diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json new file mode 100644 index 000000000..7825f75c3 --- /dev/null +++ b/dev/.documenter-siteinfo.json @@ -0,0 +1 @@ +{"documenter":{"julia_version":"1.10.1","generation_timestamp":"2024-02-22T13:36:51","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/dev/assets/biglogo-blacktheme.svg b/dev/assets/biglogo-blacktheme.svg new file mode 100644 index 000000000..101ebb89d --- /dev/null +++ b/dev/assets/biglogo-blacktheme.svg @@ -0,0 +1,55 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/assets/biglogo.svg b/dev/assets/biglogo.svg new file mode 100644 index 000000000..b9f3d9f8e --- /dev/null +++ b/dev/assets/biglogo.svg @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/dev/assets/documenter.js b/dev/assets/documenter.js new file mode 100644 index 000000000..f5311607b --- /dev/null +++ b/dev/assets/documenter.js @@ -0,0 +1,889 @@ +// Generated by Documenter.jl +requirejs.config({ + paths: { + 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', + 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', + 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', + 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', + 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', + 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', + 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', + 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min', + 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min', + 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia-repl.min', + }, + shim: { + "highlight-julia": { + "deps": [ + "highlight" + ] + }, + "katex-auto-render": { + "deps": [ + "katex" + ] + }, + "headroom-jquery": { + "deps": [ + "jquery", + "headroom" + ] + }, + "highlight-julia-repl": { + "deps": [ + "highlight" + ] + } +} +}); +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'katex', 'katex-auto-render'], function($, katex, renderMathInElement) { +$(document).ready(function() { + renderMathInElement( + document.body, + { + "delimiters": [ + { + "left": "$", + "right": "$", + "display": false + }, + { + "left": "$$", + "right": "$$", + "display": true + }, + { + "left": "\\[", + "right": "\\]", + "display": true + } + ] +} + + ); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'highlight', 'highlight-julia', 'highlight-julia-repl'], function($) { +$(document).ready(function() { + hljs.highlightAll(); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let timer = 0; +var isExpanded = true; + +$(document).on("click", ".docstring header", function () { + let articleToggleTitle = "Expand docstring"; + + debounce(() => { + if ($(this).siblings("section").is(":visible")) { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + } else { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + articleToggleTitle = "Collapse docstring"; + } + + $(this) + .find(".docstring-article-toggle-button") + .prop("title", articleToggleTitle); + $(this).siblings("section").slideToggle(); + }); +}); + +$(document).on("click", ".docs-article-toggle-button", function () { + let articleToggleTitle = "Expand docstring"; + let navArticleToggleTitle = "Expand all docstrings"; + + debounce(() => { + if (isExpanded) { + $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + + isExpanded = false; + + $(".docstring section").slideUp(); + } else { + $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + isExpanded = true; + articleToggleTitle = "Collapse docstring"; + navArticleToggleTitle = "Collapse all docstrings"; + + $(".docstring section").slideDown(); + } + + $(this).prop("title", navArticleToggleTitle); + $(".docstring-article-toggle-button").prop("title", articleToggleTitle); + }); +}); + +function debounce(callback, timeout = 300) { + if (Date.now() - timer > timeout) { + callback(); + } + + clearTimeout(timer); + + timer = Date.now(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require([], function() { +function addCopyButtonCallbacks() { + for (const el of document.getElementsByTagName("pre")) { + const button = document.createElement("button"); + button.classList.add("copy-button", "fa-solid", "fa-copy"); + button.setAttribute("aria-label", "Copy this code block"); + button.setAttribute("title", "Copy"); + + el.appendChild(button); + + const success = function () { + button.classList.add("success", "fa-check"); + button.classList.remove("fa-copy"); + }; + + const failure = function () { + button.classList.add("error", "fa-xmark"); + button.classList.remove("fa-copy"); + }; + + button.addEventListener("click", function () { + copyToClipboard(el.innerText).then(success, failure); + + setTimeout(function () { + button.classList.add("fa-copy"); + button.classList.remove("success", "fa-check", "fa-xmark"); + }, 5000); + }); + } +} + +function copyToClipboard(text) { + // clipboard API is only available in secure contexts + if (window.navigator && window.navigator.clipboard) { + return window.navigator.clipboard.writeText(text); + } else { + return new Promise(function (resolve, reject) { + try { + const el = document.createElement("textarea"); + el.textContent = text; + el.style.position = "fixed"; + el.style.opacity = 0; + document.body.appendChild(el); + el.select(); + document.execCommand("copy"); + + resolve(); + } catch (err) { + reject(err); + } finally { + document.body.removeChild(el); + } + }); + } +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addCopyButtonCallbacks); +} else { + addCopyButtonCallbacks(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'headroom', 'headroom-jquery'], function($, Headroom) { + +// Manages the top navigation bar (hides it when the user starts scrolling down on the +// mobile). +window.Headroom = Headroom; // work around buggy module loading? +$(document).ready(function () { + $("#documenter .docs-navbar").headroom({ + tolerance: { up: 10, down: 10 }, + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'minisearch'], function($, minisearch) { + +// In general, most search related things will have "search" as a prefix. +// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +let results = []; +let timer = undefined; + +let data = documenterSearchIndex["docs"].map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; +}); + +// list below is the lunr 2.1.3 list minus the intersect with names(Base) +// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) +// ideally we'd just filter the original list but it's not available as a variable +const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", +]); + +let index = new minisearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification + tokenize: (string) => string.split(/[\s\-\.]+/), + // options which will be applied during the search + searchOptions: { + boost: { title: 100 }, + fuzzy: 2, + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + tokenize: (string) => string.split(/[\s\-\.]+/), + }, +}); + +index.addAll(data); + +let filters = [...new Set(data.map((x) => x.category))]; +var modal_filters = make_modal_body_filters(filters); +var filter_results = []; + +$(document).on("keyup", ".documenter-search-input", function (event) { + // Adding a debounce to prevent disruptions from super-speed typing! + debounce(() => update_search(filter_results), 300); +}); + +$(document).on("click", ".search-filter", function () { + if ($(this).hasClass("search-filter-selected")) { + $(this).removeClass("search-filter-selected"); + } else { + $(this).addClass("search-filter-selected"); + } + + // Adding a debounce to prevent disruptions from crazy clicking! + debounce(() => get_filters(), 300); +}); + +/** + * A debounce function, takes a function and an optional timeout in milliseconds + * + * @function callback + * @param {number} timeout + */ +function debounce(callback, timeout = 300) { + clearTimeout(timer); + timer = setTimeout(callback, timeout); +} + +/** + * Make/Update the search component + * + * @param {string[]} selected_filters + */ +function update_search(selected_filters = []) { + let initial_search_body = ` +
Type something to get started!
+ `; + + let querystring = $(".documenter-search-input").val(); + + if (querystring.trim()) { + results = index.search(querystring, { + filter: (result) => { + // Filtering results + if (selected_filters.length === 0) { + return result.score >= 1; + } else { + return ( + result.score >= 1 && selected_filters.includes(result.category) + ); + } + }, + }); + + let search_result_container = ``; + let search_divider = `
`; + + if (results.length) { + let links = []; + let count = 0; + let search_results = ""; + + results.forEach(function (result) { + if (result.location) { + // Checking for duplication of results for the same page + if (!links.includes(result.location)) { + search_results += make_search_result(result, querystring); + count++; + } + + links.push(result.location); + } + }); + + let result_count = `
${count} result(s)
`; + + search_result_container = ` +
+ ${modal_filters} + ${search_divider} + ${result_count} +
+ ${search_results} +
+
+ `; + } else { + search_result_container = ` +
+ ${modal_filters} + ${search_divider} +
0 result(s)
+
+
No result found!
+ `; + } + + if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").removeClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(search_result_container); + } else { + filter_results = []; + modal_filters = make_modal_body_filters(filters, filter_results); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(initial_search_body); + } +} + +/** + * Make the modal filter html + * + * @param {string[]} filters + * @param {string[]} selected_filters + * @returns string + */ +function make_modal_body_filters(filters, selected_filters = []) { + let str = ``; + + filters.forEach((val) => { + if (selected_filters.includes(val)) { + str += `${val}`; + } else { + str += `${val}`; + } + }); + + let filter_html = ` +
+ Filters: + ${str} +
+ `; + + return filter_html; +} + +/** + * Make the result component given a minisearch result data object and the value of the search input as queryString. + * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ +function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } + + let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${result.title}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; +} + +/** + * Get selected filters, remake the filter html and lastly update the search modal + */ +function get_filters() { + let ele = $(".search-filters .search-filter-selected").get(); + filter_results = ele.map((x) => $(x).text().toLowerCase()); + modal_filters = make_modal_body_filters(filters, filter_results); + update_search(filter_results); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Modal settings dialog +$(document).ready(function () { + var settings = $("#documenter-settings"); + $("#documenter-settings-button").click(function () { + settings.toggleClass("is-active"); + }); + // Close the dialog if X is clicked + $("#documenter-settings button.delete").click(function () { + settings.removeClass("is-active"); + }); + // Close dialog if ESC is pressed + $(document).keyup(function (e) { + if (e.keyCode == 27) settings.removeClass("is-active"); + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let search_modal_header = ` +
+
+

+ + + + +

+
+
+ +
+
+`; + +let initial_search_body = ` +
Type something to get started!
+`; + +let search_modal_footer = ` + +`; + +$(document.body).append( + ` + + ` +); + +document.querySelector(".docs-search-query").addEventListener("click", () => { + openModal(); +}); + +document.querySelector(".close-search-modal").addEventListener("click", () => { + closeModal(); +}); + +$(document).on("click", ".search-result-link", function () { + closeModal(); +}); + +document.addEventListener("keydown", (event) => { + if ((event.ctrlKey || event.metaKey) && event.key === "/") { + openModal(); + } else if (event.key === "Escape") { + closeModal(); + } + + return false; +}); + +// Functions to open and close a modal +function openModal() { + let searchModal = document.querySelector("#search-modal"); + + searchModal.classList.add("is-active"); + document.querySelector(".documenter-search-input").focus(); +} + +function closeModal() { + let searchModal = document.querySelector("#search-modal"); + let initial_search_body = ` +
Type something to get started!
+ `; + + searchModal.classList.remove("is-active"); + document.querySelector(".documenter-search-input").blur(); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".documenter-search-input").val(""); + $(".search-modal-card-body").html(initial_search_body); +} + +document + .querySelector("#search-modal .modal-background") + .addEventListener("click", () => { + closeModal(); + }); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Manages the showing and hiding of the sidebar. +$(document).ready(function () { + var sidebar = $("#documenter > .docs-sidebar"); + var sidebar_button = $("#documenter-sidebar-button"); + sidebar_button.click(function (ev) { + ev.preventDefault(); + sidebar.toggleClass("visible"); + if (sidebar.hasClass("visible")) { + // Makes sure that the current menu item is visible in the sidebar. + $("#documenter .docs-menu a.is-active").focus(); + } + }); + $("#documenter > .docs-main").bind("click", function (ev) { + if ($(ev.target).is(sidebar_button)) { + return; + } + if (sidebar.hasClass("visible")) { + sidebar.removeClass("visible"); + } + }); +}); + +// Resizes the package name / sitename in the sidebar if it is too wide. +// Inspired by: https://github.com/davatron5000/FitText.js +$(document).ready(function () { + e = $("#documenter .docs-autofit"); + function resize() { + var L = parseInt(e.css("max-width"), 10); + var L0 = e.width(); + if (L0 > L) { + var h0 = parseInt(e.css("font-size"), 10); + e.css("font-size", (L * h0) / L0); + // TODO: make sure it survives resizes? + } + } + // call once and then register events + resize(); + $(window).resize(resize); + $(window).on("orientationchange", resize); +}); + +// Scroll the navigation bar to the currently selected menu item +$(document).ready(function () { + var sidebar = $("#documenter .docs-menu").get(0); + var active = $("#documenter .docs-menu .is-active").get(0); + if (typeof active !== "undefined") { + sidebar.scrollTop = active.offsetTop - sidebar.offsetTop - 15; + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Theme picker setup +$(document).ready(function () { + // onchange callback + $("#documenter-themepicker").change(function themepick_callback(ev) { + var themename = $("#documenter-themepicker option:selected").attr("value"); + if (themename === "auto") { + // set_theme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'); + window.localStorage.removeItem("documenter-theme"); + } else { + // set_theme(themename); + window.localStorage.setItem("documenter-theme", themename); + } + // We re-use the global function from themeswap.js to actually do the swapping. + set_theme_from_local_storage(); + }); + + // Make sure that the themepicker displays the correct theme when the theme is retrieved + // from localStorage + if (typeof window.localStorage !== "undefined") { + var theme = window.localStorage.getItem("documenter-theme"); + if (theme !== null) { + $("#documenter-themepicker option").each(function (i, e) { + e.selected = e.value === theme; + }); + } + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// update the version selector with info from the siteinfo.js and ../versions.js files +$(document).ready(function () { + // If the version selector is disabled with DOCUMENTER_VERSION_SELECTOR_DISABLED in the + // siteinfo.js file, we just return immediately and not display the version selector. + if ( + typeof DOCUMENTER_VERSION_SELECTOR_DISABLED === "boolean" && + DOCUMENTER_VERSION_SELECTOR_DISABLED + ) { + return; + } + + var version_selector = $("#documenter .docs-version-selector"); + var version_selector_select = $("#documenter .docs-version-selector select"); + + version_selector_select.change(function (x) { + target_href = version_selector_select + .children("option:selected") + .get(0).value; + window.location.href = target_href; + }); + + // add the current version to the selector based on siteinfo.js, but only if the selector is empty + if ( + typeof DOCUMENTER_CURRENT_VERSION !== "undefined" && + $("#version-selector > option").length == 0 + ) { + var option = $( + "" + ); + version_selector_select.append(option); + } + + if (typeof DOC_VERSIONS !== "undefined") { + var existing_versions = version_selector_select.children("option"); + var existing_versions_texts = existing_versions.map(function (i, x) { + return x.text; + }); + DOC_VERSIONS.forEach(function (each) { + var version_url = documenterBaseURL + "/../" + each + "/"; + var existing_id = $.inArray(each, existing_versions_texts); + // if not already in the version selector, add it as a new option, + // otherwise update the old option with the URL and enable it + if (existing_id == -1) { + var option = $( + "" + ); + version_selector_select.append(option); + } else { + var option = existing_versions[existing_id]; + option.value = version_url; + option.disabled = false; + } + }); + } + + // only show the version selector if the selector has been populated + if (version_selector_select.children("option").length > 0) { + version_selector.toggleClass("visible"); + } +}); + +}) diff --git a/dev/assets/examples/Active Inference Mountain car_4_1.png b/dev/assets/examples/Active Inference Mountain car_4_1.png new file mode 100644 index 000000000..9394d1730 Binary files /dev/null and b/dev/assets/examples/Active Inference Mountain car_4_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_12_1.png b/dev/assets/examples/Autoregressive Models_12_1.png new file mode 100644 index 000000000..5f7b543d9 Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_12_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_13_1.png b/dev/assets/examples/Autoregressive Models_13_1.png new file mode 100644 index 000000000..99416e777 Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_13_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_14_1.png b/dev/assets/examples/Autoregressive Models_14_1.png new file mode 100644 index 000000000..e4b52db2e Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_14_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_24_1.png b/dev/assets/examples/Autoregressive Models_24_1.png new file mode 100644 index 000000000..92d942e95 Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_24_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_32_1.png b/dev/assets/examples/Autoregressive Models_32_1.png new file mode 100644 index 000000000..9b30d0046 Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_32_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_36_1.png b/dev/assets/examples/Autoregressive Models_36_1.png new file mode 100644 index 000000000..047100331 Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_36_1.png differ diff --git a/dev/assets/examples/Autoregressive Models_6_1.png b/dev/assets/examples/Autoregressive Models_6_1.png new file mode 100644 index 000000000..309eadff5 Binary files /dev/null and b/dev/assets/examples/Autoregressive Models_6_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_10_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_10_1.png new file mode 100644 index 000000000..4ecb12eef Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_10_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_12_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_12_1.png new file mode 100644 index 000000000..21f2cf9b8 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_12_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_14_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_14_1.png new file mode 100644 index 000000000..d35fb5850 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_14_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_15_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_15_1.png new file mode 100644 index 000000000..8068d76e2 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_15_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_16_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_16_1.png new file mode 100644 index 000000000..2dd3fcb12 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_16_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_17_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_17_1.png new file mode 100644 index 000000000..ddcc56f62 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_17_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_18_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_18_1.png new file mode 100644 index 000000000..fc9c0743a Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_18_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_21_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_21_1.png new file mode 100644 index 000000000..157bce417 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_21_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_24_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_24_1.png new file mode 100644 index 000000000..332e6707d Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_24_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_25_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_25_1.png new file mode 100644 index 000000000..da8387995 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_25_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_26_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_26_1.png new file mode 100644 index 000000000..0b3299f1c Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_26_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_27_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_27_1.png new file mode 100644 index 000000000..dc2785db5 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_27_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_34_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_34_1.png new file mode 100644 index 000000000..e935ce86c Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_34_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_40_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_40_1.png new file mode 100644 index 000000000..a7f23a09f Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_40_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_42_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_42_1.png new file mode 100644 index 000000000..3249d9b3c Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_42_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_4_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_4_1.png new file mode 100644 index 000000000..3851d2ea5 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_4_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_51_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_51_1.png new file mode 100644 index 000000000..df1ae996a Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_51_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_54_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_54_1.png new file mode 100644 index 000000000..8da279955 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_54_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_55_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_55_1.png new file mode 100644 index 000000000..ca615bf2c Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_55_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_7_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_7_1.png new file mode 100644 index 000000000..564b04161 Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_7_1.png differ diff --git a/dev/assets/examples/Bayesian Linear Regression Tutorial_8_1.png b/dev/assets/examples/Bayesian Linear Regression Tutorial_8_1.png new file mode 100644 index 000000000..b86dc84cd Binary files /dev/null and b/dev/assets/examples/Bayesian Linear Regression Tutorial_8_1.png differ diff --git a/dev/assets/examples/Chance Constraints_11_1.png b/dev/assets/examples/Chance Constraints_11_1.png new file mode 100644 index 000000000..b7b9be536 Binary files /dev/null and b/dev/assets/examples/Chance Constraints_11_1.png differ diff --git a/dev/assets/examples/Coin Toss Model_7_1.png b/dev/assets/examples/Coin Toss Model_7_1.png new file mode 100644 index 000000000..180821d61 Binary files /dev/null and b/dev/assets/examples/Coin Toss Model_7_1.png differ diff --git a/dev/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png b/dev/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png new file mode 100644 index 000000000..d90df26c0 Binary files /dev/null and b/dev/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png differ diff --git a/dev/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png b/dev/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png new file mode 100644 index 000000000..14f524963 Binary files /dev/null and b/dev/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png differ diff --git a/dev/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png b/dev/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png new file mode 100644 index 000000000..2e19804fb Binary files /dev/null and b/dev/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png differ diff --git a/dev/assets/examples/GP Regression by SSM_10_1.png b/dev/assets/examples/GP Regression by SSM_10_1.png new file mode 100644 index 000000000..be25d53d3 Binary files /dev/null and b/dev/assets/examples/GP Regression by SSM_10_1.png differ diff --git a/dev/assets/examples/GP Regression by SSM_5_1.png b/dev/assets/examples/GP Regression by SSM_5_1.png new file mode 100644 index 000000000..3246e6256 Binary files /dev/null and b/dev/assets/examples/GP Regression by SSM_5_1.png differ diff --git a/dev/assets/examples/Gamma Mixture_10_1.png b/dev/assets/examples/Gamma Mixture_10_1.png new file mode 100644 index 000000000..bd8ce343b Binary files /dev/null and b/dev/assets/examples/Gamma Mixture_10_1.png differ diff --git a/dev/assets/examples/Gaussian Mixture_12_1.png b/dev/assets/examples/Gaussian Mixture_12_1.png new file mode 100644 index 000000000..fc21b9942 Binary files /dev/null and b/dev/assets/examples/Gaussian Mixture_12_1.png differ diff --git a/dev/assets/examples/Gaussian Mixture_4_1.png b/dev/assets/examples/Gaussian Mixture_4_1.png new file mode 100644 index 000000000..aedf37236 Binary files /dev/null and b/dev/assets/examples/Gaussian Mixture_4_1.png differ diff --git a/dev/assets/examples/Gaussian Mixture_7_1.png b/dev/assets/examples/Gaussian Mixture_7_1.png new file mode 100644 index 000000000..338fe2092 Binary files /dev/null and b/dev/assets/examples/Gaussian Mixture_7_1.png differ diff --git a/dev/assets/examples/Gaussian Mixture_9_1.png b/dev/assets/examples/Gaussian Mixture_9_1.png new file mode 100644 index 000000000..64adeef14 Binary files /dev/null and b/dev/assets/examples/Gaussian Mixture_9_1.png differ diff --git a/dev/assets/examples/Global Parameter Optimisation_14_1.png b/dev/assets/examples/Global Parameter Optimisation_14_1.png new file mode 100644 index 000000000..70f61d1cf Binary files /dev/null and b/dev/assets/examples/Global Parameter Optimisation_14_1.png differ diff --git a/dev/assets/examples/Global Parameter Optimisation_18_1.png b/dev/assets/examples/Global Parameter Optimisation_18_1.png new file mode 100644 index 000000000..eac50a682 Binary files /dev/null and b/dev/assets/examples/Global Parameter Optimisation_18_1.png differ diff --git a/dev/assets/examples/Global Parameter Optimisation_22_1.png b/dev/assets/examples/Global Parameter Optimisation_22_1.png new file mode 100644 index 000000000..c24630442 Binary files /dev/null and b/dev/assets/examples/Global Parameter Optimisation_22_1.png differ diff --git a/dev/assets/examples/Global Parameter Optimisation_28_1.png b/dev/assets/examples/Global Parameter Optimisation_28_1.png new file mode 100644 index 000000000..98706ec52 Binary files /dev/null and b/dev/assets/examples/Global Parameter Optimisation_28_1.png differ diff --git a/dev/assets/examples/Global Parameter Optimisation_32_1.png b/dev/assets/examples/Global Parameter Optimisation_32_1.png new file mode 100644 index 000000000..cf55c8da0 Binary files /dev/null and b/dev/assets/examples/Global Parameter Optimisation_32_1.png differ diff --git a/dev/assets/examples/Global Parameter Optimisation_35_1.png b/dev/assets/examples/Global Parameter Optimisation_35_1.png new file mode 100644 index 000000000..fddb20942 Binary files /dev/null and b/dev/assets/examples/Global Parameter Optimisation_35_1.png differ diff --git a/dev/assets/examples/Hidden Markov Model_4_1.png b/dev/assets/examples/Hidden Markov Model_4_1.png new file mode 100644 index 000000000..a15a96215 Binary files /dev/null and b/dev/assets/examples/Hidden Markov Model_4_1.png differ diff --git a/dev/assets/examples/Hidden Markov Model_9_1.png b/dev/assets/examples/Hidden Markov Model_9_1.png new file mode 100644 index 000000000..32d9bbc46 Binary files /dev/null and b/dev/assets/examples/Hidden Markov Model_9_1.png differ diff --git a/dev/assets/examples/Hierarchical Gaussian Filter_10_1.png b/dev/assets/examples/Hierarchical Gaussian Filter_10_1.png new file mode 100644 index 000000000..6a3b9c9dc Binary files /dev/null and b/dev/assets/examples/Hierarchical Gaussian Filter_10_1.png differ diff --git a/dev/assets/examples/Hierarchical Gaussian Filter_5_1.png b/dev/assets/examples/Hierarchical Gaussian Filter_5_1.png new file mode 100644 index 000000000..2d74bff5a Binary files /dev/null and b/dev/assets/examples/Hierarchical Gaussian Filter_5_1.png differ diff --git a/dev/assets/examples/Hierarchical Gaussian Filter_9_1.png b/dev/assets/examples/Hierarchical Gaussian Filter_9_1.png new file mode 100644 index 000000000..9821f6bc9 Binary files /dev/null and b/dev/assets/examples/Hierarchical Gaussian Filter_9_1.png differ diff --git a/dev/assets/examples/Infinite Data Stream_11_1.png b/dev/assets/examples/Infinite Data Stream_11_1.png new file mode 100644 index 000000000..0d1e48052 Binary files /dev/null and b/dev/assets/examples/Infinite Data Stream_11_1.png differ diff --git a/dev/assets/examples/Invertible Neural Network Tutorial_10_1.png b/dev/assets/examples/Invertible Neural Network Tutorial_10_1.png new file mode 100644 index 000000000..009e76bec Binary files /dev/null and b/dev/assets/examples/Invertible Neural Network Tutorial_10_1.png differ diff --git a/dev/assets/examples/Invertible Neural Network Tutorial_14_1.png b/dev/assets/examples/Invertible Neural Network Tutorial_14_1.png new file mode 100644 index 000000000..95edfacc0 Binary files /dev/null and b/dev/assets/examples/Invertible Neural Network Tutorial_14_1.png differ diff --git a/dev/assets/examples/Invertible Neural Network Tutorial_15_1.png b/dev/assets/examples/Invertible Neural Network Tutorial_15_1.png new file mode 100644 index 000000000..ab077a912 Binary files /dev/null and b/dev/assets/examples/Invertible Neural Network Tutorial_15_1.png differ diff --git a/dev/assets/examples/Invertible Neural Network Tutorial_17_1.png b/dev/assets/examples/Invertible Neural Network Tutorial_17_1.png new file mode 100644 index 000000000..201b882c0 Binary files /dev/null and b/dev/assets/examples/Invertible Neural Network Tutorial_17_1.png differ diff --git a/dev/assets/examples/Invertible Neural Network Tutorial_23_1.png b/dev/assets/examples/Invertible Neural Network Tutorial_23_1.png new file mode 100644 index 000000000..a639d283d Binary files /dev/null and b/dev/assets/examples/Invertible Neural Network Tutorial_23_1.png differ diff --git a/dev/assets/examples/Invertible Neural Network Tutorial_24_1.png b/dev/assets/examples/Invertible Neural Network Tutorial_24_1.png new file mode 100644 index 000000000..b38e5ab4e Binary files /dev/null and b/dev/assets/examples/Invertible Neural Network Tutorial_24_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_10_1.png b/dev/assets/examples/Kalman filtering and smoothing_10_1.png new file mode 100644 index 000000000..404cd2073 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_10_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_15_1.png b/dev/assets/examples/Kalman filtering and smoothing_15_1.png new file mode 100644 index 000000000..387f83e00 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_15_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_20_1.png b/dev/assets/examples/Kalman filtering and smoothing_20_1.png new file mode 100644 index 000000000..0332168c8 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_20_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_23_1.png b/dev/assets/examples/Kalman filtering and smoothing_23_1.png new file mode 100644 index 000000000..3997d6305 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_23_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_25_1.png b/dev/assets/examples/Kalman filtering and smoothing_25_1.png new file mode 100644 index 000000000..baae896e0 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_25_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_30_1.png b/dev/assets/examples/Kalman filtering and smoothing_30_1.png new file mode 100644 index 000000000..0ca63d89e Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_30_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_33_1.png b/dev/assets/examples/Kalman filtering and smoothing_33_1.png new file mode 100644 index 000000000..230f9e497 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_33_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_39_1.png b/dev/assets/examples/Kalman filtering and smoothing_39_1.png new file mode 100644 index 000000000..1157e61d1 Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_39_1.png differ diff --git a/dev/assets/examples/Kalman filtering and smoothing_6_1.png b/dev/assets/examples/Kalman filtering and smoothing_6_1.png new file mode 100644 index 000000000..868c31a7a Binary files /dev/null and b/dev/assets/examples/Kalman filtering and smoothing_6_1.png differ diff --git a/dev/assets/examples/Nonlinear Sensor Fusion_12_1.png b/dev/assets/examples/Nonlinear Sensor Fusion_12_1.png new file mode 100644 index 000000000..b2722f776 Binary files /dev/null and b/dev/assets/examples/Nonlinear Sensor Fusion_12_1.png differ diff --git a/dev/assets/examples/Nonlinear Sensor Fusion_17_1.png b/dev/assets/examples/Nonlinear Sensor Fusion_17_1.png new file mode 100644 index 000000000..4d1e2bd3c Binary files /dev/null and b/dev/assets/examples/Nonlinear Sensor Fusion_17_1.png differ diff --git a/dev/assets/examples/Nonlinear Sensor Fusion_4_1.png b/dev/assets/examples/Nonlinear Sensor Fusion_4_1.png new file mode 100644 index 000000000..6be9531bf Binary files /dev/null and b/dev/assets/examples/Nonlinear Sensor Fusion_4_1.png differ diff --git a/dev/assets/examples/Predicting Bike Rental Demand_17_1.png b/dev/assets/examples/Predicting Bike Rental Demand_17_1.png new file mode 100644 index 000000000..49ebabbfb Binary files /dev/null and b/dev/assets/examples/Predicting Bike Rental Demand_17_1.png differ diff --git a/dev/assets/examples/Predicting Bike Rental Demand_18_1.png b/dev/assets/examples/Predicting Bike Rental Demand_18_1.png new file mode 100644 index 000000000..ed7f08607 Binary files /dev/null and b/dev/assets/examples/Predicting Bike Rental Demand_18_1.png differ diff --git a/dev/assets/examples/Probit Model (EP)_6_1.png b/dev/assets/examples/Probit Model (EP)_6_1.png new file mode 100644 index 000000000..b9b15d04b Binary files /dev/null and b/dev/assets/examples/Probit Model (EP)_6_1.png differ diff --git a/dev/assets/examples/Probit Model (EP)_9_1.png b/dev/assets/examples/Probit Model (EP)_9_1.png new file mode 100644 index 000000000..baf1f1c80 Binary files /dev/null and b/dev/assets/examples/Probit Model (EP)_9_1.png differ diff --git a/dev/assets/examples/RTS vs BIFM Smoothing_11_1.png b/dev/assets/examples/RTS vs BIFM Smoothing_11_1.png new file mode 100644 index 000000000..66e32249a Binary files /dev/null and b/dev/assets/examples/RTS vs BIFM Smoothing_11_1.png differ diff --git a/dev/assets/examples/RTS vs BIFM Smoothing_12_1.png b/dev/assets/examples/RTS vs BIFM Smoothing_12_1.png new file mode 100644 index 000000000..c84567e8d Binary files /dev/null and b/dev/assets/examples/RTS vs BIFM Smoothing_12_1.png differ diff --git a/dev/assets/examples/RTS vs BIFM Smoothing_5_1.png b/dev/assets/examples/RTS vs BIFM Smoothing_5_1.png new file mode 100644 index 000000000..54e877de1 Binary files /dev/null and b/dev/assets/examples/RTS vs BIFM Smoothing_5_1.png differ diff --git a/dev/assets/examples/Simple Nonlinear Node_14_1.png b/dev/assets/examples/Simple Nonlinear Node_14_1.png new file mode 100644 index 000000000..75ac00028 Binary files /dev/null and b/dev/assets/examples/Simple Nonlinear Node_14_1.png differ diff --git a/dev/assets/examples/Tiny Benchmark_11_1.png b/dev/assets/examples/Tiny Benchmark_11_1.png new file mode 100644 index 000000000..97ee402ca Binary files /dev/null and b/dev/assets/examples/Tiny Benchmark_11_1.png differ diff --git a/dev/assets/examples/Tiny Benchmark_7_1.png b/dev/assets/examples/Tiny Benchmark_7_1.png new file mode 100644 index 000000000..36c08b460 Binary files /dev/null and b/dev/assets/examples/Tiny Benchmark_7_1.png differ diff --git a/dev/assets/examples/Universal Mixtures_10_1.png b/dev/assets/examples/Universal Mixtures_10_1.png new file mode 100644 index 000000000..fd23f884a Binary files /dev/null and b/dev/assets/examples/Universal Mixtures_10_1.png differ diff --git a/dev/assets/examples/Universal Mixtures_13_1.png b/dev/assets/examples/Universal Mixtures_13_1.png new file mode 100644 index 000000000..cf2c5244c Binary files /dev/null and b/dev/assets/examples/Universal Mixtures_13_1.png differ diff --git a/dev/assets/examples/Universal Mixtures_3_1.png b/dev/assets/examples/Universal Mixtures_3_1.png new file mode 100644 index 000000000..cec0904cc Binary files /dev/null and b/dev/assets/examples/Universal Mixtures_3_1.png differ diff --git a/dev/assets/examples/Universal Mixtures_9_1.png b/dev/assets/examples/Universal Mixtures_9_1.png new file mode 100644 index 000000000..a6c946c8b Binary files /dev/null and b/dev/assets/examples/Universal Mixtures_9_1.png differ diff --git a/dev/assets/examples/pics/ai-mountain-car-ai.gif b/dev/assets/examples/pics/ai-mountain-car-ai.gif new file mode 100644 index 000000000..87f6cc774 Binary files /dev/null and b/dev/assets/examples/pics/ai-mountain-car-ai.gif differ diff --git a/dev/assets/examples/pics/ai-mountain-car-naive.gif b/dev/assets/examples/pics/ai-mountain-car-naive.gif new file mode 100644 index 000000000..80fdf4e1c Binary files /dev/null and b/dev/assets/examples/pics/ai-mountain-car-naive.gif differ diff --git a/dev/assets/examples/pics/hblr-matrix-completion.jpeg b/dev/assets/examples/pics/hblr-matrix-completion.jpeg new file mode 100644 index 000000000..be0f78e1c Binary files /dev/null and b/dev/assets/examples/pics/hblr-matrix-completion.jpeg differ diff --git a/dev/assets/examples/pics/infinite-data-stream-inference.gif b/dev/assets/examples/pics/infinite-data-stream-inference.gif new file mode 100644 index 000000000..34ca16f56 Binary files /dev/null and b/dev/assets/examples/pics/infinite-data-stream-inference.gif differ diff --git a/dev/assets/examples/pics/infinite-data-stream.gif b/dev/assets/examples/pics/infinite-data-stream.gif new file mode 100644 index 000000000..5455f9437 Binary files /dev/null and b/dev/assets/examples/pics/infinite-data-stream.gif differ diff --git a/dev/assets/examples/pics/online-coin-bias-inference.gif b/dev/assets/examples/pics/online-coin-bias-inference.gif new file mode 100644 index 000000000..59a505632 Binary files /dev/null and b/dev/assets/examples/pics/online-coin-bias-inference.gif differ diff --git a/dev/assets/examples/pics/pipeline.png b/dev/assets/examples/pics/pipeline.png new file mode 100644 index 000000000..d8302e166 Binary files /dev/null and b/dev/assets/examples/pics/pipeline.png differ diff --git a/dev/assets/examples/pics/posterior.png b/dev/assets/examples/pics/posterior.png new file mode 100644 index 000000000..4fa49edff Binary files /dev/null and b/dev/assets/examples/pics/posterior.png differ diff --git a/dev/assets/examples/pics/rts_bifm_benchmark.png b/dev/assets/examples/pics/rts_bifm_benchmark.png new file mode 100644 index 000000000..51a066062 Binary files /dev/null and b/dev/assets/examples/pics/rts_bifm_benchmark.png differ diff --git a/dev/assets/examples/pics/sp.png b/dev/assets/examples/pics/sp.png new file mode 100644 index 000000000..dedc65431 Binary files /dev/null and b/dev/assets/examples/pics/sp.png differ diff --git a/dev/assets/examples/pics/vmp.png b/dev/assets/examples/pics/vmp.png new file mode 100644 index 000000000..0561f27e3 Binary files /dev/null and b/dev/assets/examples/pics/vmp.png differ diff --git a/dev/assets/header.css b/dev/assets/header.css new file mode 100644 index 000000000..155b10a3b --- /dev/null +++ b/dev/assets/header.css @@ -0,0 +1,138 @@ + +@media all and (max-width: 560px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar { + min-height: 1rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + min-height: 1rem !important; + margin-left: 0.5rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: visible !important; + display: block !important; + margin: 0.5rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + visibility: hidden; + display: none; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a { + visibility: hidden; + display: none; + } + + html:not(.theme--documenter-dark) body #documenter .docs-main { + margin-top: 2rem !important; + } +} + +@media all and (max-width: 1055px) and (min-width: 561px){ + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + width: 80% !important; + } +} + +@media all and (min-width: 1056px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 18rem; + } + +} + +html.theme--documenter-dark header.navigation { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container { + border-bottom: 1px solid #5e6d6f; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: white; + transition: color 100ms; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +html header.navigation { + background-color: white !important; +} + +html header.navigation div.container { + border-bottom: 1px solid #dbdbdb; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: #222; + transition: color 100ms; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +header.navigation { + z-index: 3; +} + +header.navigation div.container nav.navbar ul.navbar-nav { + margin-left: 4rem; + min-height: 3.25rem; + width: 70%; + display: flex; + align-self: auto; + flex-direction: row; + justify-content: space-around; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + align-self: stretch; + align-content: space-around; + justify-content: center; + display: flex; + flex-direction: column; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: hidden; + display: none; +} \ No newline at end of file diff --git a/dev/assets/header.js b/dev/assets/header.js new file mode 100644 index 000000000..7f15cae83 --- /dev/null +++ b/dev/assets/header.js @@ -0,0 +1,97 @@ + +// We add a simple `onload` hook to inject the custom header for our `HTML`-generated pages +window.onload = function() { + //
+ const header = document.createElement('header') + header.classList.add("navigation") + header.appendChild((() => { + const container = document.createElement('div') + container.classList.add('container') + container.appendChild((() => { + const nav = document.createElement('nav') + nav.classList.add("navbar") + + nav.appendChild((() => { + const ul = document.createElement("ul") + ul.classList.add("navbar-nav") + + ul.appendChild((() => { + const smalllink = document.createElement('li') + smalllink.classList.add('small-item') + smalllink.appendChild((() => { + const a = document.createElement('a') + a.classList.add("nav-link") + a.href = 'http://www.rxinfer.ml' + a.innerHTML = 'RxInfer.jl' + a.title = 'RxInfer.jl' + return a + })()) + return smalllink + })()) + + const items = [ + { title: "Home", link: "http://www.rxinfer.ml", icon: [ "fas", "fa-diagram-project" ] }, + { title: "Get Started", link: "https://reactivebayes.github.io/RxInfer.jl/stable/manuals/getting-started/" }, + { title: "Documentation", link: "https://reactivebayes.github.io/RxInfer.jl/stable/" }, + { title: "Examples", link: "https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/" }, + { title: "Papers", link: "https://reactivebayes.github.io/publication/" }, + { title: "Team", link: "https://reactivebayes.github.io/team/" }, + // { title: "Contact", link: "http://www.rxinfer.ml/contact/" }, the redirect is broken for now + { title: "GitHub", link: "https://github.com/reactivebayes/RxInfer.jl", icon: [ "fab", "fa-github" ] }, + ] + + items.forEach((item) => { + ul.appendChild(((item) => { + const li = document.createElement("li") + li.classList.add("nav-item") + li.appendChild((() => { + const a = document.createElement("a") + + if (item.icon !== undefined) { + a.appendChild((() => { + const i = document.createElement("i") + i.classList.add(...(item.icon)) + return i + })()) + } + + a.classList.add("nav-link") + a.href = item.link + a.title = item.title + + a.appendChild((() => { + const span = document.createElement("span") + span.innerHTML = ` ${item.title}` + return span + })()) + + return a + })()) + return li + })(item)) + }) + return ul + })()) + return nav + })()) + return container + })()) + + const documenterTarget = document.querySelector('#documenter'); + + documenterTarget.parentNode.insertBefore(header, documenterTarget); + + // Edit broken links in the examples, see issue #70 + const editOnGithubLinkTarget = document.querySelector('.docs-edit-link'); + + if (editOnGithubLinkTarget) { + const link = editOnGithubLinkTarget.href; + if (link.includes('docs/src/examples')) { + const fixedLink = link.replace('docs/src/', '').replace('.md', '.ipynb'); + editOnGithubLinkTarget.href = fixedLink; + console.log('Fixed link for the example: ', fixedLink) + } + } + +} + diff --git a/dev/assets/img/bp-message.svg b/dev/assets/img/bp-message.svg new file mode 100644 index 000000000..259b70803 --- /dev/null +++ b/dev/assets/img/bp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/dev/assets/img/coin-flip.png b/dev/assets/img/coin-flip.png new file mode 100644 index 000000000..2ed0f04c0 Binary files /dev/null and b/dev/assets/img/coin-flip.png differ diff --git a/dev/assets/img/coin-flip.svg b/dev/assets/img/coin-flip.svg new file mode 100644 index 000000000..a85960c12 --- /dev/null +++ b/dev/assets/img/coin-flip.svg @@ -0,0 +1,794 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/assets/img/debugging_graph.png b/dev/assets/img/debugging_graph.png new file mode 100644 index 000000000..b97ef1a06 Binary files /dev/null and b/dev/assets/img/debugging_graph.png differ diff --git a/dev/assets/img/debugging_messages.png b/dev/assets/img/debugging_messages.png new file mode 100644 index 000000000..8ec84e778 Binary files /dev/null and b/dev/assets/img/debugging_messages.png differ diff --git a/dev/assets/img/linear_regresion_model.png b/dev/assets/img/linear_regresion_model.png new file mode 100644 index 000000000..bb4e34422 Binary files /dev/null and b/dev/assets/img/linear_regresion_model.png differ diff --git a/dev/assets/img/release_comment.png b/dev/assets/img/release_comment.png new file mode 100644 index 000000000..743fe9614 Binary files /dev/null and b/dev/assets/img/release_comment.png differ diff --git a/dev/assets/img/vmp-message.svg b/dev/assets/img/vmp-message.svg new file mode 100644 index 000000000..475cd7f49 --- /dev/null +++ b/dev/assets/img/vmp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/dev/assets/logo-dark.svg b/dev/assets/logo-dark.svg new file mode 100644 index 000000000..63b4f65fa --- /dev/null +++ b/dev/assets/logo-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + diff --git a/dev/assets/logo.svg b/dev/assets/logo.svg new file mode 100644 index 000000000..b799e5beb --- /dev/null +++ b/dev/assets/logo.svg @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/dev/assets/theme.css b/dev/assets/theme.css new file mode 100644 index 000000000..1b060cdef --- /dev/null +++ b/dev/assets/theme.css @@ -0,0 +1,27 @@ +html body #documenter .docs-main { + margin-top: 4rem; +} + +html body #documenter .docs-sidebar.visible { + margin-top: 0px !important; +} + +html div.light-biglogo { + display: block; +} + +html.theme--documenter-dark div.light-biglogo { + display: none; +} + +html div.dark-biglogo { + display: none; +} + +html.theme--documenter-dark div.dark-biglogo { + display: block; +} + +#documenter .docs-main article.content img { + width: 100%; +} diff --git a/dev/assets/themes/documenter-dark.css b/dev/assets/themes/documenter-dark.css new file mode 100644 index 000000000..9f5449f4b --- /dev/null +++ b/dev/assets/themes/documenter-dark.css @@ -0,0 +1,7 @@ +html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:.4em;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus,html.theme--documenter-dark .pagination-ellipsis:focus,html.theme--documenter-dark .file-cta:focus,html.theme--documenter-dark .file-name:focus,html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .button:focus,html.theme--documenter-dark .is-focused.pagination-previous,html.theme--documenter-dark .is-focused.pagination-next,html.theme--documenter-dark .is-focused.pagination-link,html.theme--documenter-dark .is-focused.pagination-ellipsis,html.theme--documenter-dark .is-focused.file-cta,html.theme--documenter-dark .is-focused.file-name,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-focused.button,html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active,html.theme--documenter-dark .pagination-ellipsis:active,html.theme--documenter-dark .file-cta:active,html.theme--documenter-dark .file-name:active,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .button:active,html.theme--documenter-dark .is-active.pagination-previous,html.theme--documenter-dark .is-active.pagination-next,html.theme--documenter-dark .is-active.pagination-link,html.theme--documenter-dark .is-active.pagination-ellipsis,html.theme--documenter-dark .is-active.file-cta,html.theme--documenter-dark .is-active.file-name,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .is-active.button{outline:none}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-ellipsis[disabled],html.theme--documenter-dark .file-cta[disabled],html.theme--documenter-dark .file-name[disabled],html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark fieldset[disabled] .pagination-previous,fieldset[disabled] html.theme--documenter-dark .pagination-next,html.theme--documenter-dark fieldset[disabled] .pagination-next,fieldset[disabled] html.theme--documenter-dark .pagination-link,html.theme--documenter-dark fieldset[disabled] .pagination-link,fieldset[disabled] html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark fieldset[disabled] .pagination-ellipsis,fieldset[disabled] html.theme--documenter-dark .file-cta,html.theme--documenter-dark fieldset[disabled] .file-cta,fieldset[disabled] html.theme--documenter-dark .file-name,html.theme--documenter-dark fieldset[disabled] .file-name,fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark fieldset[disabled] .select select,html.theme--documenter-dark .select fieldset[disabled] select,html.theme--documenter-dark fieldset[disabled] .textarea,html.theme--documenter-dark fieldset[disabled] .input,html.theme--documenter-dark fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] html.theme--documenter-dark .button,html.theme--documenter-dark fieldset[disabled] .button{cursor:not-allowed}html.theme--documenter-dark .tabs,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .breadcrumb,html.theme--documenter-dark .file,html.theme--documenter-dark .button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after,html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}html.theme--documenter-dark .admonition:not(:last-child),html.theme--documenter-dark .tabs:not(:last-child),html.theme--documenter-dark .pagination:not(:last-child),html.theme--documenter-dark .message:not(:last-child),html.theme--documenter-dark .level:not(:last-child),html.theme--documenter-dark .breadcrumb:not(:last-child),html.theme--documenter-dark .block:not(:last-child),html.theme--documenter-dark .title:not(:last-child),html.theme--documenter-dark .subtitle:not(:last-child),html.theme--documenter-dark .table-container:not(:last-child),html.theme--documenter-dark .table:not(:last-child),html.theme--documenter-dark .progress:not(:last-child),html.theme--documenter-dark .notification:not(:last-child),html.theme--documenter-dark .content:not(:last-child),html.theme--documenter-dark .box:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .modal-close,html.theme--documenter-dark .delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before,html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before{height:2px;width:50%}html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{height:50%;width:2px}html.theme--documenter-dark .modal-close:hover,html.theme--documenter-dark .delete:hover,html.theme--documenter-dark .modal-close:focus,html.theme--documenter-dark .delete:focus{background-color:rgba(10,10,10,0.3)}html.theme--documenter-dark .modal-close:active,html.theme--documenter-dark .delete:active{background-color:rgba(10,10,10,0.4)}html.theme--documenter-dark .is-small.modal-close,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.modal-close,html.theme--documenter-dark .is-small.delete,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}html.theme--documenter-dark .is-medium.modal-close,html.theme--documenter-dark .is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}html.theme--documenter-dark .is-large.modal-close,html.theme--documenter-dark .is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}html.theme--documenter-dark .control.is-loading::after,html.theme--documenter-dark .select.is-loading::after,html.theme--documenter-dark .loader,html.theme--documenter-dark .button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdee0;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}html.theme--documenter-dark .hero-video,html.theme--documenter-dark .modal-background,html.theme--documenter-dark .modal,html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}html.theme--documenter-dark .navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#ecf0f1 !important}a.has-text-light:hover,a.has-text-light:focus{color:#cfd9db !important}.has-background-light{background-color:#ecf0f1 !important}.has-text-dark{color:#282f2f !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#111414 !important}.has-background-dark{background-color:#282f2f !important}.has-text-primary{color:#375a7f !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#28415b !important}.has-background-primary{background-color:#375a7f !important}.has-text-primary-light{color:#f1f5f9 !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#cddbe9 !important}.has-background-primary-light{background-color:#f1f5f9 !important}.has-text-primary-dark{color:#4d7eb2 !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#7198c1 !important}.has-background-primary-dark{background-color:#4d7eb2 !important}.has-text-link{color:#1abc9c !important}a.has-text-link:hover,a.has-text-link:focus{color:#148f77 !important}.has-background-link{background-color:#1abc9c !important}.has-text-link-light{color:#edfdf9 !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c0f6ec !important}.has-background-link-light{background-color:#edfdf9 !important}.has-text-link-dark{color:#15987e !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#1bc5a4 !important}.has-background-link-dark{background-color:#15987e !important}.has-text-info{color:#024c7d !important}a.has-text-info:hover,a.has-text-info:focus{color:#012d4b !important}.has-background-info{background-color:#024c7d !important}.has-text-info-light{color:#ebf7ff !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#b9e2fe !important}.has-background-info-light{background-color:#ebf7ff !important}.has-text-info-dark{color:#0e9dfb !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#40b1fc !important}.has-background-info-dark{background-color:#0e9dfb !important}.has-text-success{color:#008438 !important}a.has-text-success:hover,a.has-text-success:focus{color:#005122 !important}.has-background-success{background-color:#008438 !important}.has-text-success-light{color:#ebfff3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#b8ffd6 !important}.has-background-success-light{background-color:#ebfff3 !important}.has-text-success-dark{color:#00eb64 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#1fff7e !important}.has-background-success-dark{background-color:#00eb64 !important}.has-text-warning{color:#ad8100 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#7a5b00 !important}.has-background-warning{background-color:#ad8100 !important}.has-text-warning-light{color:#fffaeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#ffedb8 !important}.has-background-warning-light{background-color:#fffaeb !important}.has-text-warning-dark{color:#d19c00 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#ffbf05 !important}.has-background-warning-dark{background-color:#d19c00 !important}.has-text-danger{color:#9e1b0d !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#6f1309 !important}.has-background-danger{background-color:#9e1b0d !important}.has-text-danger-light{color:#fdeeec !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#fac3bd !important}.has-background-danger-light{background-color:#fdeeec !important}.has-text-danger-dark{color:#ec311d !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#f05c4c !important}.has-background-danger-dark{background-color:#ec311d !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#282f2f !important}.has-background-grey-darker{background-color:#282f2f !important}.has-text-grey-dark{color:#343c3d !important}.has-background-grey-dark{background-color:#343c3d !important}.has-text-grey{color:#5e6d6f !important}.has-background-grey{background-color:#5e6d6f !important}.has-text-grey-light{color:#8c9b9d !important}.has-background-grey-light{background-color:#8c9b9d !important}.has-text-grey-lighter{color:#dbdee0 !important}.has-background-grey-lighter{background-color:#dbdee0 !important}.has-text-white-ter{color:#ecf0f1 !important}.has-background-white-ter{background-color:#ecf0f1 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}html.theme--documenter-dark{/*! + Theme: a11y-dark + Author: @ericwbailey + Maintainer: @ericwbailey + + Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css +*/}html.theme--documenter-dark html{background-color:#1f2424;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark article,html.theme--documenter-dark aside,html.theme--documenter-dark figure,html.theme--documenter-dark footer,html.theme--documenter-dark header,html.theme--documenter-dark hgroup,html.theme--documenter-dark section{display:block}html.theme--documenter-dark body,html.theme--documenter-dark button,html.theme--documenter-dark input,html.theme--documenter-dark optgroup,html.theme--documenter-dark select,html.theme--documenter-dark textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}html.theme--documenter-dark code,html.theme--documenter-dark pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark body{color:#fff;font-size:1em;font-weight:400;line-height:1.5}html.theme--documenter-dark a{color:#1abc9c;cursor:pointer;text-decoration:none}html.theme--documenter-dark a strong{color:currentColor}html.theme--documenter-dark a:hover{color:#1dd2af}html.theme--documenter-dark code{background-color:rgba(255,255,255,0.05);color:#ececec;font-size:.875em;font-weight:normal;padding:.1em}html.theme--documenter-dark hr{background-color:#282f2f;border:none;display:block;height:2px;margin:1.5rem 0}html.theme--documenter-dark img{height:auto;max-width:100%}html.theme--documenter-dark input[type="checkbox"],html.theme--documenter-dark input[type="radio"]{vertical-align:baseline}html.theme--documenter-dark small{font-size:.875em}html.theme--documenter-dark span{font-style:inherit;font-weight:inherit}html.theme--documenter-dark strong{color:#f2f2f2;font-weight:700}html.theme--documenter-dark fieldset{border:none}html.theme--documenter-dark pre{-webkit-overflow-scrolling:touch;background-color:#282f2f;color:#fff;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}html.theme--documenter-dark pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}html.theme--documenter-dark table td,html.theme--documenter-dark table th{vertical-align:top}html.theme--documenter-dark table td:not([align]),html.theme--documenter-dark table th:not([align]){text-align:inherit}html.theme--documenter-dark table th{color:#f2f2f2}html.theme--documenter-dark .box{background-color:#343c3d;border-radius:8px;box-shadow:none;color:#fff;display:block;padding:1.25rem}html.theme--documenter-dark a.box:hover,html.theme--documenter-dark a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #1abc9c}html.theme--documenter-dark a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #1abc9c}html.theme--documenter-dark .button{background-color:#282f2f;border-color:#4c5759;border-width:1px;color:#375a7f;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}html.theme--documenter-dark .button strong{color:inherit}html.theme--documenter-dark .button .icon,html.theme--documenter-dark .button .icon.is-small,html.theme--documenter-dark .button #documenter .docs-sidebar form.docs-search>input.icon,html.theme--documenter-dark #documenter .docs-sidebar .button form.docs-search>input.icon,html.theme--documenter-dark .button .icon.is-medium,html.theme--documenter-dark .button .icon.is-large{height:1.5em;width:1.5em}html.theme--documenter-dark .button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}html.theme--documenter-dark .button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button:hover,html.theme--documenter-dark .button.is-hovered{border-color:#8c9b9d;color:#f2f2f2}html.theme--documenter-dark .button:focus,html.theme--documenter-dark .button.is-focused{border-color:#8c9b9d;color:#17a689}html.theme--documenter-dark .button:focus:not(:active),html.theme--documenter-dark .button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button:active,html.theme--documenter-dark .button.is-active{border-color:#343c3d;color:#f2f2f2}html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;color:#fff;text-decoration:underline}html.theme--documenter-dark .button.is-text:hover,html.theme--documenter-dark .button.is-text.is-hovered,html.theme--documenter-dark .button.is-text:focus,html.theme--documenter-dark .button.is-text.is-focused{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .button.is-text:active,html.theme--documenter-dark .button.is-text.is-active{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .button.is-text[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}html.theme--documenter-dark .button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#1abc9c;text-decoration:none}html.theme--documenter-dark .button.is-ghost:hover,html.theme--documenter-dark .button.is-ghost.is-hovered{color:#1abc9c;text-decoration:underline}html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:hover,html.theme--documenter-dark .button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus,html.theme--documenter-dark .button.is-white.is-focused{border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus:not(:active),html.theme--documenter-dark .button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-hovered{background-color:#000}html.theme--documenter-dark .button.is-white.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-white.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:hover,html.theme--documenter-dark .button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus,html.theme--documenter-dark .button.is-black.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus:not(:active),html.theme--documenter-dark .button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-black.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:hover,html.theme--documenter-dark .button.is-light.is-hovered{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus,html.theme--documenter-dark .button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus:not(:active),html.theme--documenter-dark .button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light.is-active{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:#ecf0f1;box-shadow:none}html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-outlined.is-focused{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-dark,html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover,html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus:not(:active),html.theme--documenter-dark .content kbd.button:focus:not(:active),html.theme--documenter-dark .button.is-dark.is-focused:not(:active),html.theme--documenter-dark .content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark[disabled],html.theme--documenter-dark .content kbd.button[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark,fieldset[disabled] html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:#282f2f;box-shadow:none}html.theme--documenter-dark .button.is-dark.is-inverted,html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted:hover,html.theme--documenter-dark .content kbd.button.is-inverted:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-dark.is-inverted[disabled],html.theme--documenter-dark .content kbd.button.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-loading::after,html.theme--documenter-dark .content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined,html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-outlined.is-focused{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus:not(:active),html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus:not(:active),html.theme--documenter-dark .button.is-primary.is-focused:not(:active),html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary[disabled],html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;box-shadow:none}html.theme--documenter-dark .button.is-primary.is-inverted,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}html.theme--documenter-dark .button.is-primary.is-inverted[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:hover,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-light.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e8eef5;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:active,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-light.is-active,html.theme--documenter-dark .docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#dfe8f1;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:hover,html.theme--documenter-dark .button.is-link.is-hovered{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus,html.theme--documenter-dark .button.is-link.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus:not(:active),html.theme--documenter-dark .button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link.is-active{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:#1abc9c;box-shadow:none}html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-link.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-outlined.is-focused{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:hover,html.theme--documenter-dark .button.is-link.is-light.is-hovered{background-color:#e2fbf6;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:active,html.theme--documenter-dark .button.is-link.is-light.is-active{background-color:#d7f9f3;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:hover,html.theme--documenter-dark .button.is-info.is-hovered{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus,html.theme--documenter-dark .button.is-info.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus:not(:active),html.theme--documenter-dark .button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info.is-active{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:#024c7d;box-shadow:none}html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-info.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;color:#024c7d}html.theme--documenter-dark .button.is-info.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-outlined.is-focused{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:hover,html.theme--documenter-dark .button.is-info.is-light.is-hovered{background-color:#def2fe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:active,html.theme--documenter-dark .button.is-info.is-light.is-active{background-color:#d2edfe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:hover,html.theme--documenter-dark .button.is-success.is-hovered{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus,html.theme--documenter-dark .button.is-success.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus:not(:active),html.theme--documenter-dark .button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success.is-active{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:#008438;box-shadow:none}html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-success.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;color:#008438}html.theme--documenter-dark .button.is-success.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-outlined.is-focused{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:hover,html.theme--documenter-dark .button.is-success.is-light.is-hovered{background-color:#deffec;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:active,html.theme--documenter-dark .button.is-success.is-light.is-active{background-color:#d1ffe5;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:hover,html.theme--documenter-dark .button.is-warning.is-hovered{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus,html.theme--documenter-dark .button.is-warning.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus:not(:active),html.theme--documenter-dark .button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning.is-active{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:#ad8100;box-shadow:none}html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-warning.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-outlined.is-focused{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-focused{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:hover,html.theme--documenter-dark .button.is-warning.is-light.is-hovered{background-color:#fff7de;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:active,html.theme--documenter-dark .button.is-warning.is-light.is-active{background-color:#fff3d1;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:hover,html.theme--documenter-dark .button.is-danger.is-hovered{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus,html.theme--documenter-dark .button.is-danger.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus:not(:active),html.theme--documenter-dark .button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger.is-active{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;box-shadow:none}html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-danger.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-outlined.is-focused{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:hover,html.theme--documenter-dark .button.is-danger.is-light.is-hovered{background-color:#fce3e0;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:active,html.theme--documenter-dark .button.is-danger.is-light.is-active{background-color:#fcd8d5;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}html.theme--documenter-dark .button.is-small:not(.is-rounded),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:3px}html.theme--documenter-dark .button.is-normal{font-size:1rem}html.theme--documenter-dark .button.is-medium{font-size:1.25rem}html.theme--documenter-dark .button.is-large{font-size:1.5rem}html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .button{background-color:#8c9b9d;border-color:#5e6d6f;box-shadow:none;opacity:.5}html.theme--documenter-dark .button.is-fullwidth{display:flex;width:100%}html.theme--documenter-dark .button.is-loading{color:transparent !important;pointer-events:none}html.theme--documenter-dark .button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}html.theme--documenter-dark .button.is-static{background-color:#282f2f;border-color:#5e6d6f;color:#dbdee0;box-shadow:none;pointer-events:none}html.theme--documenter-dark .button.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}html.theme--documenter-dark .buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .buttons .button{margin-bottom:0.5rem}html.theme--documenter-dark .buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}html.theme--documenter-dark .buttons:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .buttons:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:3px}html.theme--documenter-dark .buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}html.theme--documenter-dark .buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}html.theme--documenter-dark .buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}html.theme--documenter-dark .buttons.has-addons .button:last-child{margin-right:0}html.theme--documenter-dark .buttons.has-addons .button:hover,html.theme--documenter-dark .buttons.has-addons .button.is-hovered{z-index:2}html.theme--documenter-dark .buttons.has-addons .button:focus,html.theme--documenter-dark .buttons.has-addons .button.is-focused,html.theme--documenter-dark .buttons.has-addons .button:active,html.theme--documenter-dark .buttons.has-addons .button.is-active,html.theme--documenter-dark .buttons.has-addons .button.is-selected{z-index:3}html.theme--documenter-dark .buttons.has-addons .button:focus:hover,html.theme--documenter-dark .buttons.has-addons .button.is-focused:hover,html.theme--documenter-dark .buttons.has-addons .button:active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-selected:hover{z-index:4}html.theme--documenter-dark .buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .buttons.is-centered{justify-content:center}html.theme--documenter-dark .buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}html.theme--documenter-dark .buttons.is-right{justify-content:flex-end}html.theme--documenter-dark .buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:1rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1.25rem}}html.theme--documenter-dark .container{flex-grow:1;margin:0 auto;position:relative;width:auto}html.theme--documenter-dark .container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){html.theme--documenter-dark .container{max-width:992px}}@media screen and (max-width: 1215px){html.theme--documenter-dark .container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){html.theme--documenter-dark .container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){html.theme--documenter-dark .container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){html.theme--documenter-dark .container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}html.theme--documenter-dark .content li+li{margin-top:0.25em}html.theme--documenter-dark .content p:not(:last-child),html.theme--documenter-dark .content dl:not(:last-child),html.theme--documenter-dark .content ol:not(:last-child),html.theme--documenter-dark .content ul:not(:last-child),html.theme--documenter-dark .content blockquote:not(:last-child),html.theme--documenter-dark .content pre:not(:last-child),html.theme--documenter-dark .content table:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .content h1,html.theme--documenter-dark .content h2,html.theme--documenter-dark .content h3,html.theme--documenter-dark .content h4,html.theme--documenter-dark .content h5,html.theme--documenter-dark .content h6{color:#f2f2f2;font-weight:600;line-height:1.125}html.theme--documenter-dark .content h1{font-size:2em;margin-bottom:0.5em}html.theme--documenter-dark .content h1:not(:first-child){margin-top:1em}html.theme--documenter-dark .content h2{font-size:1.75em;margin-bottom:0.5714em}html.theme--documenter-dark .content h2:not(:first-child){margin-top:1.1428em}html.theme--documenter-dark .content h3{font-size:1.5em;margin-bottom:0.6666em}html.theme--documenter-dark .content h3:not(:first-child){margin-top:1.3333em}html.theme--documenter-dark .content h4{font-size:1.25em;margin-bottom:0.8em}html.theme--documenter-dark .content h5{font-size:1.125em;margin-bottom:0.8888em}html.theme--documenter-dark .content h6{font-size:1em;margin-bottom:1em}html.theme--documenter-dark .content blockquote{background-color:#282f2f;border-left:5px solid #5e6d6f;padding:1.25em 1.5em}html.theme--documenter-dark .content ol{list-style-position:outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ol:not([type]){list-style-type:decimal}html.theme--documenter-dark .content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}html.theme--documenter-dark .content ol.is-lower-roman:not([type]){list-style-type:lower-roman}html.theme--documenter-dark .content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}html.theme--documenter-dark .content ol.is-upper-roman:not([type]){list-style-type:upper-roman}html.theme--documenter-dark .content ul{list-style:disc outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ul ul{list-style-type:circle;margin-top:0.5em}html.theme--documenter-dark .content ul ul ul{list-style-type:square}html.theme--documenter-dark .content dd{margin-left:2em}html.theme--documenter-dark .content figure{margin-left:2em;margin-right:2em;text-align:center}html.theme--documenter-dark .content figure:not(:first-child){margin-top:2em}html.theme--documenter-dark .content figure:not(:last-child){margin-bottom:2em}html.theme--documenter-dark .content figure img{display:inline-block}html.theme--documenter-dark .content figure figcaption{font-style:italic}html.theme--documenter-dark .content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}html.theme--documenter-dark .content sup,html.theme--documenter-dark .content sub{font-size:75%}html.theme--documenter-dark .content table{width:100%}html.theme--documenter-dark .content table td,html.theme--documenter-dark .content table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .content table th{color:#f2f2f2}html.theme--documenter-dark .content table th:not([align]){text-align:inherit}html.theme--documenter-dark .content table thead td,html.theme--documenter-dark .content table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .content table tfoot td,html.theme--documenter-dark .content table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .content table tbody tr:last-child td,html.theme--documenter-dark .content table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .content .tabs li+li{margin-top:0}html.theme--documenter-dark .content.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}html.theme--documenter-dark .content.is-normal{font-size:1rem}html.theme--documenter-dark .content.is-medium{font-size:1.25rem}html.theme--documenter-dark .content.is-large{font-size:1.5rem}html.theme--documenter-dark .icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}html.theme--documenter-dark .icon.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}html.theme--documenter-dark .icon.is-medium{height:2rem;width:2rem}html.theme--documenter-dark .icon.is-large{height:3rem;width:3rem}html.theme--documenter-dark .icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}html.theme--documenter-dark .icon-text .icon{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .icon-text .icon:not(:last-child){margin-right:.25em}html.theme--documenter-dark .icon-text .icon:not(:first-child){margin-left:.25em}html.theme--documenter-dark div.icon-text{display:flex}html.theme--documenter-dark .image,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{display:block;position:relative}html.theme--documenter-dark .image img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}html.theme--documenter-dark .image img.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}html.theme--documenter-dark .image.is-fullwidth,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}html.theme--documenter-dark .image.is-square,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square,html.theme--documenter-dark .image.is-1by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}html.theme--documenter-dark .image.is-5by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}html.theme--documenter-dark .image.is-4by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}html.theme--documenter-dark .image.is-3by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}html.theme--documenter-dark .image.is-5by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}html.theme--documenter-dark .image.is-16by9,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}html.theme--documenter-dark .image.is-2by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}html.theme--documenter-dark .image.is-3by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}html.theme--documenter-dark .image.is-4by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}html.theme--documenter-dark .image.is-3by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}html.theme--documenter-dark .image.is-2by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}html.theme--documenter-dark .image.is-3by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}html.theme--documenter-dark .image.is-9by16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}html.theme--documenter-dark .image.is-1by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}html.theme--documenter-dark .image.is-1by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}html.theme--documenter-dark .image.is-16x16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}html.theme--documenter-dark .image.is-24x24,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}html.theme--documenter-dark .image.is-32x32,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}html.theme--documenter-dark .image.is-48x48,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}html.theme--documenter-dark .image.is-64x64,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}html.theme--documenter-dark .image.is-96x96,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}html.theme--documenter-dark .image.is-128x128,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}html.theme--documenter-dark .notification{background-color:#282f2f;border-radius:.4em;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}html.theme--documenter-dark .notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .notification strong{color:currentColor}html.theme--documenter-dark .notification code,html.theme--documenter-dark .notification pre{background:#fff}html.theme--documenter-dark .notification pre code{background:transparent}html.theme--documenter-dark .notification>.delete{right:.5rem;position:absolute;top:0.5rem}html.theme--documenter-dark .notification .title,html.theme--documenter-dark .notification .subtitle,html.theme--documenter-dark .notification .content{color:currentColor}html.theme--documenter-dark .notification.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .notification.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .notification.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .notification.is-dark,html.theme--documenter-dark .content kbd.notification{background-color:#282f2f;color:#fff}html.theme--documenter-dark .notification.is-primary,html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .notification.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.notification.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .notification.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .notification.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .notification.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .notification.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .notification.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .notification.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .notification.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .notification.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .notification.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .notification.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}html.theme--documenter-dark .progress::-webkit-progress-bar{background-color:#343c3d}html.theme--documenter-dark .progress::-webkit-progress-value{background-color:#dbdee0}html.theme--documenter-dark .progress::-moz-progress-bar{background-color:#dbdee0}html.theme--documenter-dark .progress::-ms-fill{background-color:#dbdee0;border:none}html.theme--documenter-dark .progress.is-white::-webkit-progress-value{background-color:#fff}html.theme--documenter-dark .progress.is-white::-moz-progress-bar{background-color:#fff}html.theme--documenter-dark .progress.is-white::-ms-fill{background-color:#fff}html.theme--documenter-dark .progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-black::-webkit-progress-value{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-moz-progress-bar{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-ms-fill{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-light::-webkit-progress-value{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-moz-progress-bar{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-ms-fill{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light:indeterminate{background-image:linear-gradient(to right, #ecf0f1 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-dark::-webkit-progress-value,html.theme--documenter-dark .content kbd.progress::-webkit-progress-value{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-moz-progress-bar,html.theme--documenter-dark .content kbd.progress::-moz-progress-bar{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-ms-fill,html.theme--documenter-dark .content kbd.progress::-ms-fill{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark:indeterminate,html.theme--documenter-dark .content kbd.progress:indeterminate{background-image:linear-gradient(to right, #282f2f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-primary::-webkit-progress-value,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-moz-progress-bar,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-ms-fill,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary:indeterminate,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #375a7f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-link::-webkit-progress-value{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-moz-progress-bar{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-ms-fill{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link:indeterminate{background-image:linear-gradient(to right, #1abc9c 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-info::-webkit-progress-value{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-moz-progress-bar{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-ms-fill{background-color:#024c7d}html.theme--documenter-dark .progress.is-info:indeterminate{background-image:linear-gradient(to right, #024c7d 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-success::-webkit-progress-value{background-color:#008438}html.theme--documenter-dark .progress.is-success::-moz-progress-bar{background-color:#008438}html.theme--documenter-dark .progress.is-success::-ms-fill{background-color:#008438}html.theme--documenter-dark .progress.is-success:indeterminate{background-image:linear-gradient(to right, #008438 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-warning::-webkit-progress-value{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-moz-progress-bar{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-ms-fill{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ad8100 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-danger::-webkit-progress-value{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-moz-progress-bar{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-ms-fill{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger:indeterminate{background-image:linear-gradient(to right, #9e1b0d 30%, #343c3d 30%)}html.theme--documenter-dark .progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#343c3d;background-image:linear-gradient(to right, #fff 30%, #343c3d 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}html.theme--documenter-dark .progress:indeterminate::-webkit-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-moz-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-ms-fill{animation-name:none}html.theme--documenter-dark .progress.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}html.theme--documenter-dark .progress.is-medium{height:1.25rem}html.theme--documenter-dark .progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}html.theme--documenter-dark .table{background-color:#343c3d;color:#fff}html.theme--documenter-dark .table td,html.theme--documenter-dark .table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .table td.is-white,html.theme--documenter-dark .table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .table td.is-black,html.theme--documenter-dark .table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .table td.is-light,html.theme--documenter-dark .table th.is-light{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .table td.is-dark,html.theme--documenter-dark .table th.is-dark{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .table td.is-primary,html.theme--documenter-dark .table th.is-primary{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-link,html.theme--documenter-dark .table th.is-link{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .table td.is-info,html.theme--documenter-dark .table th.is-info{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .table td.is-success,html.theme--documenter-dark .table th.is-success{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .table td.is-warning,html.theme--documenter-dark .table th.is-warning{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .table td.is-danger,html.theme--documenter-dark .table th.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .table td.is-narrow,html.theme--documenter-dark .table th.is-narrow{white-space:nowrap;width:1%}html.theme--documenter-dark .table td.is-selected,html.theme--documenter-dark .table th.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-selected a,html.theme--documenter-dark .table td.is-selected strong,html.theme--documenter-dark .table th.is-selected a,html.theme--documenter-dark .table th.is-selected strong{color:currentColor}html.theme--documenter-dark .table td.is-vcentered,html.theme--documenter-dark .table th.is-vcentered{vertical-align:middle}html.theme--documenter-dark .table th{color:#f2f2f2}html.theme--documenter-dark .table th:not([align]){text-align:left}html.theme--documenter-dark .table tr.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table tr.is-selected a,html.theme--documenter-dark .table tr.is-selected strong{color:currentColor}html.theme--documenter-dark .table tr.is-selected td,html.theme--documenter-dark .table tr.is-selected th{border-color:#fff;color:currentColor}html.theme--documenter-dark .table thead{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table thead td,html.theme--documenter-dark .table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .table tfoot{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tfoot td,html.theme--documenter-dark .table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .table tbody{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tbody tr:last-child td,html.theme--documenter-dark .table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .table.is-bordered td,html.theme--documenter-dark .table.is-bordered th{border-width:1px}html.theme--documenter-dark .table.is-bordered tr:last-child td,html.theme--documenter-dark .table.is-bordered tr:last-child th{border-bottom-width:1px}html.theme--documenter-dark .table.is-fullwidth{width:100%}html.theme--documenter-dark .table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#2d3435}html.theme--documenter-dark .table.is-narrow td,html.theme--documenter-dark .table.is-narrow th{padding:0.25em 0.5em}html.theme--documenter-dark .table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#282f2f}html.theme--documenter-dark .table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}html.theme--documenter-dark .tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .tags .tag,html.theme--documenter-dark .tags .content kbd,html.theme--documenter-dark .content .tags kbd,html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}html.theme--documenter-dark .tags .tag:not(:last-child),html.theme--documenter-dark .tags .content kbd:not(:last-child),html.theme--documenter-dark .content .tags kbd:not(:last-child),html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}html.theme--documenter-dark .tags:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .tags:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .tags.are-medium .tag:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .content kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .content .tags.are-medium kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}html.theme--documenter-dark .tags.are-large .tag:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .content kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .content .tags.are-large kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}html.theme--documenter-dark .tags.is-centered{justify-content:center}html.theme--documenter-dark .tags.is-centered .tag,html.theme--documenter-dark .tags.is-centered .content kbd,html.theme--documenter-dark .content .tags.is-centered kbd,html.theme--documenter-dark .tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}html.theme--documenter-dark .tags.is-right{justify-content:flex-end}html.theme--documenter-dark .tags.is-right .tag:not(:first-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:first-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}html.theme--documenter-dark .tags.is-right .tag:not(:last-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:last-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}html.theme--documenter-dark .tags.has-addons .tag,html.theme--documenter-dark .tags.has-addons .content kbd,html.theme--documenter-dark .content .tags.has-addons kbd,html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}html.theme--documenter-dark .tags.has-addons .tag:not(:first-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:first-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}html.theme--documenter-dark .tags.has-addons .tag:not(:last-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:last-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}html.theme--documenter-dark .tag:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#282f2f;border-radius:.4em;color:#fff;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}html.theme--documenter-dark .tag:not(body) .delete,html.theme--documenter-dark .content kbd:not(body) .delete,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}html.theme--documenter-dark .tag.is-white:not(body),html.theme--documenter-dark .content kbd.is-white:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .tag.is-black:not(body),html.theme--documenter-dark .content kbd.is-black:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .tag.is-light:not(body),html.theme--documenter-dark .content kbd.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .tag.is-dark:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-dark:not(body),html.theme--documenter-dark .content .docstring>section>kbd:not(body){background-color:#282f2f;color:#fff}html.theme--documenter-dark .tag.is-primary:not(body),html.theme--documenter-dark .content kbd.is-primary:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){background-color:#375a7f;color:#fff}html.theme--documenter-dark .tag.is-primary.is-light:not(body),html.theme--documenter-dark .content kbd.is-primary.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .tag.is-link:not(body),html.theme--documenter-dark .content kbd.is-link:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#1abc9c;color:#fff}html.theme--documenter-dark .tag.is-link.is-light:not(body),html.theme--documenter-dark .content kbd.is-link.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .tag.is-info:not(body),html.theme--documenter-dark .content kbd.is-info:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#024c7d;color:#fff}html.theme--documenter-dark .tag.is-info.is-light:not(body),html.theme--documenter-dark .content kbd.is-info.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .tag.is-success:not(body),html.theme--documenter-dark .content kbd.is-success:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#008438;color:#fff}html.theme--documenter-dark .tag.is-success.is-light:not(body),html.theme--documenter-dark .content kbd.is-success.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .tag.is-warning:not(body),html.theme--documenter-dark .content kbd.is-warning:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ad8100;color:#fff}html.theme--documenter-dark .tag.is-warning.is-light:not(body),html.theme--documenter-dark .content kbd.is-warning.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .tag.is-danger:not(body),html.theme--documenter-dark .content kbd.is-danger:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .tag.is-danger.is-light:not(body),html.theme--documenter-dark .content kbd.is-danger.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .tag.is-normal:not(body),html.theme--documenter-dark .content kbd.is-normal:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}html.theme--documenter-dark .tag.is-medium:not(body),html.theme--documenter-dark .content kbd.is-medium:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}html.theme--documenter-dark .tag.is-large:not(body),html.theme--documenter-dark .content kbd.is-large:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}html.theme--documenter-dark .tag:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .content kbd:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}html.theme--documenter-dark .tag:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .content kbd:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}html.theme--documenter-dark .tag:not(body) .icon:first-child:last-child,html.theme--documenter-dark .content kbd:not(body) .icon:first-child:last-child,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}html.theme--documenter-dark .tag.is-delete:not(body),html.theme--documenter-dark .content kbd.is-delete:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before,html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}html.theme--documenter-dark .tag.is-delete:not(body):hover,html.theme--documenter-dark .content kbd.is-delete:not(body):hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):hover,html.theme--documenter-dark .tag.is-delete:not(body):focus,html.theme--documenter-dark .content kbd.is-delete:not(body):focus,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#1d2122}html.theme--documenter-dark .tag.is-delete:not(body):active,html.theme--documenter-dark .content kbd.is-delete:not(body):active,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#111414}html.theme--documenter-dark .tag.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:not(body),html.theme--documenter-dark .content kbd.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}html.theme--documenter-dark a.tag:hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:hover{text-decoration:underline}html.theme--documenter-dark .title,html.theme--documenter-dark .subtitle{word-break:break-word}html.theme--documenter-dark .title em,html.theme--documenter-dark .title span,html.theme--documenter-dark .subtitle em,html.theme--documenter-dark .subtitle span{font-weight:inherit}html.theme--documenter-dark .title sub,html.theme--documenter-dark .subtitle sub{font-size:.75em}html.theme--documenter-dark .title sup,html.theme--documenter-dark .subtitle sup{font-size:.75em}html.theme--documenter-dark .title .tag,html.theme--documenter-dark .title .content kbd,html.theme--documenter-dark .content .title kbd,html.theme--documenter-dark .title .docstring>section>a.docs-sourcelink,html.theme--documenter-dark .subtitle .tag,html.theme--documenter-dark .subtitle .content kbd,html.theme--documenter-dark .content .subtitle kbd,html.theme--documenter-dark .subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}html.theme--documenter-dark .title{color:#fff;font-size:2rem;font-weight:500;line-height:1.125}html.theme--documenter-dark .title strong{color:inherit;font-weight:inherit}html.theme--documenter-dark .title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}html.theme--documenter-dark .title.is-1{font-size:3rem}html.theme--documenter-dark .title.is-2{font-size:2.5rem}html.theme--documenter-dark .title.is-3{font-size:2rem}html.theme--documenter-dark .title.is-4{font-size:1.5rem}html.theme--documenter-dark .title.is-5{font-size:1.25rem}html.theme--documenter-dark .title.is-6{font-size:1rem}html.theme--documenter-dark .title.is-7{font-size:.75rem}html.theme--documenter-dark .subtitle{color:#8c9b9d;font-size:1.25rem;font-weight:400;line-height:1.25}html.theme--documenter-dark .subtitle strong{color:#8c9b9d;font-weight:600}html.theme--documenter-dark .subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}html.theme--documenter-dark .subtitle.is-1{font-size:3rem}html.theme--documenter-dark .subtitle.is-2{font-size:2.5rem}html.theme--documenter-dark .subtitle.is-3{font-size:2rem}html.theme--documenter-dark .subtitle.is-4{font-size:1.5rem}html.theme--documenter-dark .subtitle.is-5{font-size:1.25rem}html.theme--documenter-dark .subtitle.is-6{font-size:1rem}html.theme--documenter-dark .subtitle.is-7{font-size:.75rem}html.theme--documenter-dark .heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}html.theme--documenter-dark .number{align-items:center;background-color:#282f2f;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#1f2424;border-color:#5e6d6f;border-radius:.4em;color:#dbdee0}html.theme--documenter-dark .select select::-moz-placeholder,html.theme--documenter-dark .textarea::-moz-placeholder,html.theme--documenter-dark .input::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select::-webkit-input-placeholder,html.theme--documenter-dark .textarea::-webkit-input-placeholder,html.theme--documenter-dark .input::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:-moz-placeholder,html.theme--documenter-dark .textarea:-moz-placeholder,html.theme--documenter-dark .input:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select:-ms-input-placeholder,html.theme--documenter-dark .textarea:-ms-input-placeholder,html.theme--documenter-dark .input:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:hover,html.theme--documenter-dark .textarea:hover,html.theme--documenter-dark .input:hover,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:hover,html.theme--documenter-dark .select select.is-hovered,html.theme--documenter-dark .is-hovered.textarea,html.theme--documenter-dark .is-hovered.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#8c9b9d}html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{border-color:#1abc9c;box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#8c9b9d;border-color:#282f2f;box-shadow:none;color:#fff}html.theme--documenter-dark .select select[disabled]::-moz-placeholder,html.theme--documenter-dark .textarea[disabled]::-moz-placeholder,html.theme--documenter-dark .input[disabled]::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .textarea[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .input[disabled]::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-moz-placeholder,html.theme--documenter-dark .textarea[disabled]:-moz-placeholder,html.theme--documenter-dark .input[disabled]:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-ms-input-placeholder,html.theme--documenter-dark .textarea[disabled]:-ms-input-placeholder,html.theme--documenter-dark .input[disabled]:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}html.theme--documenter-dark .textarea[readonly],html.theme--documenter-dark .input[readonly],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}html.theme--documenter-dark .is-white.textarea,html.theme--documenter-dark .is-white.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}html.theme--documenter-dark .is-white.textarea:focus,html.theme--documenter-dark .is-white.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:focus,html.theme--documenter-dark .is-white.is-focused.textarea,html.theme--documenter-dark .is-white.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-white.textarea:active,html.theme--documenter-dark .is-white.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:active,html.theme--documenter-dark .is-white.is-active.textarea,html.theme--documenter-dark .is-white.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .is-black.textarea,html.theme--documenter-dark .is-black.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}html.theme--documenter-dark .is-black.textarea:focus,html.theme--documenter-dark .is-black.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:focus,html.theme--documenter-dark .is-black.is-focused.textarea,html.theme--documenter-dark .is-black.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-black.textarea:active,html.theme--documenter-dark .is-black.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:active,html.theme--documenter-dark .is-black.is-active.textarea,html.theme--documenter-dark .is-black.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .is-light.textarea,html.theme--documenter-dark .is-light.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light{border-color:#ecf0f1}html.theme--documenter-dark .is-light.textarea:focus,html.theme--documenter-dark .is-light.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:focus,html.theme--documenter-dark .is-light.is-focused.textarea,html.theme--documenter-dark .is-light.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-light.textarea:active,html.theme--documenter-dark .is-light.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:active,html.theme--documenter-dark .is-light.is-active.textarea,html.theme--documenter-dark .is-light.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .is-dark.textarea,html.theme--documenter-dark .content kbd.textarea,html.theme--documenter-dark .is-dark.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark,html.theme--documenter-dark .content kbd.input{border-color:#282f2f}html.theme--documenter-dark .is-dark.textarea:focus,html.theme--documenter-dark .content kbd.textarea:focus,html.theme--documenter-dark .is-dark.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:focus,html.theme--documenter-dark .content kbd.input:focus,html.theme--documenter-dark .is-dark.is-focused.textarea,html.theme--documenter-dark .content kbd.is-focused.textarea,html.theme--documenter-dark .is-dark.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .content kbd.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-focused,html.theme--documenter-dark .is-dark.textarea:active,html.theme--documenter-dark .content kbd.textarea:active,html.theme--documenter-dark .is-dark.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:active,html.theme--documenter-dark .content kbd.input:active,html.theme--documenter-dark .is-dark.is-active.textarea,html.theme--documenter-dark .content kbd.is-active.textarea,html.theme--documenter-dark .is-dark.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .content kbd.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .is-primary.textarea,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink{border-color:#375a7f}html.theme--documenter-dark .is-primary.textarea:focus,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:focus,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.is-focused.textarea,html.theme--documenter-dark .docstring>section>a.is-focused.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .docstring>section>a.is-focused.input.docs-sourcelink,html.theme--documenter-dark .is-primary.textarea:active,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:active,html.theme--documenter-dark .is-primary.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:active,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:active,html.theme--documenter-dark .is-primary.is-active.textarea,html.theme--documenter-dark .docstring>section>a.is-active.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .is-link.textarea,html.theme--documenter-dark .is-link.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link{border-color:#1abc9c}html.theme--documenter-dark .is-link.textarea:focus,html.theme--documenter-dark .is-link.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:focus,html.theme--documenter-dark .is-link.is-focused.textarea,html.theme--documenter-dark .is-link.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-link.textarea:active,html.theme--documenter-dark .is-link.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:active,html.theme--documenter-dark .is-link.is-active.textarea,html.theme--documenter-dark .is-link.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .is-info.textarea,html.theme--documenter-dark .is-info.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info{border-color:#024c7d}html.theme--documenter-dark .is-info.textarea:focus,html.theme--documenter-dark .is-info.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:focus,html.theme--documenter-dark .is-info.is-focused.textarea,html.theme--documenter-dark .is-info.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-info.textarea:active,html.theme--documenter-dark .is-info.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:active,html.theme--documenter-dark .is-info.is-active.textarea,html.theme--documenter-dark .is-info.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .is-success.textarea,html.theme--documenter-dark .is-success.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success{border-color:#008438}html.theme--documenter-dark .is-success.textarea:focus,html.theme--documenter-dark .is-success.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:focus,html.theme--documenter-dark .is-success.is-focused.textarea,html.theme--documenter-dark .is-success.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-success.textarea:active,html.theme--documenter-dark .is-success.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:active,html.theme--documenter-dark .is-success.is-active.textarea,html.theme--documenter-dark .is-success.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .is-warning.textarea,html.theme--documenter-dark .is-warning.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ad8100}html.theme--documenter-dark .is-warning.textarea:focus,html.theme--documenter-dark .is-warning.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:focus,html.theme--documenter-dark .is-warning.is-focused.textarea,html.theme--documenter-dark .is-warning.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-warning.textarea:active,html.theme--documenter-dark .is-warning.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:active,html.theme--documenter-dark .is-warning.is-active.textarea,html.theme--documenter-dark .is-warning.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .is-danger.textarea,html.theme--documenter-dark .is-danger.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#9e1b0d}html.theme--documenter-dark .is-danger.textarea:focus,html.theme--documenter-dark .is-danger.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:focus,html.theme--documenter-dark .is-danger.is-focused.textarea,html.theme--documenter-dark .is-danger.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-danger.textarea:active,html.theme--documenter-dark .is-danger.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:active,html.theme--documenter-dark .is-danger.is-active.textarea,html.theme--documenter-dark .is-danger.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .is-small.textarea,html.theme--documenter-dark .is-small.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .is-medium.textarea,html.theme--documenter-dark .is-medium.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}html.theme--documenter-dark .is-large.textarea,html.theme--documenter-dark .is-large.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}html.theme--documenter-dark .is-fullwidth.textarea,html.theme--documenter-dark .is-fullwidth.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}html.theme--documenter-dark .is-inline.textarea,html.theme--documenter-dark .is-inline.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}html.theme--documenter-dark .input.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}html.theme--documenter-dark .input.is-static,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}html.theme--documenter-dark .textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}html.theme--documenter-dark .textarea:not([rows]){max-height:40em;min-height:8em}html.theme--documenter-dark .textarea[rows]{height:initial}html.theme--documenter-dark .textarea.has-fixed-size{resize:none}html.theme--documenter-dark .radio,html.theme--documenter-dark .checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}html.theme--documenter-dark .radio input,html.theme--documenter-dark .checkbox input{cursor:pointer}html.theme--documenter-dark .radio:hover,html.theme--documenter-dark .checkbox:hover{color:#8c9b9d}html.theme--documenter-dark .radio[disabled],html.theme--documenter-dark .checkbox[disabled],fieldset[disabled] html.theme--documenter-dark .radio,fieldset[disabled] html.theme--documenter-dark .checkbox,html.theme--documenter-dark .radio input[disabled],html.theme--documenter-dark .checkbox input[disabled]{color:#fff;cursor:not-allowed}html.theme--documenter-dark .radio+.radio{margin-left:.5em}html.theme--documenter-dark .select{display:inline-block;max-width:100%;position:relative;vertical-align:top}html.theme--documenter-dark .select:not(.is-multiple){height:2.5em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border-color:#1abc9c;right:1.125em;z-index:4}html.theme--documenter-dark .select.is-rounded select,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}html.theme--documenter-dark .select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}html.theme--documenter-dark .select select::-ms-expand{display:none}html.theme--documenter-dark .select select[disabled]:hover,fieldset[disabled] html.theme--documenter-dark .select select:hover{border-color:#282f2f}html.theme--documenter-dark .select select:not([multiple]){padding-right:2.5em}html.theme--documenter-dark .select select[multiple]{height:auto;padding:0}html.theme--documenter-dark .select select[multiple] option{padding:0.5em 1em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading):hover::after{border-color:#8c9b9d}html.theme--documenter-dark .select.is-white:not(:hover)::after{border-color:#fff}html.theme--documenter-dark .select.is-white select{border-color:#fff}html.theme--documenter-dark .select.is-white select:hover,html.theme--documenter-dark .select.is-white select.is-hovered{border-color:#f2f2f2}html.theme--documenter-dark .select.is-white select:focus,html.theme--documenter-dark .select.is-white select.is-focused,html.theme--documenter-dark .select.is-white select:active,html.theme--documenter-dark .select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .select.is-black:not(:hover)::after{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select:hover,html.theme--documenter-dark .select.is-black select.is-hovered{border-color:#000}html.theme--documenter-dark .select.is-black select:focus,html.theme--documenter-dark .select.is-black select.is-focused,html.theme--documenter-dark .select.is-black select:active,html.theme--documenter-dark .select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .select.is-light:not(:hover)::after{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select:hover,html.theme--documenter-dark .select.is-light select.is-hovered{border-color:#dde4e6}html.theme--documenter-dark .select.is-light select:focus,html.theme--documenter-dark .select.is-light select.is-focused,html.theme--documenter-dark .select.is-light select:active,html.theme--documenter-dark .select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .select.is-dark:not(:hover)::after,html.theme--documenter-dark .content kbd.select:not(:hover)::after{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select,html.theme--documenter-dark .content kbd.select select{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select:hover,html.theme--documenter-dark .content kbd.select select:hover,html.theme--documenter-dark .select.is-dark select.is-hovered,html.theme--documenter-dark .content kbd.select select.is-hovered{border-color:#1d2122}html.theme--documenter-dark .select.is-dark select:focus,html.theme--documenter-dark .content kbd.select select:focus,html.theme--documenter-dark .select.is-dark select.is-focused,html.theme--documenter-dark .content kbd.select select.is-focused,html.theme--documenter-dark .select.is-dark select:active,html.theme--documenter-dark .content kbd.select select:active,html.theme--documenter-dark .select.is-dark select.is-active,html.theme--documenter-dark .content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .select.is-primary:not(:hover)::after,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select:hover,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:hover,html.theme--documenter-dark .select.is-primary select.is-hovered,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#2f4d6d}html.theme--documenter-dark .select.is-primary select:focus,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:focus,html.theme--documenter-dark .select.is-primary select.is-focused,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-focused,html.theme--documenter-dark .select.is-primary select:active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:active,html.theme--documenter-dark .select.is-primary select.is-active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .select.is-link:not(:hover)::after{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select:hover,html.theme--documenter-dark .select.is-link select.is-hovered{border-color:#17a689}html.theme--documenter-dark .select.is-link select:focus,html.theme--documenter-dark .select.is-link select.is-focused,html.theme--documenter-dark .select.is-link select:active,html.theme--documenter-dark .select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select.is-info:not(:hover)::after{border-color:#024c7d}html.theme--documenter-dark .select.is-info select{border-color:#024c7d}html.theme--documenter-dark .select.is-info select:hover,html.theme--documenter-dark .select.is-info select.is-hovered{border-color:#023d64}html.theme--documenter-dark .select.is-info select:focus,html.theme--documenter-dark .select.is-info select.is-focused,html.theme--documenter-dark .select.is-info select:active,html.theme--documenter-dark .select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .select.is-success:not(:hover)::after{border-color:#008438}html.theme--documenter-dark .select.is-success select{border-color:#008438}html.theme--documenter-dark .select.is-success select:hover,html.theme--documenter-dark .select.is-success select.is-hovered{border-color:#006b2d}html.theme--documenter-dark .select.is-success select:focus,html.theme--documenter-dark .select.is-success select.is-focused,html.theme--documenter-dark .select.is-success select:active,html.theme--documenter-dark .select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .select.is-warning:not(:hover)::after{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select:hover,html.theme--documenter-dark .select.is-warning select.is-hovered{border-color:#946e00}html.theme--documenter-dark .select.is-warning select:focus,html.theme--documenter-dark .select.is-warning select.is-focused,html.theme--documenter-dark .select.is-warning select:active,html.theme--documenter-dark .select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .select.is-danger:not(:hover)::after{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select:hover,html.theme--documenter-dark .select.is-danger select.is-hovered{border-color:#86170b}html.theme--documenter-dark .select.is-danger select:focus,html.theme--documenter-dark .select.is-danger select.is-focused,html.theme--documenter-dark .select.is-danger select:active,html.theme--documenter-dark .select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .select.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .select.is-medium{font-size:1.25rem}html.theme--documenter-dark .select.is-large{font-size:1.5rem}html.theme--documenter-dark .select.is-disabled::after{border-color:#fff !important;opacity:0.5}html.theme--documenter-dark .select.is-fullwidth{width:100%}html.theme--documenter-dark .select.is-fullwidth select{width:100%}html.theme--documenter-dark .select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}html.theme--documenter-dark .select.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .select.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .select.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}html.theme--documenter-dark .file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:hover .file-cta,html.theme--documenter-dark .file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:focus .file-cta,html.theme--documenter-dark .file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}html.theme--documenter-dark .file.is-white:active .file-cta,html.theme--documenter-dark .file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:hover .file-cta,html.theme--documenter-dark .file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:focus .file-cta,html.theme--documenter-dark .file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}html.theme--documenter-dark .file.is-black:active .file-cta,html.theme--documenter-dark .file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-light .file-cta{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:hover .file-cta,html.theme--documenter-dark .file.is-light.is-hovered .file-cta{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:focus .file-cta,html.theme--documenter-dark .file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(236,240,241,0.25);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:active .file-cta,html.theme--documenter-dark .file.is-light.is-active .file-cta{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-dark .file-cta,html.theme--documenter-dark .content kbd.file .file-cta{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:hover .file-cta,html.theme--documenter-dark .content kbd.file:hover .file-cta,html.theme--documenter-dark .file.is-dark.is-hovered .file-cta,html.theme--documenter-dark .content kbd.file.is-hovered .file-cta{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:focus .file-cta,html.theme--documenter-dark .content kbd.file:focus .file-cta,html.theme--documenter-dark .file.is-dark.is-focused .file-cta,html.theme--documenter-dark .content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(40,47,47,0.25);color:#fff}html.theme--documenter-dark .file.is-dark:active .file-cta,html.theme--documenter-dark .content kbd.file:active .file-cta,html.theme--documenter-dark .file.is-dark.is-active .file-cta,html.theme--documenter-dark .content kbd.file.is-active .file-cta{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink .file-cta{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:hover .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:hover .file-cta,html.theme--documenter-dark .file.is-primary.is-hovered .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:focus .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:focus .file-cta,html.theme--documenter-dark .file.is-primary.is-focused .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(55,90,127,0.25);color:#fff}html.theme--documenter-dark .file.is-primary:active .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:active .file-cta,html.theme--documenter-dark .file.is-primary.is-active .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link .file-cta{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:hover .file-cta,html.theme--documenter-dark .file.is-link.is-hovered .file-cta{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:focus .file-cta,html.theme--documenter-dark .file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(26,188,156,0.25);color:#fff}html.theme--documenter-dark .file.is-link:active .file-cta,html.theme--documenter-dark .file.is-link.is-active .file-cta{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info .file-cta{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:hover .file-cta,html.theme--documenter-dark .file.is-info.is-hovered .file-cta{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:focus .file-cta,html.theme--documenter-dark .file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(2,76,125,0.25);color:#fff}html.theme--documenter-dark .file.is-info:active .file-cta,html.theme--documenter-dark .file.is-info.is-active .file-cta{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success .file-cta{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:hover .file-cta,html.theme--documenter-dark .file.is-success.is-hovered .file-cta{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:focus .file-cta,html.theme--documenter-dark .file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(0,132,56,0.25);color:#fff}html.theme--documenter-dark .file.is-success:active .file-cta,html.theme--documenter-dark .file.is-success.is-active .file-cta{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning .file-cta{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:hover .file-cta,html.theme--documenter-dark .file.is-warning.is-hovered .file-cta{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:focus .file-cta,html.theme--documenter-dark .file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(173,129,0,0.25);color:#fff}html.theme--documenter-dark .file.is-warning:active .file-cta,html.theme--documenter-dark .file.is-warning.is-active .file-cta{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger .file-cta{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:hover .file-cta,html.theme--documenter-dark .file.is-danger.is-hovered .file-cta{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:focus .file-cta,html.theme--documenter-dark .file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(158,27,13,0.25);color:#fff}html.theme--documenter-dark .file.is-danger:active .file-cta,html.theme--documenter-dark .file.is-danger.is-active .file-cta{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}html.theme--documenter-dark .file.is-normal{font-size:1rem}html.theme--documenter-dark .file.is-medium{font-size:1.25rem}html.theme--documenter-dark .file.is-medium .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-large{font-size:1.5rem}html.theme--documenter-dark .file.is-large .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .file.has-name.is-empty .file-cta{border-radius:.4em}html.theme--documenter-dark .file.has-name.is-empty .file-name{display:none}html.theme--documenter-dark .file.is-boxed .file-label{flex-direction:column}html.theme--documenter-dark .file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}html.theme--documenter-dark .file.is-boxed .file-name{border-width:0 1px 1px}html.theme--documenter-dark .file.is-boxed .file-icon{height:1.5em;width:1.5em}html.theme--documenter-dark .file.is-boxed .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-boxed.is-small .file-icon .fa,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}html.theme--documenter-dark .file.is-boxed.is-medium .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.is-boxed.is-large .file-icon .fa{font-size:35px}html.theme--documenter-dark .file.is-boxed.has-name .file-cta{border-radius:.4em .4em 0 0}html.theme--documenter-dark .file.is-boxed.has-name .file-name{border-radius:0 0 .4em .4em;border-width:0 1px 1px}html.theme--documenter-dark .file.is-centered{justify-content:center}html.theme--documenter-dark .file.is-fullwidth .file-label{width:100%}html.theme--documenter-dark .file.is-fullwidth .file-name{flex-grow:1;max-width:none}html.theme--documenter-dark .file.is-right{justify-content:flex-end}html.theme--documenter-dark .file.is-right .file-cta{border-radius:0 .4em .4em 0}html.theme--documenter-dark .file.is-right .file-name{border-radius:.4em 0 0 .4em;border-width:1px 0 1px 1px;order:-1}html.theme--documenter-dark .file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}html.theme--documenter-dark .file-label:hover .file-cta{background-color:#232829;color:#f2f2f2}html.theme--documenter-dark .file-label:hover .file-name{border-color:#596668}html.theme--documenter-dark .file-label:active .file-cta{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .file-label:active .file-name{border-color:#535f61}html.theme--documenter-dark .file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-radius:.4em;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}html.theme--documenter-dark .file-cta{background-color:#282f2f;color:#fff}html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}html.theme--documenter-dark .file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}html.theme--documenter-dark .file-icon .fa{font-size:14px}html.theme--documenter-dark .label{color:#f2f2f2;display:block;font-size:1rem;font-weight:700}html.theme--documenter-dark .label:not(:last-child){margin-bottom:0.5em}html.theme--documenter-dark .label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}html.theme--documenter-dark .label.is-medium{font-size:1.25rem}html.theme--documenter-dark .label.is-large{font-size:1.5rem}html.theme--documenter-dark .help{display:block;font-size:.75rem;margin-top:0.25rem}html.theme--documenter-dark .help.is-white{color:#fff}html.theme--documenter-dark .help.is-black{color:#0a0a0a}html.theme--documenter-dark .help.is-light{color:#ecf0f1}html.theme--documenter-dark .help.is-dark,html.theme--documenter-dark .content kbd.help{color:#282f2f}html.theme--documenter-dark .help.is-primary,html.theme--documenter-dark .docstring>section>a.help.docs-sourcelink{color:#375a7f}html.theme--documenter-dark .help.is-link{color:#1abc9c}html.theme--documenter-dark .help.is-info{color:#024c7d}html.theme--documenter-dark .help.is-success{color:#008438}html.theme--documenter-dark .help.is-warning{color:#ad8100}html.theme--documenter-dark .help.is-danger{color:#9e1b0d}html.theme--documenter-dark .field:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.has-addons{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.has-addons .control:not(:last-child){margin-right:-1px}html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .button,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]){z-index:3}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}html.theme--documenter-dark .field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.has-addons.has-addons-centered{justify-content:center}html.theme--documenter-dark .field.has-addons.has-addons-right{justify-content:flex-end}html.theme--documenter-dark .field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .field.is-grouped{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.is-grouped>.control{flex-shrink:0}html.theme--documenter-dark .field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.is-grouped.is-grouped-centered{justify-content:center}html.theme--documenter-dark .field.is-grouped.is-grouped-right{justify-content:flex-end}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline{flex-wrap:wrap}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:last-child,html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field.is-horizontal{display:flex}}html.theme--documenter-dark .field-label .label{font-size:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}html.theme--documenter-dark .field-label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-normal{padding-top:0.375em}html.theme--documenter-dark .field-label.is-medium{font-size:1.25rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-large{font-size:1.5rem;padding-top:0.375em}}html.theme--documenter-dark .field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}html.theme--documenter-dark .field-body .field{margin-bottom:0}html.theme--documenter-dark .field-body>.field{flex-shrink:1}html.theme--documenter-dark .field-body>.field:not(.is-narrow){flex-grow:1}html.theme--documenter-dark .field-body>.field:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}html.theme--documenter-dark .control.has-icons-left .input:focus~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-left .select:focus~.icon,html.theme--documenter-dark .control.has-icons-right .input:focus~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-right .select:focus~.icon{color:#282f2f}html.theme--documenter-dark .control.has-icons-left .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-small~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-small~.icon{font-size:.75rem}html.theme--documenter-dark .control.has-icons-left .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}html.theme--documenter-dark .control.has-icons-left .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-large~.icon{font-size:1.5rem}html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon{color:#5e6d6f;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}html.theme--documenter-dark .control.has-icons-left .input,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input,html.theme--documenter-dark .control.has-icons-left .select select{padding-left:2.5em}html.theme--documenter-dark .control.has-icons-left .icon.is-left{left:0}html.theme--documenter-dark .control.has-icons-right .input,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input,html.theme--documenter-dark .control.has-icons-right .select select{padding-right:2.5em}html.theme--documenter-dark .control.has-icons-right .icon.is-right{right:0}html.theme--documenter-dark .control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}html.theme--documenter-dark .control.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .control.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .control.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .breadcrumb{font-size:1rem;white-space:nowrap}html.theme--documenter-dark .breadcrumb a{align-items:center;color:#1abc9c;display:flex;justify-content:center;padding:0 .75em}html.theme--documenter-dark .breadcrumb a:hover{color:#1dd2af}html.theme--documenter-dark .breadcrumb li{align-items:center;display:flex}html.theme--documenter-dark .breadcrumb li:first-child a{padding-left:0}html.theme--documenter-dark .breadcrumb li.is-active a{color:#f2f2f2;cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb li+li::before{color:#8c9b9d;content:"\0002f"}html.theme--documenter-dark .breadcrumb ul,html.theme--documenter-dark .breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .breadcrumb .icon:first-child{margin-right:.5em}html.theme--documenter-dark .breadcrumb .icon:last-child{margin-left:.5em}html.theme--documenter-dark .breadcrumb.is-centered ol,html.theme--documenter-dark .breadcrumb.is-centered ul{justify-content:center}html.theme--documenter-dark .breadcrumb.is-right ol,html.theme--documenter-dark .breadcrumb.is-right ul{justify-content:flex-end}html.theme--documenter-dark .breadcrumb.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}html.theme--documenter-dark .breadcrumb.is-medium{font-size:1.25rem}html.theme--documenter-dark .breadcrumb.is-large{font-size:1.5rem}html.theme--documenter-dark .breadcrumb.has-arrow-separator li+li::before{content:"\02192"}html.theme--documenter-dark .breadcrumb.has-bullet-separator li+li::before{content:"\02022"}html.theme--documenter-dark .breadcrumb.has-dot-separator li+li::before{content:"\000b7"}html.theme--documenter-dark .breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}html.theme--documenter-dark .card{background-color:#fff;border-radius:.25rem;box-shadow:#171717;color:#fff;max-width:100%;position:relative}html.theme--documenter-dark .card-footer:first-child,html.theme--documenter-dark .card-content:first-child,html.theme--documenter-dark .card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-footer:last-child,html.theme--documenter-dark .card-content:last-child,html.theme--documenter-dark .card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}html.theme--documenter-dark .card-header-title{align-items:center;color:#f2f2f2;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}html.theme--documenter-dark .card-header-title.is-centered{justify-content:center}html.theme--documenter-dark .card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}html.theme--documenter-dark .card-image{display:block;position:relative}html.theme--documenter-dark .card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-content{background-color:rgba(0,0,0,0);padding:1.5rem}html.theme--documenter-dark .card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}html.theme--documenter-dark .card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}html.theme--documenter-dark .card-footer-item:not(:last-child){border-right:1px solid #ededed}html.theme--documenter-dark .card .media:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .dropdown{display:inline-flex;position:relative;vertical-align:top}html.theme--documenter-dark .dropdown.is-active .dropdown-menu,html.theme--documenter-dark .dropdown.is-hoverable:hover .dropdown-menu{display:block}html.theme--documenter-dark .dropdown.is-right .dropdown-menu{left:auto;right:0}html.theme--documenter-dark .dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}html.theme--documenter-dark .dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .dropdown-content{background-color:#282f2f;border-radius:.4em;box-shadow:#171717;padding-bottom:.5rem;padding-top:.5rem}html.theme--documenter-dark .dropdown-item{color:#fff;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}html.theme--documenter-dark a.dropdown-item,html.theme--documenter-dark button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}html.theme--documenter-dark a.dropdown-item:hover,html.theme--documenter-dark button.dropdown-item:hover{background-color:#282f2f;color:#0a0a0a}html.theme--documenter-dark a.dropdown-item.is-active,html.theme--documenter-dark button.dropdown-item.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}html.theme--documenter-dark .level{align-items:center;justify-content:space-between}html.theme--documenter-dark .level code{border-radius:.4em}html.theme--documenter-dark .level img{display:inline-block;vertical-align:top}html.theme--documenter-dark .level.is-mobile{display:flex}html.theme--documenter-dark .level.is-mobile .level-left,html.theme--documenter-dark .level.is-mobile .level-right{display:flex}html.theme--documenter-dark .level.is-mobile .level-left+.level-right{margin-top:0}html.theme--documenter-dark .level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level{display:flex}html.theme--documenter-dark .level>.level-item:not(.is-narrow){flex-grow:1}}html.theme--documenter-dark .level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}html.theme--documenter-dark .level-item .title,html.theme--documenter-dark .level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){html.theme--documenter-dark .level-item:not(:last-child){margin-bottom:.75rem}}html.theme--documenter-dark .level-left,html.theme--documenter-dark .level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .level-left .level-item.is-flexible,html.theme--documenter-dark .level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left .level-item:not(:last-child),html.theme--documenter-dark .level-right .level-item:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){html.theme--documenter-dark .level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left{display:flex}}html.theme--documenter-dark .level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-right{display:flex}}html.theme--documenter-dark .media{align-items:flex-start;display:flex;text-align:inherit}html.theme--documenter-dark .media .content:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .media .media{border-top:1px solid rgba(94,109,111,0.5);display:flex;padding-top:.75rem}html.theme--documenter-dark .media .media .content:not(:last-child),html.theme--documenter-dark .media .media .control:not(:last-child){margin-bottom:.5rem}html.theme--documenter-dark .media .media .media{padding-top:.5rem}html.theme--documenter-dark .media .media .media+.media{margin-top:.5rem}html.theme--documenter-dark .media+.media{border-top:1px solid rgba(94,109,111,0.5);margin-top:1rem;padding-top:1rem}html.theme--documenter-dark .media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}html.theme--documenter-dark .media-left,html.theme--documenter-dark .media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .media-left{margin-right:1rem}html.theme--documenter-dark .media-right{margin-left:1rem}html.theme--documenter-dark .media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .media-content{overflow-x:auto}}html.theme--documenter-dark .menu{font-size:1rem}html.theme--documenter-dark .menu.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}html.theme--documenter-dark .menu.is-medium{font-size:1.25rem}html.theme--documenter-dark .menu.is-large{font-size:1.5rem}html.theme--documenter-dark .menu-list{line-height:1.25}html.theme--documenter-dark .menu-list a{border-radius:3px;color:#fff;display:block;padding:0.5em 0.75em}html.theme--documenter-dark .menu-list a:hover{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .menu-list a.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .menu-list li ul{border-left:1px solid #5e6d6f;margin:.75em;padding-left:.75em}html.theme--documenter-dark .menu-label{color:#fff;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}html.theme--documenter-dark .menu-label:not(:first-child){margin-top:1em}html.theme--documenter-dark .menu-label:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .message{background-color:#282f2f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .message strong{color:currentColor}html.theme--documenter-dark .message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .message.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}html.theme--documenter-dark .message.is-medium{font-size:1.25rem}html.theme--documenter-dark .message.is-large{font-size:1.5rem}html.theme--documenter-dark .message.is-white{background-color:#fff}html.theme--documenter-dark .message.is-white .message-header{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .message.is-white .message-body{border-color:#fff}html.theme--documenter-dark .message.is-black{background-color:#fafafa}html.theme--documenter-dark .message.is-black .message-header{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .message.is-black .message-body{border-color:#0a0a0a}html.theme--documenter-dark .message.is-light{background-color:#f9fafb}html.theme--documenter-dark .message.is-light .message-header{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .message.is-light .message-body{border-color:#ecf0f1}html.theme--documenter-dark .message.is-dark,html.theme--documenter-dark .content kbd.message{background-color:#f9fafa}html.theme--documenter-dark .message.is-dark .message-header,html.theme--documenter-dark .content kbd.message .message-header{background-color:#282f2f;color:#fff}html.theme--documenter-dark .message.is-dark .message-body,html.theme--documenter-dark .content kbd.message .message-body{border-color:#282f2f}html.theme--documenter-dark .message.is-primary,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink{background-color:#f1f5f9}html.theme--documenter-dark .message.is-primary .message-header,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-header{background-color:#375a7f;color:#fff}html.theme--documenter-dark .message.is-primary .message-body,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-body{border-color:#375a7f;color:#4d7eb2}html.theme--documenter-dark .message.is-link{background-color:#edfdf9}html.theme--documenter-dark .message.is-link .message-header{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .message.is-link .message-body{border-color:#1abc9c;color:#15987e}html.theme--documenter-dark .message.is-info{background-color:#ebf7ff}html.theme--documenter-dark .message.is-info .message-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .message.is-info .message-body{border-color:#024c7d;color:#0e9dfb}html.theme--documenter-dark .message.is-success{background-color:#ebfff3}html.theme--documenter-dark .message.is-success .message-header{background-color:#008438;color:#fff}html.theme--documenter-dark .message.is-success .message-body{border-color:#008438;color:#00eb64}html.theme--documenter-dark .message.is-warning{background-color:#fffaeb}html.theme--documenter-dark .message.is-warning .message-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .message.is-warning .message-body{border-color:#ad8100;color:#d19c00}html.theme--documenter-dark .message.is-danger{background-color:#fdeeec}html.theme--documenter-dark .message.is-danger .message-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .message.is-danger .message-body{border-color:#9e1b0d;color:#ec311d}html.theme--documenter-dark .message-header{align-items:center;background-color:#fff;border-radius:.4em .4em 0 0;color:rgba(0,0,0,0.7);display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}html.theme--documenter-dark .message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}html.theme--documenter-dark .message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}html.theme--documenter-dark .message-body{border-color:#5e6d6f;border-radius:.4em;border-style:solid;border-width:0 0 0 4px;color:#fff;padding:1.25em 1.5em}html.theme--documenter-dark .message-body code,html.theme--documenter-dark .message-body pre{background-color:#fff}html.theme--documenter-dark .message-body pre code{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}html.theme--documenter-dark .modal.is-active{display:flex}html.theme--documenter-dark .modal-background{background-color:rgba(10,10,10,0.86)}html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}html.theme--documenter-dark .modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}html.theme--documenter-dark .modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}html.theme--documenter-dark .modal-card-head,html.theme--documenter-dark .modal-card-foot{align-items:center;background-color:#282f2f;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}html.theme--documenter-dark .modal-card-head{border-bottom:1px solid #5e6d6f;border-top-left-radius:8px;border-top-right-radius:8px}html.theme--documenter-dark .modal-card-title{color:#f2f2f2;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}html.theme--documenter-dark .modal-card-foot{border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid #5e6d6f}html.theme--documenter-dark .modal-card-foot .button:not(:last-child){margin-right:.5em}html.theme--documenter-dark .modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}html.theme--documenter-dark .navbar{background-color:#375a7f;min-height:4rem;position:relative;z-index:30}html.theme--documenter-dark .navbar.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-white .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}html.theme--documenter-dark .navbar.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-black .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}html.theme--documenter-dark .navbar.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-light .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}}html.theme--documenter-dark .navbar.is-dark,html.theme--documenter-dark .content kbd.navbar{background-color:#282f2f;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-burger,html.theme--documenter-dark .content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-dark .navbar-start>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-end>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#282f2f;color:#fff}}html.theme--documenter-dark .navbar.is-primary,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-burger,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-primary .navbar-start>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-end>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#375a7f;color:#fff}}html.theme--documenter-dark .navbar.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-link .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c;color:#fff}}html.theme--documenter-dark .navbar.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-info .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#024c7d;color:#fff}}html.theme--documenter-dark .navbar.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-success .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#008438;color:#fff}}html.theme--documenter-dark .navbar.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-warning .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ad8100;color:#fff}}html.theme--documenter-dark .navbar.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-danger .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#9e1b0d;color:#fff}}html.theme--documenter-dark .navbar>.container{align-items:stretch;display:flex;min-height:4rem;width:100%}html.theme--documenter-dark .navbar.has-shadow{box-shadow:0 2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-bottom,html.theme--documenter-dark .navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-top{top:0}html.theme--documenter-dark html.has-navbar-fixed-top,html.theme--documenter-dark body.has-navbar-fixed-top{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom,html.theme--documenter-dark body.has-navbar-fixed-bottom{padding-bottom:4rem}html.theme--documenter-dark .navbar-brand,html.theme--documenter-dark .navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:4rem}html.theme--documenter-dark .navbar-brand a.navbar-item:focus,html.theme--documenter-dark .navbar-brand a.navbar-item:hover{background-color:transparent}html.theme--documenter-dark .navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}html.theme--documenter-dark .navbar-burger{color:#fff;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:4rem;position:relative;width:4rem;margin-left:auto}html.theme--documenter-dark .navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}html.theme--documenter-dark .navbar-burger span:nth-child(1){top:calc(50% - 6px)}html.theme--documenter-dark .navbar-burger span:nth-child(2){top:calc(50% - 1px)}html.theme--documenter-dark .navbar-burger span:nth-child(3){top:calc(50% + 4px)}html.theme--documenter-dark .navbar-burger:hover{background-color:rgba(0,0,0,0.05)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(2){opacity:0}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}html.theme--documenter-dark .navbar-menu{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{color:#fff;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}html.theme--documenter-dark .navbar-item .icon:only-child,html.theme--documenter-dark .navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}html.theme--documenter-dark a.navbar-item,html.theme--documenter-dark .navbar-link{cursor:pointer}html.theme--documenter-dark a.navbar-item:focus,html.theme--documenter-dark a.navbar-item:focus-within,html.theme--documenter-dark a.navbar-item:hover,html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link:focus,html.theme--documenter-dark .navbar-link:focus-within,html.theme--documenter-dark .navbar-link:hover,html.theme--documenter-dark .navbar-link.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-item{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .navbar-item img{max-height:1.75rem}html.theme--documenter-dark .navbar-item.has-dropdown{padding:0}html.theme--documenter-dark .navbar-item.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-item.is-tab{border-bottom:1px solid transparent;min-height:4rem;padding-bottom:calc(0.5rem - 1px)}html.theme--documenter-dark .navbar-item.is-tab:focus,html.theme--documenter-dark .navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c}html.theme--documenter-dark .navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c;border-bottom-style:solid;border-bottom-width:3px;color:#1abc9c;padding-bottom:calc(0.5rem - 3px)}html.theme--documenter-dark .navbar-content{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-link:not(.is-arrowless){padding-right:2.5em}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after{border-color:#fff;margin-top:-0.375em;right:1.125em}html.theme--documenter-dark .navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}html.theme--documenter-dark .navbar-divider{background-color:rgba(0,0,0,0.2);border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar>.container{display:block}html.theme--documenter-dark .navbar-brand .navbar-item,html.theme--documenter-dark .navbar-tabs .navbar-item{align-items:center;display:flex}html.theme--documenter-dark .navbar-link::after{display:none}html.theme--documenter-dark .navbar-menu{background-color:#375a7f;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}html.theme--documenter-dark .navbar-menu.is-active{display:block}html.theme--documenter-dark .navbar.is-fixed-bottom-touch,html.theme--documenter-dark .navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-touch{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-touch{top:0}html.theme--documenter-dark .navbar.is-fixed-top .navbar-menu,html.theme--documenter-dark .navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 4rem);overflow:auto}html.theme--documenter-dark html.has-navbar-fixed-top-touch,html.theme--documenter-dark body.has-navbar-fixed-top-touch{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-touch,html.theme--documenter-dark body.has-navbar-fixed-bottom-touch{padding-bottom:4rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar,html.theme--documenter-dark .navbar-menu,html.theme--documenter-dark .navbar-start,html.theme--documenter-dark .navbar-end{align-items:stretch;display:flex}html.theme--documenter-dark .navbar{min-height:4rem}html.theme--documenter-dark .navbar.is-spaced{padding:1rem 2rem}html.theme--documenter-dark .navbar.is-spaced .navbar-start,html.theme--documenter-dark .navbar.is-spaced .navbar-end{align-items:center}html.theme--documenter-dark .navbar.is-spaced a.navbar-item,html.theme--documenter-dark .navbar.is-spaced .navbar-link{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent a.navbar-item:hover,html.theme--documenter-dark .navbar.is-transparent a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-transparent .navbar-link:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-link:hover,html.theme--documenter-dark .navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-burger{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{align-items:center;display:flex}html.theme--documenter-dark .navbar-item.has-dropdown{align-items:stretch}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:1px solid rgba(0,0,0,0.2);border-radius:8px 8px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}html.theme--documenter-dark .navbar-menu{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .navbar-start{justify-content:flex-start;margin-right:auto}html.theme--documenter-dark .navbar-end{justify-content:flex-end;margin-left:auto}html.theme--documenter-dark .navbar-dropdown{background-color:#375a7f;border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid rgba(0,0,0,0.2);box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}html.theme--documenter-dark .navbar-dropdown a.navbar-item{padding-right:3rem}html.theme--documenter-dark .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}.navbar.is-spaced html.theme--documenter-dark .navbar-dropdown,html.theme--documenter-dark .navbar-dropdown.is-boxed{border-radius:8px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}html.theme--documenter-dark .navbar-dropdown.is-right{left:auto;right:0}html.theme--documenter-dark .navbar-divider{display:block}html.theme--documenter-dark .navbar>.container .navbar-brand,html.theme--documenter-dark .container>.navbar .navbar-brand{margin-left:-.75rem}html.theme--documenter-dark .navbar>.container .navbar-menu,html.theme--documenter-dark .container>.navbar .navbar-menu{margin-right:-.75rem}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop,html.theme--documenter-dark .navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-desktop{top:0}html.theme--documenter-dark html.has-navbar-fixed-top-desktop,html.theme--documenter-dark body.has-navbar-fixed-top-desktop{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-desktop,html.theme--documenter-dark body.has-navbar-fixed-bottom-desktop{padding-bottom:4rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-top,html.theme--documenter-dark body.has-spaced-navbar-fixed-top{padding-top:6rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-bottom,html.theme--documenter-dark body.has-spaced-navbar-fixed-bottom{padding-bottom:6rem}html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link.is-active{color:#1abc9c}html.theme--documenter-dark a.navbar-item.is-active:not(:focus):not(:hover),html.theme--documenter-dark .navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}html.theme--documenter-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown.is-active .navbar-link{background-color:rgba(0,0,0,0)}}html.theme--documenter-dark .hero.is-fullheight-with-navbar{min-height:calc(100vh - 4rem)}html.theme--documenter-dark .pagination{font-size:1rem;margin:-.25rem}html.theme--documenter-dark .pagination.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}html.theme--documenter-dark .pagination.is-medium{font-size:1.25rem}html.theme--documenter-dark .pagination.is-large{font-size:1.5rem}html.theme--documenter-dark .pagination.is-rounded .pagination-previous,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,html.theme--documenter-dark .pagination.is-rounded .pagination-next,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}html.theme--documenter-dark .pagination.is-rounded .pagination-link,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}html.theme--documenter-dark .pagination,html.theme--documenter-dark .pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link{border-color:#5e6d6f;color:#1abc9c;min-width:2.5em}html.theme--documenter-dark .pagination-previous:hover,html.theme--documenter-dark .pagination-next:hover,html.theme--documenter-dark .pagination-link:hover{border-color:#8c9b9d;color:#1dd2af}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus{border-color:#8c9b9d}html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-previous.is-disabled,html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-next.is-disabled,html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-link.is-disabled{background-color:#5e6d6f;border-color:#5e6d6f;box-shadow:none;color:#fff;opacity:0.5}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}html.theme--documenter-dark .pagination-link.is-current{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .pagination-ellipsis{color:#8c9b9d;pointer-events:none}html.theme--documenter-dark .pagination-list{flex-wrap:wrap}html.theme--documenter-dark .pagination-list li{list-style:none}@media screen and (max-width: 768px){html.theme--documenter-dark .pagination{flex-wrap:wrap}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination-previous{order:2}html.theme--documenter-dark .pagination-next{order:3}html.theme--documenter-dark .pagination{justify-content:space-between;margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination.is-centered .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-centered .pagination-list{justify-content:center;order:2}html.theme--documenter-dark .pagination.is-centered .pagination-next{order:3}html.theme--documenter-dark .pagination.is-right .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-right .pagination-next{order:2}html.theme--documenter-dark .pagination.is-right .pagination-list{justify-content:flex-end;order:3}}html.theme--documenter-dark .panel{border-radius:8px;box-shadow:#171717;font-size:1rem}html.theme--documenter-dark .panel:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}html.theme--documenter-dark .panel.is-white .panel-block.is-active .panel-icon{color:#fff}html.theme--documenter-dark .panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}html.theme--documenter-dark .panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}html.theme--documenter-dark .panel.is-light .panel-heading{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .panel.is-light .panel-tabs a.is-active{border-bottom-color:#ecf0f1}html.theme--documenter-dark .panel.is-light .panel-block.is-active .panel-icon{color:#ecf0f1}html.theme--documenter-dark .panel.is-dark .panel-heading,html.theme--documenter-dark .content kbd.panel .panel-heading{background-color:#282f2f;color:#fff}html.theme--documenter-dark .panel.is-dark .panel-tabs a.is-active,html.theme--documenter-dark .content kbd.panel .panel-tabs a.is-active{border-bottom-color:#282f2f}html.theme--documenter-dark .panel.is-dark .panel-block.is-active .panel-icon,html.theme--documenter-dark .content kbd.panel .panel-block.is-active .panel-icon{color:#282f2f}html.theme--documenter-dark .panel.is-primary .panel-heading,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#375a7f;color:#fff}html.theme--documenter-dark .panel.is-primary .panel-tabs a.is-active,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#375a7f}html.theme--documenter-dark .panel.is-primary .panel-block.is-active .panel-icon,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#375a7f}html.theme--documenter-dark .panel.is-link .panel-heading{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .panel.is-link .panel-tabs a.is-active{border-bottom-color:#1abc9c}html.theme--documenter-dark .panel.is-link .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel.is-info .panel-heading{background-color:#024c7d;color:#fff}html.theme--documenter-dark .panel.is-info .panel-tabs a.is-active{border-bottom-color:#024c7d}html.theme--documenter-dark .panel.is-info .panel-block.is-active .panel-icon{color:#024c7d}html.theme--documenter-dark .panel.is-success .panel-heading{background-color:#008438;color:#fff}html.theme--documenter-dark .panel.is-success .panel-tabs a.is-active{border-bottom-color:#008438}html.theme--documenter-dark .panel.is-success .panel-block.is-active .panel-icon{color:#008438}html.theme--documenter-dark .panel.is-warning .panel-heading{background-color:#ad8100;color:#fff}html.theme--documenter-dark .panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ad8100}html.theme--documenter-dark .panel.is-warning .panel-block.is-active .panel-icon{color:#ad8100}html.theme--documenter-dark .panel.is-danger .panel-heading{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .panel.is-danger .panel-tabs a.is-active{border-bottom-color:#9e1b0d}html.theme--documenter-dark .panel.is-danger .panel-block.is-active .panel-icon{color:#9e1b0d}html.theme--documenter-dark .panel-tabs:not(:last-child),html.theme--documenter-dark .panel-block:not(:last-child){border-bottom:1px solid #ededed}html.theme--documenter-dark .panel-heading{background-color:#343c3d;border-radius:8px 8px 0 0;color:#f2f2f2;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}html.theme--documenter-dark .panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}html.theme--documenter-dark .panel-tabs a{border-bottom:1px solid #5e6d6f;margin-bottom:-1px;padding:0.5em}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#343c3d;color:#17a689}html.theme--documenter-dark .panel-list a{color:#fff}html.theme--documenter-dark .panel-list a:hover{color:#1abc9c}html.theme--documenter-dark .panel-block{align-items:center;color:#f2f2f2;display:flex;justify-content:flex-start;padding:0.5em 0.75em}html.theme--documenter-dark .panel-block input[type="checkbox"]{margin-right:.75em}html.theme--documenter-dark .panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}html.theme--documenter-dark .panel-block.is-wrapped{flex-wrap:wrap}html.theme--documenter-dark .panel-block.is-active{border-left-color:#1abc9c;color:#17a689}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel-block:last-child{border-bottom-left-radius:8px;border-bottom-right-radius:8px}html.theme--documenter-dark a.panel-block,html.theme--documenter-dark label.panel-block{cursor:pointer}html.theme--documenter-dark a.panel-block:hover,html.theme--documenter-dark label.panel-block:hover{background-color:#282f2f}html.theme--documenter-dark .panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#fff;margin-right:.75em}html.theme--documenter-dark .panel-icon .fa{font-size:inherit;line-height:inherit}html.theme--documenter-dark .tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}html.theme--documenter-dark .tabs a{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;color:#fff;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}html.theme--documenter-dark .tabs a:hover{border-bottom-color:#f2f2f2;color:#f2f2f2}html.theme--documenter-dark .tabs li{display:block}html.theme--documenter-dark .tabs li.is-active a{border-bottom-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .tabs ul{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}html.theme--documenter-dark .tabs ul.is-left{padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}html.theme--documenter-dark .tabs .icon:first-child{margin-right:.5em}html.theme--documenter-dark .tabs .icon:last-child{margin-left:.5em}html.theme--documenter-dark .tabs.is-centered ul{justify-content:center}html.theme--documenter-dark .tabs.is-right ul{justify-content:flex-end}html.theme--documenter-dark .tabs.is-boxed a{border:1px solid transparent;border-radius:.4em .4em 0 0}html.theme--documenter-dark .tabs.is-boxed a:hover{background-color:#282f2f;border-bottom-color:#5e6d6f}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#fff;border-color:#5e6d6f;border-bottom-color:rgba(0,0,0,0) !important}html.theme--documenter-dark .tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .tabs.is-toggle a{border-color:#5e6d6f;border-style:solid;border-width:1px;margin-bottom:0;position:relative}html.theme--documenter-dark .tabs.is-toggle a:hover{background-color:#282f2f;border-color:#8c9b9d;z-index:2}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .tabs.is-toggle li:first-child a{border-top-left-radius:.4em;border-bottom-left-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li:last-child a{border-top-right-radius:.4em;border-bottom-right-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li.is-active a{background-color:#1abc9c;border-color:#1abc9c;color:#fff;z-index:1}html.theme--documenter-dark .tabs.is-toggle ul{border-bottom:none}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}html.theme--documenter-dark .tabs.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}html.theme--documenter-dark .tabs.is-medium{font-size:1.25rem}html.theme--documenter-dark .tabs.is-large{font-size:1.5rem}html.theme--documenter-dark .column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>html.theme--documenter-dark .column.is-narrow{flex:none;width:unset}.columns.is-mobile>html.theme--documenter-dark .column.is-full{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-half{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-half{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-0{flex:none;width:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-0{margin-left:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-3{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-3{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-6{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-6{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-9{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-9{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-12{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){html.theme--documenter-dark .column.is-narrow-mobile{flex:none;width:unset}html.theme--documenter-dark .column.is-full-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-mobile{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-mobile{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-mobile{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-mobile{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-mobile{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-mobile{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-mobile{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-mobile{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-mobile{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-mobile{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-mobile{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-mobile{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-mobile{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-mobile{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-mobile{margin-left:80%}html.theme--documenter-dark .column.is-0-mobile{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-mobile{margin-left:0%}html.theme--documenter-dark .column.is-1-mobile{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-mobile{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-mobile{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-mobile{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-mobile{margin-left:25%}html.theme--documenter-dark .column.is-4-mobile{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-mobile{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-mobile{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-mobile{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-mobile{margin-left:50%}html.theme--documenter-dark .column.is-7-mobile{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-mobile{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-mobile{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-mobile{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-mobile{margin-left:75%}html.theme--documenter-dark .column.is-10-mobile{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-mobile{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-mobile{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-mobile{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .column.is-narrow,html.theme--documenter-dark .column.is-narrow-tablet{flex:none;width:unset}html.theme--documenter-dark .column.is-full,html.theme--documenter-dark .column.is-full-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters,html.theme--documenter-dark .column.is-three-quarters-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds,html.theme--documenter-dark .column.is-two-thirds-tablet{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half,html.theme--documenter-dark .column.is-half-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third,html.theme--documenter-dark .column.is-one-third-tablet{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter,html.theme--documenter-dark .column.is-one-quarter-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth,html.theme--documenter-dark .column.is-one-fifth-tablet{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths,html.theme--documenter-dark .column.is-two-fifths-tablet{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths,html.theme--documenter-dark .column.is-three-fifths-tablet{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths,html.theme--documenter-dark .column.is-four-fifths-tablet{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters,html.theme--documenter-dark .column.is-offset-three-quarters-tablet{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds,html.theme--documenter-dark .column.is-offset-two-thirds-tablet{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half,html.theme--documenter-dark .column.is-offset-half-tablet{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third,html.theme--documenter-dark .column.is-offset-one-third-tablet{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter,html.theme--documenter-dark .column.is-offset-one-quarter-tablet{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth,html.theme--documenter-dark .column.is-offset-one-fifth-tablet{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths,html.theme--documenter-dark .column.is-offset-two-fifths-tablet{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths,html.theme--documenter-dark .column.is-offset-three-fifths-tablet{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths,html.theme--documenter-dark .column.is-offset-four-fifths-tablet{margin-left:80%}html.theme--documenter-dark .column.is-0,html.theme--documenter-dark .column.is-0-tablet{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0,html.theme--documenter-dark .column.is-offset-0-tablet{margin-left:0%}html.theme--documenter-dark .column.is-1,html.theme--documenter-dark .column.is-1-tablet{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1,html.theme--documenter-dark .column.is-offset-1-tablet{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2,html.theme--documenter-dark .column.is-2-tablet{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2,html.theme--documenter-dark .column.is-offset-2-tablet{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3,html.theme--documenter-dark .column.is-3-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3,html.theme--documenter-dark .column.is-offset-3-tablet{margin-left:25%}html.theme--documenter-dark .column.is-4,html.theme--documenter-dark .column.is-4-tablet{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4,html.theme--documenter-dark .column.is-offset-4-tablet{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5,html.theme--documenter-dark .column.is-5-tablet{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5,html.theme--documenter-dark .column.is-offset-5-tablet{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6,html.theme--documenter-dark .column.is-6-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6,html.theme--documenter-dark .column.is-offset-6-tablet{margin-left:50%}html.theme--documenter-dark .column.is-7,html.theme--documenter-dark .column.is-7-tablet{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7,html.theme--documenter-dark .column.is-offset-7-tablet{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8,html.theme--documenter-dark .column.is-8-tablet{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8,html.theme--documenter-dark .column.is-offset-8-tablet{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9,html.theme--documenter-dark .column.is-9-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9,html.theme--documenter-dark .column.is-offset-9-tablet{margin-left:75%}html.theme--documenter-dark .column.is-10,html.theme--documenter-dark .column.is-10-tablet{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10,html.theme--documenter-dark .column.is-offset-10-tablet{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11,html.theme--documenter-dark .column.is-11-tablet{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11,html.theme--documenter-dark .column.is-offset-11-tablet{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12,html.theme--documenter-dark .column.is-12-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12,html.theme--documenter-dark .column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){html.theme--documenter-dark .column.is-narrow-touch{flex:none;width:unset}html.theme--documenter-dark .column.is-full-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-touch{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-touch{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-touch{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-touch{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-touch{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-touch{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-touch{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-touch{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-touch{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-touch{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-touch{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-touch{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-touch{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-touch{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-touch{margin-left:80%}html.theme--documenter-dark .column.is-0-touch{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-touch{margin-left:0%}html.theme--documenter-dark .column.is-1-touch{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-touch{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-touch{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-touch{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-touch{margin-left:25%}html.theme--documenter-dark .column.is-4-touch{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-touch{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-touch{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-touch{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-touch{margin-left:50%}html.theme--documenter-dark .column.is-7-touch{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-touch{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-touch{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-touch{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-touch{margin-left:75%}html.theme--documenter-dark .column.is-10-touch{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-touch{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-touch{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-touch{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){html.theme--documenter-dark .column.is-narrow-desktop{flex:none;width:unset}html.theme--documenter-dark .column.is-full-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-desktop{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-desktop{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-desktop{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-desktop{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-desktop{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-desktop{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-desktop{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-desktop{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-desktop{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-desktop{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-desktop{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-desktop{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-desktop{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-desktop{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-desktop{margin-left:80%}html.theme--documenter-dark .column.is-0-desktop{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-desktop{margin-left:0%}html.theme--documenter-dark .column.is-1-desktop{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-desktop{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-desktop{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-desktop{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-desktop{margin-left:25%}html.theme--documenter-dark .column.is-4-desktop{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-desktop{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-desktop{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-desktop{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-desktop{margin-left:50%}html.theme--documenter-dark .column.is-7-desktop{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-desktop{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-desktop{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-desktop{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-desktop{margin-left:75%}html.theme--documenter-dark .column.is-10-desktop{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-desktop{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-desktop{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-desktop{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){html.theme--documenter-dark .column.is-narrow-widescreen{flex:none;width:unset}html.theme--documenter-dark .column.is-full-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-widescreen{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-widescreen{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-widescreen{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-widescreen{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-widescreen{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-widescreen{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-widescreen{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-widescreen{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-widescreen{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-widescreen{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-widescreen{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-widescreen{margin-left:80%}html.theme--documenter-dark .column.is-0-widescreen{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-widescreen{margin-left:0%}html.theme--documenter-dark .column.is-1-widescreen{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-widescreen{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-widescreen{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-widescreen{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-4-widescreen{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-widescreen{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-widescreen{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-widescreen{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-7-widescreen{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-widescreen{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-widescreen{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-widescreen{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-10-widescreen{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-widescreen{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-widescreen{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-widescreen{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){html.theme--documenter-dark .column.is-narrow-fullhd{flex:none;width:unset}html.theme--documenter-dark .column.is-full-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-fullhd{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-fullhd{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-fullhd{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-fullhd{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-fullhd{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-fullhd{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-fullhd{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-fullhd{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-fullhd{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-fullhd{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-fullhd{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-fullhd{margin-left:80%}html.theme--documenter-dark .column.is-0-fullhd{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-fullhd{margin-left:0%}html.theme--documenter-dark .column.is-1-fullhd{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-fullhd{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-fullhd{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-fullhd{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-4-fullhd{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-fullhd{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-fullhd{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-fullhd{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-7-fullhd{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-fullhd{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-fullhd{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-fullhd{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-10-fullhd{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-fullhd{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-fullhd{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-fullhd{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-fullhd{margin-left:100%}}html.theme--documenter-dark .columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .columns:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}html.theme--documenter-dark .columns.is-centered{justify-content:center}html.theme--documenter-dark .columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}html.theme--documenter-dark .columns.is-gapless>.column{margin:0;padding:0 !important}html.theme--documenter-dark .columns.is-gapless:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .columns.is-gapless:last-child{margin-bottom:0}html.theme--documenter-dark .columns.is-mobile{display:flex}html.theme--documenter-dark .columns.is-multiline{flex-wrap:wrap}html.theme--documenter-dark .columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-desktop{display:flex}}html.theme--documenter-dark .columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}html.theme--documenter-dark .columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}html.theme--documenter-dark .columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-0-fullhd{--columnGap: 0rem}}html.theme--documenter-dark .columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-1-fullhd{--columnGap: .25rem}}html.theme--documenter-dark .columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-2-fullhd{--columnGap: .5rem}}html.theme--documenter-dark .columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-3-fullhd{--columnGap: .75rem}}html.theme--documenter-dark .columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-4-fullhd{--columnGap: 1rem}}html.theme--documenter-dark .columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}html.theme--documenter-dark .columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}html.theme--documenter-dark .columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}html.theme--documenter-dark .columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-8-fullhd{--columnGap: 2rem}}html.theme--documenter-dark .tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}html.theme--documenter-dark .tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .tile.is-ancestor:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .tile.is-ancestor:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .tile.is-child{margin:0 !important}html.theme--documenter-dark .tile.is-parent{padding:.75rem}html.theme--documenter-dark .tile.is-vertical{flex-direction:column}html.theme--documenter-dark .tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{html.theme--documenter-dark .tile:not(.is-child){display:flex}html.theme--documenter-dark .tile.is-1{flex:none;width:8.33333337%}html.theme--documenter-dark .tile.is-2{flex:none;width:16.66666674%}html.theme--documenter-dark .tile.is-3{flex:none;width:25%}html.theme--documenter-dark .tile.is-4{flex:none;width:33.33333337%}html.theme--documenter-dark .tile.is-5{flex:none;width:41.66666674%}html.theme--documenter-dark .tile.is-6{flex:none;width:50%}html.theme--documenter-dark .tile.is-7{flex:none;width:58.33333337%}html.theme--documenter-dark .tile.is-8{flex:none;width:66.66666674%}html.theme--documenter-dark .tile.is-9{flex:none;width:75%}html.theme--documenter-dark .tile.is-10{flex:none;width:83.33333337%}html.theme--documenter-dark .tile.is-11{flex:none;width:91.66666674%}html.theme--documenter-dark .tile.is-12{flex:none;width:100%}}html.theme--documenter-dark .hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}html.theme--documenter-dark .hero .navbar{background:none}html.theme--documenter-dark .hero .tabs ul{border-bottom:none}html.theme--documenter-dark .hero.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-white strong{color:inherit}html.theme--documenter-dark .hero.is-white .title{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .subtitle{color:rgba(10,10,10,0.9)}html.theme--documenter-dark .hero.is-white .subtitle a:not(.button),html.theme--documenter-dark .hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-white .navbar-menu{background-color:#fff}}html.theme--documenter-dark .hero.is-white .navbar-item,html.theme--documenter-dark .hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}html.theme--documenter-dark .hero.is-white a.navbar-item:hover,html.theme--documenter-dark .hero.is-white a.navbar-item.is-active,html.theme--documenter-dark .hero.is-white .navbar-link:hover,html.theme--documenter-dark .hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}html.theme--documenter-dark .hero.is-white .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}html.theme--documenter-dark .hero.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-black strong{color:inherit}html.theme--documenter-dark .hero.is-black .title{color:#fff}html.theme--documenter-dark .hero.is-black .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-black .subtitle a:not(.button),html.theme--documenter-dark .hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-black .navbar-menu{background-color:#0a0a0a}}html.theme--documenter-dark .hero.is-black .navbar-item,html.theme--documenter-dark .hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-black a.navbar-item:hover,html.theme--documenter-dark .hero.is-black a.navbar-item.is-active,html.theme--documenter-dark .hero.is-black .navbar-link:hover,html.theme--documenter-dark .hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .hero.is-black .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-black .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}html.theme--documenter-dark .hero.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-light strong{color:inherit}html.theme--documenter-dark .hero.is-light .title{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .subtitle{color:rgba(0,0,0,0.9)}html.theme--documenter-dark .hero.is-light .subtitle a:not(.button),html.theme--documenter-dark .hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-light .navbar-menu{background-color:#ecf0f1}}html.theme--documenter-dark .hero.is-light .navbar-item,html.theme--documenter-dark .hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a.navbar-item:hover,html.theme--documenter-dark .hero.is-light a.navbar-item.is-active,html.theme--documenter-dark .hero.is-light .navbar-link:hover,html.theme--documenter-dark .hero.is-light .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}html.theme--documenter-dark .hero.is-light .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-light .tabs li.is-active a{color:#ecf0f1 !important;opacity:1}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .hero.is-light.is-bold{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}}html.theme--documenter-dark .hero.is-dark,html.theme--documenter-dark .content kbd.hero{background-color:#282f2f;color:#fff}html.theme--documenter-dark .hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-dark strong,html.theme--documenter-dark .content kbd.hero strong{color:inherit}html.theme--documenter-dark .hero.is-dark .title,html.theme--documenter-dark .content kbd.hero .title{color:#fff}html.theme--documenter-dark .hero.is-dark .subtitle,html.theme--documenter-dark .content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-dark .subtitle a:not(.button),html.theme--documenter-dark .content kbd.hero .subtitle a:not(.button),html.theme--documenter-dark .hero.is-dark .subtitle strong,html.theme--documenter-dark .content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-dark .navbar-menu,html.theme--documenter-dark .content kbd.hero .navbar-menu{background-color:#282f2f}}html.theme--documenter-dark .hero.is-dark .navbar-item,html.theme--documenter-dark .content kbd.hero .navbar-item,html.theme--documenter-dark .hero.is-dark .navbar-link,html.theme--documenter-dark .content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-dark a.navbar-item:hover,html.theme--documenter-dark .content kbd.hero a.navbar-item:hover,html.theme--documenter-dark .hero.is-dark a.navbar-item.is-active,html.theme--documenter-dark .content kbd.hero a.navbar-item.is-active,html.theme--documenter-dark .hero.is-dark .navbar-link:hover,html.theme--documenter-dark .content kbd.hero .navbar-link:hover,html.theme--documenter-dark .hero.is-dark .navbar-link.is-active,html.theme--documenter-dark .content kbd.hero .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .hero.is-dark .tabs a,html.theme--documenter-dark .content kbd.hero .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-dark .tabs a:hover,html.theme--documenter-dark .content kbd.hero .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-dark .tabs li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs li.is-active a{color:#282f2f !important;opacity:1}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#282f2f}html.theme--documenter-dark .hero.is-dark.is-bold,html.theme--documenter-dark .content kbd.hero.is-bold{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-dark.is-bold .navbar-menu,html.theme--documenter-dark .content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}}html.theme--documenter-dark .hero.is-primary,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-primary strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink strong{color:inherit}html.theme--documenter-dark .hero.is-primary .title,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .title{color:#fff}html.theme--documenter-dark .hero.is-primary .subtitle,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-primary .subtitle a:not(.button),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),html.theme--documenter-dark .hero.is-primary .subtitle strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-primary .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#375a7f}}html.theme--documenter-dark .hero.is-primary .navbar-item,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-item,html.theme--documenter-dark .hero.is-primary .navbar-link,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-primary a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,html.theme--documenter-dark .hero.is-primary a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,html.theme--documenter-dark .hero.is-primary .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link:hover,html.theme--documenter-dark .hero.is-primary .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .hero.is-primary .tabs a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-primary .tabs a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-primary .tabs li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#375a7f !important;opacity:1}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#375a7f}html.theme--documenter-dark .hero.is-primary.is-bold,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-primary.is-bold .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}}html.theme--documenter-dark .hero.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-link strong{color:inherit}html.theme--documenter-dark .hero.is-link .title{color:#fff}html.theme--documenter-dark .hero.is-link .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-link .subtitle a:not(.button),html.theme--documenter-dark .hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-link .navbar-menu{background-color:#1abc9c}}html.theme--documenter-dark .hero.is-link .navbar-item,html.theme--documenter-dark .hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-link a.navbar-item:hover,html.theme--documenter-dark .hero.is-link a.navbar-item.is-active,html.theme--documenter-dark .hero.is-link .navbar-link:hover,html.theme--documenter-dark .hero.is-link .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .hero.is-link .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-link .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-link .tabs li.is-active a{color:#1abc9c !important;opacity:1}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#1abc9c}html.theme--documenter-dark .hero.is-link.is-bold{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}}html.theme--documenter-dark .hero.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-info strong{color:inherit}html.theme--documenter-dark .hero.is-info .title{color:#fff}html.theme--documenter-dark .hero.is-info .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-info .subtitle a:not(.button),html.theme--documenter-dark .hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-info .navbar-menu{background-color:#024c7d}}html.theme--documenter-dark .hero.is-info .navbar-item,html.theme--documenter-dark .hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-info a.navbar-item:hover,html.theme--documenter-dark .hero.is-info a.navbar-item.is-active,html.theme--documenter-dark .hero.is-info .navbar-link:hover,html.theme--documenter-dark .hero.is-info .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .hero.is-info .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-info .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-info .tabs li.is-active a{color:#024c7d !important;opacity:1}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#024c7d}html.theme--documenter-dark .hero.is-info.is-bold{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}}html.theme--documenter-dark .hero.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-success strong{color:inherit}html.theme--documenter-dark .hero.is-success .title{color:#fff}html.theme--documenter-dark .hero.is-success .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-success .subtitle a:not(.button),html.theme--documenter-dark .hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-success .navbar-menu{background-color:#008438}}html.theme--documenter-dark .hero.is-success .navbar-item,html.theme--documenter-dark .hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-success a.navbar-item:hover,html.theme--documenter-dark .hero.is-success a.navbar-item.is-active,html.theme--documenter-dark .hero.is-success .navbar-link:hover,html.theme--documenter-dark .hero.is-success .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .hero.is-success .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-success .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-success .tabs li.is-active a{color:#008438 !important;opacity:1}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#008438}html.theme--documenter-dark .hero.is-success.is-bold{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}}html.theme--documenter-dark .hero.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-warning strong{color:inherit}html.theme--documenter-dark .hero.is-warning .title{color:#fff}html.theme--documenter-dark .hero.is-warning .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-warning .subtitle a:not(.button),html.theme--documenter-dark .hero.is-warning .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-warning .navbar-menu{background-color:#ad8100}}html.theme--documenter-dark .hero.is-warning .navbar-item,html.theme--documenter-dark .hero.is-warning .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-warning a.navbar-item:hover,html.theme--documenter-dark .hero.is-warning a.navbar-item.is-active,html.theme--documenter-dark .hero.is-warning .navbar-link:hover,html.theme--documenter-dark .hero.is-warning .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .hero.is-warning .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-warning .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-warning .tabs li.is-active a{color:#ad8100 !important;opacity:1}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#ad8100}html.theme--documenter-dark .hero.is-warning.is-bold{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}}html.theme--documenter-dark .hero.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-danger strong{color:inherit}html.theme--documenter-dark .hero.is-danger .title{color:#fff}html.theme--documenter-dark .hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-danger .subtitle a:not(.button),html.theme--documenter-dark .hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-danger .navbar-menu{background-color:#9e1b0d}}html.theme--documenter-dark .hero.is-danger .navbar-item,html.theme--documenter-dark .hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-danger a.navbar-item:hover,html.theme--documenter-dark .hero.is-danger a.navbar-item.is-active,html.theme--documenter-dark .hero.is-danger .navbar-link:hover,html.theme--documenter-dark .hero.is-danger .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .hero.is-danger .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-danger .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-danger .tabs li.is-active a{color:#9e1b0d !important;opacity:1}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#9e1b0d}html.theme--documenter-dark .hero.is-danger.is-bold{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}}html.theme--documenter-dark .hero.is-small .hero-body,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-large .hero-body{padding:18rem 6rem}}html.theme--documenter-dark .hero.is-halfheight .hero-body,html.theme--documenter-dark .hero.is-fullheight .hero-body,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}html.theme--documenter-dark .hero.is-halfheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .hero.is-halfheight{min-height:50vh}html.theme--documenter-dark .hero.is-fullheight{min-height:100vh}html.theme--documenter-dark .hero-video{overflow:hidden}html.theme--documenter-dark .hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}html.theme--documenter-dark .hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-video{display:none}}html.theme--documenter-dark .hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-buttons .button{display:flex}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-buttons{display:flex;justify-content:center}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-right:1.5rem}}html.theme--documenter-dark .hero-head,html.theme--documenter-dark .hero-foot{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-body{padding:3rem 3rem}}html.theme--documenter-dark .section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){html.theme--documenter-dark .section{padding:3rem 3rem}html.theme--documenter-dark .section.is-medium{padding:9rem 4.5rem}html.theme--documenter-dark .section.is-large{padding:18rem 6rem}}html.theme--documenter-dark .footer{background-color:#282f2f;padding:3rem 1.5rem 6rem}html.theme--documenter-dark hr{height:1px}html.theme--documenter-dark h6{text-transform:uppercase;letter-spacing:0.5px}html.theme--documenter-dark .hero{background-color:#343c3d}html.theme--documenter-dark a{transition:all 200ms ease}html.theme--documenter-dark .button{transition:all 200ms ease;border-width:1px;color:#fff}html.theme--documenter-dark .button.is-active,html.theme--documenter-dark .button.is-focused,html.theme--documenter-dark .button:active,html.theme--documenter-dark .button:focus{box-shadow:0 0 0 2px rgba(140,155,157,0.5)}html.theme--documenter-dark .button.is-white.is-hovered,html.theme--documenter-dark .button.is-white:hover{background-color:#fff}html.theme--documenter-dark .button.is-white.is-active,html.theme--documenter-dark .button.is-white.is-focused,html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white:focus{border-color:#fff;box-shadow:0 0 0 2px rgba(255,255,255,0.5)}html.theme--documenter-dark .button.is-black.is-hovered,html.theme--documenter-dark .button.is-black:hover{background-color:#1d1d1d}html.theme--documenter-dark .button.is-black.is-active,html.theme--documenter-dark .button.is-black.is-focused,html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black:focus{border-color:#0a0a0a;box-shadow:0 0 0 2px rgba(10,10,10,0.5)}html.theme--documenter-dark .button.is-light.is-hovered,html.theme--documenter-dark .button.is-light:hover{background-color:#fff}html.theme--documenter-dark .button.is-light.is-active,html.theme--documenter-dark .button.is-light.is-focused,html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light:focus{border-color:#ecf0f1;box-shadow:0 0 0 2px rgba(236,240,241,0.5)}html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered,html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover{background-color:#3a4344}html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused,html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus{border-color:#282f2f;box-shadow:0 0 0 2px rgba(40,47,47,0.5)}html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover{background-color:#436d9a}html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink,html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus{border-color:#375a7f;box-shadow:0 0 0 2px rgba(55,90,127,0.5)}html.theme--documenter-dark .button.is-link.is-hovered,html.theme--documenter-dark .button.is-link:hover{background-color:#1fdeb8}html.theme--documenter-dark .button.is-link.is-active,html.theme--documenter-dark .button.is-link.is-focused,html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link:focus{border-color:#1abc9c;box-shadow:0 0 0 2px rgba(26,188,156,0.5)}html.theme--documenter-dark .button.is-info.is-hovered,html.theme--documenter-dark .button.is-info:hover{background-color:#0363a3}html.theme--documenter-dark .button.is-info.is-active,html.theme--documenter-dark .button.is-info.is-focused,html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info:focus{border-color:#024c7d;box-shadow:0 0 0 2px rgba(2,76,125,0.5)}html.theme--documenter-dark .button.is-success.is-hovered,html.theme--documenter-dark .button.is-success:hover{background-color:#00aa48}html.theme--documenter-dark .button.is-success.is-active,html.theme--documenter-dark .button.is-success.is-focused,html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success:focus{border-color:#008438;box-shadow:0 0 0 2px rgba(0,132,56,0.5)}html.theme--documenter-dark .button.is-warning.is-hovered,html.theme--documenter-dark .button.is-warning:hover{background-color:#d39e00}html.theme--documenter-dark .button.is-warning.is-active,html.theme--documenter-dark .button.is-warning.is-focused,html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning:focus{border-color:#ad8100;box-shadow:0 0 0 2px rgba(173,129,0,0.5)}html.theme--documenter-dark .button.is-danger.is-hovered,html.theme--documenter-dark .button.is-danger:hover{background-color:#c12110}html.theme--documenter-dark .button.is-danger.is-active,html.theme--documenter-dark .button.is-danger.is-focused,html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger:focus{border-color:#9e1b0d;box-shadow:0 0 0 2px rgba(158,27,13,0.5)}html.theme--documenter-dark .label{color:#dbdee0}html.theme--documenter-dark .button,html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .select,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea{height:2.5em}html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .textarea{transition:all 200ms ease;box-shadow:none;border-width:1px;padding-left:1em;padding-right:1em}html.theme--documenter-dark .select:after,html.theme--documenter-dark .select select{border-width:1px}html.theme--documenter-dark .control.has-addons .button,html.theme--documenter-dark .control.has-addons .input,html.theme--documenter-dark .control.has-addons #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-addons form.docs-search>input,html.theme--documenter-dark .control.has-addons .select{margin-right:-1px}html.theme--documenter-dark .notification{background-color:#343c3d}html.theme--documenter-dark .card{box-shadow:none;border:1px solid #343c3d;background-color:#282f2f;border-radius:.4em}html.theme--documenter-dark .card .card-image img{border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-header{box-shadow:none;background-color:rgba(18,18,18,0.2);border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-footer{background-color:rgba(18,18,18,0.2)}html.theme--documenter-dark .card .card-footer,html.theme--documenter-dark .card .card-footer-item{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .notification.is-white a:not(.button){color:#0a0a0a;text-decoration:underline}html.theme--documenter-dark .notification.is-black a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-light a:not(.button){color:rgba(0,0,0,0.7);text-decoration:underline}html.theme--documenter-dark .notification.is-dark a:not(.button),html.theme--documenter-dark .content kbd.notification a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-primary a:not(.button),html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-link a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-info a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-success a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-warning a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-danger a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .tag,html.theme--documenter-dark .content kbd,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{border-radius:.4em}html.theme--documenter-dark .menu-list a{transition:all 300ms ease}html.theme--documenter-dark .modal-card-body{background-color:#282f2f}html.theme--documenter-dark .modal-card-foot,html.theme--documenter-dark .modal-card-head{border-color:#343c3d}html.theme--documenter-dark .message-header{font-weight:700;background-color:#343c3d;color:#fff}html.theme--documenter-dark .message-body{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .navbar{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent{background:none}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar .navbar-menu{background-color:#375a7f;border-radius:0 0 .4em .4em}}html.theme--documenter-dark .hero .navbar,html.theme--documenter-dark body>.navbar{border-radius:0}html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous{border-width:1px}html.theme--documenter-dark .panel-block,html.theme--documenter-dark .panel-heading,html.theme--documenter-dark .panel-tabs{border-width:1px}html.theme--documenter-dark .panel-block:first-child,html.theme--documenter-dark .panel-heading:first-child,html.theme--documenter-dark .panel-tabs:first-child{border-top-width:1px}html.theme--documenter-dark .panel-heading{font-weight:700}html.theme--documenter-dark .panel-tabs a{border-width:1px;margin-bottom:-1px}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#17a689}html.theme--documenter-dark .panel-block:hover{color:#1dd2af}html.theme--documenter-dark .panel-block:hover .panel-icon{color:#1dd2af}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#17a689}html.theme--documenter-dark .tabs a{border-bottom-width:1px;margin-bottom:-1px}html.theme--documenter-dark .tabs ul{border-bottom-width:1px}html.theme--documenter-dark .tabs.is-boxed a{border-width:1px}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#1f2424}html.theme--documenter-dark .tabs.is-toggle li a{border-width:1px;margin-bottom:0}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .hero.is-white .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-black .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-light .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-dark .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .content kbd.hero .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-primary .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-link .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-info .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-success .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-warning .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-danger .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark h1 .docs-heading-anchor,html.theme--documenter-dark h1 .docs-heading-anchor:hover,html.theme--documenter-dark h1 .docs-heading-anchor:visited,html.theme--documenter-dark h2 .docs-heading-anchor,html.theme--documenter-dark h2 .docs-heading-anchor:hover,html.theme--documenter-dark h2 .docs-heading-anchor:visited,html.theme--documenter-dark h3 .docs-heading-anchor,html.theme--documenter-dark h3 .docs-heading-anchor:hover,html.theme--documenter-dark h3 .docs-heading-anchor:visited,html.theme--documenter-dark h4 .docs-heading-anchor,html.theme--documenter-dark h4 .docs-heading-anchor:hover,html.theme--documenter-dark h4 .docs-heading-anchor:visited,html.theme--documenter-dark h5 .docs-heading-anchor,html.theme--documenter-dark h5 .docs-heading-anchor:hover,html.theme--documenter-dark h5 .docs-heading-anchor:visited,html.theme--documenter-dark h6 .docs-heading-anchor,html.theme--documenter-dark h6 .docs-heading-anchor:hover,html.theme--documenter-dark h6 .docs-heading-anchor:visited{color:#f2f2f2}html.theme--documenter-dark h1 .docs-heading-anchor-permalink,html.theme--documenter-dark h2 .docs-heading-anchor-permalink,html.theme--documenter-dark h3 .docs-heading-anchor-permalink,html.theme--documenter-dark h4 .docs-heading-anchor-permalink,html.theme--documenter-dark h5 .docs-heading-anchor-permalink,html.theme--documenter-dark h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}html.theme--documenter-dark h1 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h2 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h3 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h4 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h5 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}html.theme--documenter-dark h1:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h2:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h3:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h4:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h5:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h6:hover .docs-heading-anchor-permalink{visibility:visible}html.theme--documenter-dark .docs-light-only{display:none !important}html.theme--documenter-dark pre{position:relative;overflow:hidden}html.theme--documenter-dark pre code,html.theme--documenter-dark pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}html.theme--documenter-dark pre code:first-of-type,html.theme--documenter-dark pre code.hljs:first-of-type{padding-top:0.5rem !important}html.theme--documenter-dark pre code:last-of-type,html.theme--documenter-dark pre code.hljs:last-of-type{padding-bottom:0.5rem !important}html.theme--documenter-dark pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#fff;cursor:pointer;text-align:center}html.theme--documenter-dark pre .copy-button:focus,html.theme--documenter-dark pre .copy-button:hover{opacity:1;background:rgba(255,255,255,0.1);color:#1abc9c}html.theme--documenter-dark pre .copy-button.success{color:#259a12;opacity:1}html.theme--documenter-dark pre .copy-button.error{color:#cb3c33;opacity:1}html.theme--documenter-dark pre:hover .copy-button{opacity:1}html.theme--documenter-dark .admonition{background-color:#282f2f;border-style:solid;border-width:1px;border-color:#5e6d6f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .admonition strong{color:currentColor}html.theme--documenter-dark .admonition.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}html.theme--documenter-dark .admonition.is-medium{font-size:1.25rem}html.theme--documenter-dark .admonition.is-large{font-size:1.5rem}html.theme--documenter-dark .admonition.is-default{background-color:#282f2f;border-color:#5e6d6f}html.theme--documenter-dark .admonition.is-default>.admonition-header{background-color:#5e6d6f;color:#fff}html.theme--documenter-dark .admonition.is-default>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-info{background-color:#282f2f;border-color:#024c7d}html.theme--documenter-dark .admonition.is-info>.admonition-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .admonition.is-info>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-success{background-color:#282f2f;border-color:#008438}html.theme--documenter-dark .admonition.is-success>.admonition-header{background-color:#008438;color:#fff}html.theme--documenter-dark .admonition.is-success>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-warning{background-color:#282f2f;border-color:#ad8100}html.theme--documenter-dark .admonition.is-warning>.admonition-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .admonition.is-warning>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-danger{background-color:#282f2f;border-color:#9e1b0d}html.theme--documenter-dark .admonition.is-danger>.admonition-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .admonition.is-danger>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-compat{background-color:#282f2f;border-color:#137886}html.theme--documenter-dark .admonition.is-compat>.admonition-header{background-color:#137886;color:#fff}html.theme--documenter-dark .admonition.is-compat>.admonition-body{color:#fff}html.theme--documenter-dark .admonition-header{color:#fff;background-color:#5e6d6f;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}html.theme--documenter-dark .admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}html.theme--documenter-dark details.admonition.is-details>.admonition-header{list-style:none}html.theme--documenter-dark details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}html.theme--documenter-dark details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}html.theme--documenter-dark .admonition-body{color:#fff;padding:0.5rem .75rem}html.theme--documenter-dark .admonition-body pre{background-color:#282f2f}html.theme--documenter-dark .admonition-body code{background-color:rgba(255,255,255,0.05)}html.theme--documenter-dark .docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #5e6d6f;box-shadow:none;max-width:100%}html.theme--documenter-dark .docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#282f2f;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #5e6d6f;overflow:auto}html.theme--documenter-dark .docstring>header code{background-color:transparent}html.theme--documenter-dark .docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}html.theme--documenter-dark .docstring>header .docstring-binding{margin-right:0.3em}html.theme--documenter-dark .docstring>header .docstring-category{margin-left:0.3em}html.theme--documenter-dark .docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .docstring>section:last-child{border-bottom:none}html.theme--documenter-dark .docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}html.theme--documenter-dark .docstring>section>a.docs-sourcelink:focus{opacity:1 !important}html.theme--documenter-dark .docstring:hover>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring>section:hover a.docs-sourcelink{opacity:1}html.theme--documenter-dark .documenter-example-output{background-color:#1f2424}html.theme--documenter-dark .outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#282f2f;color:#fff;border-bottom:3px solid #9e1b0d;padding:10px 35px;text-align:center;font-size:15px}html.theme--documenter-dark .outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}html.theme--documenter-dark .outdated-warning-overlay a{color:#1abc9c}html.theme--documenter-dark .outdated-warning-overlay a:hover{color:#1dd2af}html.theme--documenter-dark .content pre{border:1px solid #5e6d6f}html.theme--documenter-dark .content code{font-weight:inherit}html.theme--documenter-dark .content a code{color:#1abc9c}html.theme--documenter-dark .content h1 code,html.theme--documenter-dark .content h2 code,html.theme--documenter-dark .content h3 code,html.theme--documenter-dark .content h4 code,html.theme--documenter-dark .content h5 code,html.theme--documenter-dark .content h6 code{color:#f2f2f2}html.theme--documenter-dark .content table{display:block;width:initial;max-width:100%;overflow-x:auto}html.theme--documenter-dark .content blockquote>ul:first-child,html.theme--documenter-dark .content blockquote>ol:first-child,html.theme--documenter-dark .content .admonition-body>ul:first-child,html.theme--documenter-dark .content .admonition-body>ol:first-child{margin-top:0}html.theme--documenter-dark pre,html.theme--documenter-dark code{font-variant-ligatures:no-contextual}html.theme--documenter-dark .breadcrumb a.is-disabled{cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb a.is-disabled,html.theme--documenter-dark .breadcrumb a.is-disabled:hover{color:#f2f2f2}html.theme--documenter-dark .hljs{background:initial !important}html.theme--documenter-dark .katex .katex-mathml{top:0;right:0}html.theme--documenter-dark .katex-display,html.theme--documenter-dark mjx-container,html.theme--documenter-dark .MathJax_Display{margin:0.5em 0 !important}html.theme--documenter-dark html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}html.theme--documenter-dark li.no-marker{list-style:none}html.theme--documenter-dark #documenter .docs-main>article{overflow-wrap:break-word}html.theme--documenter-dark #documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main{width:100%}html.theme--documenter-dark #documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-main>header,html.theme--documenter-dark #documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar{background-color:#1f2424;border-bottom:1px solid #5e6d6f;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-icon,html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #171717;transition-duration:0.7s;-webkit-transition-duration:0.7s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}html.theme--documenter-dark #documenter .docs-main section.footnotes{border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-main section.footnotes li .tag:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .content kbd:first-child,html.theme--documenter-dark .content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}html.theme--documenter-dark #documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #5e6d6f;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage,html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}html.theme--documenter-dark #documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}html.theme--documenter-dark #documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}html.theme--documenter-dark #documenter .docs-sidebar{display:flex;flex-direction:column;color:#fff;background-color:#282f2f;border-right:1px solid #5e6d6f;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}html.theme--documenter-dark #documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #171717}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar{left:0;top:0}}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a,html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a:hover{color:#fff}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector{border-top:1px solid #5e6d6f;display:none;padding:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector.visible{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #5e6d6f;padding-bottom:1.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#fff;background:#282f2f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu a.tocitem:hover,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#fff;background-color:#32393a}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #5e6d6f;border-bottom:1px solid #5e6d6f;background-color:#1f2424}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#1f2424;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#32393a;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{width:14.4rem}html.theme--documenter-dark #documenter .docs-sidebar #documenter-search-query{color:#868c98;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}html.theme--documenter-dark kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(245,245,245,0.6);box-shadow:0 2px 0 1px rgba(245,245,245,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}html.theme--documenter-dark .search-min-width-50{min-width:50%}html.theme--documenter-dark .search-min-height-100{min-height:100%}html.theme--documenter-dark .search-modal-card-body{max-height:calc(100vh - 15rem)}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333;background-color:#f1f5f9}html.theme--documenter-dark .search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}html.theme--documenter-dark .search-filter:hover,html.theme--documenter-dark .search-filter:focus{color:#333}html.theme--documenter-dark .search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}html.theme--documenter-dark .search-filter-selected:hover,html.theme--documenter-dark .search-filter-selected:focus{color:#f5f5f5}html.theme--documenter-dark .search-result-highlight{background-color:#ffdd57;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .search-result-title{width:85%;color:#f5f5f5}html.theme--documenter-dark .search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-thumb,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-track,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem}html.theme--documenter-dark .gap-8{gap:2rem}html.theme--documenter-dark{background-color:#1f2424;font-size:16px;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark .ansi span.sgr1{font-weight:bolder}html.theme--documenter-dark .ansi span.sgr2{font-weight:lighter}html.theme--documenter-dark .ansi span.sgr3{font-style:italic}html.theme--documenter-dark .ansi span.sgr4{text-decoration:underline}html.theme--documenter-dark .ansi span.sgr7{color:#1f2424;background-color:#fff}html.theme--documenter-dark .ansi span.sgr8{color:transparent}html.theme--documenter-dark .ansi span.sgr8 span{color:transparent}html.theme--documenter-dark .ansi span.sgr9{text-decoration:line-through}html.theme--documenter-dark .ansi span.sgr30{color:#242424}html.theme--documenter-dark .ansi span.sgr31{color:#f6705f}html.theme--documenter-dark .ansi span.sgr32{color:#4fb43a}html.theme--documenter-dark .ansi span.sgr33{color:#f4c72f}html.theme--documenter-dark .ansi span.sgr34{color:#7587f0}html.theme--documenter-dark .ansi span.sgr35{color:#bc89d3}html.theme--documenter-dark .ansi span.sgr36{color:#49b6ca}html.theme--documenter-dark .ansi span.sgr37{color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr40{background-color:#242424}html.theme--documenter-dark .ansi span.sgr41{background-color:#f6705f}html.theme--documenter-dark .ansi span.sgr42{background-color:#4fb43a}html.theme--documenter-dark .ansi span.sgr43{background-color:#f4c72f}html.theme--documenter-dark .ansi span.sgr44{background-color:#7587f0}html.theme--documenter-dark .ansi span.sgr45{background-color:#bc89d3}html.theme--documenter-dark .ansi span.sgr46{background-color:#49b6ca}html.theme--documenter-dark .ansi span.sgr47{background-color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr90{color:#92a0a2}html.theme--documenter-dark .ansi span.sgr91{color:#ff8674}html.theme--documenter-dark .ansi span.sgr92{color:#79d462}html.theme--documenter-dark .ansi span.sgr93{color:#ffe76b}html.theme--documenter-dark .ansi span.sgr94{color:#8a98ff}html.theme--documenter-dark .ansi span.sgr95{color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr96{color:#6bc8db}html.theme--documenter-dark .ansi span.sgr97{color:#ecf0f1}html.theme--documenter-dark .ansi span.sgr100{background-color:#92a0a2}html.theme--documenter-dark .ansi span.sgr101{background-color:#ff8674}html.theme--documenter-dark .ansi span.sgr102{background-color:#79d462}html.theme--documenter-dark .ansi span.sgr103{background-color:#ffe76b}html.theme--documenter-dark .ansi span.sgr104{background-color:#8a98ff}html.theme--documenter-dark .ansi span.sgr105{background-color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr106{background-color:#6bc8db}html.theme--documenter-dark .ansi span.sgr107{background-color:#ecf0f1}html.theme--documenter-dark code.language-julia-repl>span.hljs-meta{color:#4fb43a;font-weight:bolder}html.theme--documenter-dark .hljs{background:#2b2b2b;color:#f8f8f2}html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-quote{color:#d4d0ab}html.theme--documenter-dark .hljs-variable,html.theme--documenter-dark .hljs-template-variable,html.theme--documenter-dark .hljs-tag,html.theme--documenter-dark .hljs-name,html.theme--documenter-dark .hljs-selector-id,html.theme--documenter-dark .hljs-selector-class,html.theme--documenter-dark .hljs-regexp,html.theme--documenter-dark .hljs-deletion{color:#ffa07a}html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-link{color:#f5ab35}html.theme--documenter-dark .hljs-attribute{color:#ffd700}html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-addition{color:#abe338}html.theme--documenter-dark .hljs-title,html.theme--documenter-dark .hljs-section{color:#00e0e0}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{color:#dcc6e0}html.theme--documenter-dark .hljs-emphasis{font-style:italic}html.theme--documenter-dark .hljs-strong{font-weight:bold}@media screen and (-ms-high-contrast: active){html.theme--documenter-dark .hljs-addition,html.theme--documenter-dark .hljs-attribute,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-link,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-quote{color:highlight}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{font-weight:bold}}html.theme--documenter-dark .hljs-subst{color:#f8f8f2}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333 !important;background-color:#f1f5f9 !important}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:whitesmoke;background-color:#33415580;border-radius:0.6rem}html.theme--documenter-dark .search-result-title{color:whitesmoke}html.theme--documenter-dark .search-result-highlight{background-color:greenyellow;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f50}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem} diff --git a/dev/assets/themes/documenter-light.css b/dev/assets/themes/documenter-light.css new file mode 100644 index 000000000..2f168c77b --- /dev/null +++ b/dev/assets/themes/documenter-light.css @@ -0,0 +1,9 @@ +.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.file-cta,.file-name,.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input,.button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:4px;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus,.pagination-ellipsis:focus,.file-cta:focus,.file-name:focus,.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.button:focus,.is-focused.pagination-previous,.is-focused.pagination-next,.is-focused.pagination-link,.is-focused.pagination-ellipsis,.is-focused.file-cta,.is-focused.file-name,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-focused.button,.pagination-previous:active,.pagination-next:active,.pagination-link:active,.pagination-ellipsis:active,.file-cta:active,.file-name:active,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.button:active,.is-active.pagination-previous,.is-active.pagination-next,.is-active.pagination-link,.is-active.pagination-ellipsis,.is-active.file-cta,.is-active.file-name,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.is-active.button{outline:none}.pagination-previous[disabled],.pagination-next[disabled],.pagination-link[disabled],.pagination-ellipsis[disabled],.file-cta[disabled],.file-name[disabled],.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],.button[disabled],fieldset[disabled] .pagination-previous,fieldset[disabled] .pagination-next,fieldset[disabled] .pagination-link,fieldset[disabled] .pagination-ellipsis,fieldset[disabled] .file-cta,fieldset[disabled] .file-name,fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] .button{cursor:not-allowed}.tabs,.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.breadcrumb,.file,.button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.navbar-link:not(.is-arrowless)::after,.select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}.admonition:not(:last-child),.tabs:not(:last-child),.pagination:not(:last-child),.message:not(:last-child),.level:not(:last-child),.breadcrumb:not(:last-child),.block:not(:last-child),.title:not(:last-child),.subtitle:not(:last-child),.table-container:not(:last-child),.table:not(:last-child),.progress:not(:last-child),.notification:not(:last-child),.content:not(:last-child),.box:not(:last-child){margin-bottom:1.5rem}.modal-close,.delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}.modal-close::before,.delete::before,.modal-close::after,.delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.modal-close::before,.delete::before{height:2px;width:50%}.modal-close::after,.delete::after{height:50%;width:2px}.modal-close:hover,.delete:hover,.modal-close:focus,.delete:focus{background-color:rgba(10,10,10,0.3)}.modal-close:active,.delete:active{background-color:rgba(10,10,10,0.4)}.is-small.modal-close,#documenter .docs-sidebar form.docs-search>input.modal-close,.is-small.delete,#documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}.is-medium.modal-close,.is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}.is-large.modal-close,.is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}.control.is-loading::after,.select.is-loading::after,.loader,.button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdbdb;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}.hero-video,.modal-background,.modal,.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}.navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#f5f5f5 !important}a.has-text-light:hover,a.has-text-light:focus{color:#dbdbdb !important}.has-background-light{background-color:#f5f5f5 !important}.has-text-dark{color:#363636 !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#1c1c1c !important}.has-background-dark{background-color:#363636 !important}.has-text-primary{color:#4eb5de !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#27a1d2 !important}.has-background-primary{background-color:#4eb5de !important}.has-text-primary-light{color:#eef8fc !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#c3e6f4 !important}.has-background-primary-light{background-color:#eef8fc !important}.has-text-primary-dark{color:#1a6d8e !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#228eb9 !important}.has-background-primary-dark{background-color:#1a6d8e !important}.has-text-link{color:#2e63b8 !important}a.has-text-link:hover,a.has-text-link:focus{color:#244d8f !important}.has-background-link{background-color:#2e63b8 !important}.has-text-link-light{color:#eff3fb !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c6d6f1 !important}.has-background-link-light{background-color:#eff3fb !important}.has-text-link-dark{color:#3169c4 !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#5485d4 !important}.has-background-link-dark{background-color:#3169c4 !important}.has-text-info{color:#209cee !important}a.has-text-info:hover,a.has-text-info:focus{color:#1081cb !important}.has-background-info{background-color:#209cee !important}.has-text-info-light{color:#ecf7fe !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#bde2fa !important}.has-background-info-light{background-color:#ecf7fe !important}.has-text-info-dark{color:#0e72b4 !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#1190e3 !important}.has-background-info-dark{background-color:#0e72b4 !important}.has-text-success{color:#22c35b !important}a.has-text-success:hover,a.has-text-success:focus{color:#1a9847 !important}.has-background-success{background-color:#22c35b !important}.has-text-success-light{color:#eefcf3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#c2f4d4 !important}.has-background-success-light{background-color:#eefcf3 !important}.has-text-success-dark{color:#198f43 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#21bb57 !important}.has-background-success-dark{background-color:#198f43 !important}.has-text-warning{color:#ffdd57 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#ffd324 !important}.has-background-warning{background-color:#ffdd57 !important}.has-text-warning-light{color:#fffbeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#fff1b8 !important}.has-background-warning-light{background-color:#fffbeb !important}.has-text-warning-dark{color:#947600 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#c79f00 !important}.has-background-warning-dark{background-color:#947600 !important}.has-text-danger{color:#da0b00 !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#a70800 !important}.has-background-danger{background-color:#da0b00 !important}.has-text-danger-light{color:#ffeceb !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#ffbbb8 !important}.has-background-danger-light{background-color:#ffeceb !important}.has-text-danger-dark{color:#f50c00 !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#ff3429 !important}.has-background-danger-dark{background-color:#f50c00 !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#363636 !important}.has-background-grey-darker{background-color:#363636 !important}.has-text-grey-dark{color:#4a4a4a !important}.has-background-grey-dark{background-color:#4a4a4a !important}.has-text-grey{color:#6b6b6b !important}.has-background-grey{background-color:#6b6b6b !important}.has-text-grey-light{color:#b5b5b5 !important}.has-background-grey-light{background-color:#b5b5b5 !important}.has-text-grey-lighter{color:#dbdbdb !important}.has-background-grey-lighter{background-color:#dbdbdb !important}.has-text-white-ter{color:#f5f5f5 !important}.has-background-white-ter{background-color:#f5f5f5 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,.docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}html{background-color:#fff;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}article,aside,figure,footer,header,hgroup,section{display:block}body,button,input,optgroup,select,textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}code,pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}body{color:#222;font-size:1em;font-weight:400;line-height:1.5}a{color:#2e63b8;cursor:pointer;text-decoration:none}a strong{color:currentColor}a:hover{color:#363636}code{background-color:rgba(0,0,0,0.05);color:#000;font-size:.875em;font-weight:normal;padding:.1em}hr{background-color:#f5f5f5;border:none;display:block;height:2px;margin:1.5rem 0}img{height:auto;max-width:100%}input[type="checkbox"],input[type="radio"]{vertical-align:baseline}small{font-size:.875em}span{font-style:inherit;font-weight:inherit}strong{color:#222;font-weight:700}fieldset{border:none}pre{-webkit-overflow-scrolling:touch;background-color:#f5f5f5;color:#222;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}table td,table th{vertical-align:top}table td:not([align]),table th:not([align]){text-align:inherit}table th{color:#222}@keyframes spinAround{from{transform:rotate(0deg)}to{transform:rotate(359deg)}}.box{background-color:#fff;border-radius:6px;box-shadow:#bbb;color:#222;display:block;padding:1.25rem}a.box:hover,a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #2e63b8}a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #2e63b8}.button{background-color:#fff;border-color:#dbdbdb;border-width:1px;color:#222;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}.button strong{color:inherit}.button .icon,.button .icon.is-small,.button #documenter .docs-sidebar form.docs-search>input.icon,#documenter .docs-sidebar .button form.docs-search>input.icon,.button .icon.is-medium,.button .icon.is-large{height:1.5em;width:1.5em}.button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}.button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}.button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}.button:hover,.button.is-hovered{border-color:#b5b5b5;color:#363636}.button:focus,.button.is-focused{border-color:#3c5dcd;color:#363636}.button:focus:not(:active),.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button:active,.button.is-active{border-color:#4a4a4a;color:#363636}.button.is-text{background-color:transparent;border-color:transparent;color:#222;text-decoration:underline}.button.is-text:hover,.button.is-text.is-hovered,.button.is-text:focus,.button.is-text.is-focused{background-color:#f5f5f5;color:#222}.button.is-text:active,.button.is-text.is-active{background-color:#e8e8e8;color:#222}.button.is-text[disabled],fieldset[disabled] .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}.button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#2e63b8;text-decoration:none}.button.is-ghost:hover,.button.is-ghost.is-hovered{color:#2e63b8;text-decoration:underline}.button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}.button.is-white:hover,.button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.button.is-white:focus,.button.is-white.is-focused{border-color:transparent;color:#0a0a0a}.button.is-white:focus:not(:active),.button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.button.is-white:active,.button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.button.is-white[disabled],fieldset[disabled] .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}.button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted:hover,.button.is-white.is-inverted.is-hovered{background-color:#000}.button.is-white.is-inverted[disabled],fieldset[disabled] .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}.button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-white.is-outlined:hover,.button.is-white.is-outlined.is-hovered,.button.is-white.is-outlined:focus,.button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}.button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-outlined.is-loading:hover::after,.button.is-white.is-outlined.is-loading.is-hovered::after,.button.is-white.is-outlined.is-loading:focus::after,.button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined[disabled],fieldset[disabled] .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-white.is-inverted.is-outlined:hover,.button.is-white.is-inverted.is-outlined.is-hovered,.button.is-white.is-inverted.is-outlined:focus,.button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted.is-outlined.is-loading:hover::after,.button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-white.is-inverted.is-outlined.is-loading:focus::after,.button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}.button.is-black:hover,.button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}.button.is-black:focus,.button.is-black.is-focused{border-color:transparent;color:#fff}.button.is-black:focus:not(:active),.button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.button.is-black:active,.button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}.button.is-black[disabled],fieldset[disabled] .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}.button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted:hover,.button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-black.is-inverted[disabled],fieldset[disabled] .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}.button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-black.is-outlined:hover,.button.is-black.is-outlined.is-hovered,.button.is-black.is-outlined:focus,.button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-outlined.is-loading:hover::after,.button.is-black.is-outlined.is-loading.is-hovered::after,.button.is-black.is-outlined.is-loading:focus::after,.button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined[disabled],fieldset[disabled] .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-black.is-inverted.is-outlined:hover,.button.is-black.is-inverted.is-outlined.is-hovered,.button.is-black.is-inverted.is-outlined:focus,.button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted.is-outlined.is-loading:hover::after,.button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-black.is-inverted.is-outlined.is-loading:focus::after,.button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-light{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:hover,.button.is-light.is-hovered{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus,.button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus:not(:active),.button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.button.is-light:active,.button.is-light.is-active{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light[disabled],fieldset[disabled] .button.is-light{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none}.button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted:hover,.button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-light.is-inverted[disabled],fieldset[disabled] .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#f5f5f5}.button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;color:#f5f5f5}.button.is-light.is-outlined:hover,.button.is-light.is-outlined.is-hovered,.button.is-light.is-outlined:focus,.button.is-light.is-outlined.is-focused{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-outlined.is-loading:hover::after,.button.is-light.is-outlined.is-loading.is-hovered::after,.button.is-light.is-outlined.is-loading:focus::after,.button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined[disabled],fieldset[disabled] .button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;box-shadow:none;color:#f5f5f5}.button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-light.is-inverted.is-outlined:hover,.button.is-light.is-inverted.is-outlined.is-hovered,.button.is-light.is-inverted.is-outlined:focus,.button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted.is-outlined.is-loading:hover::after,.button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-light.is-inverted.is-outlined.is-loading:focus::after,.button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-dark,.content kbd.button{background-color:#363636;border-color:transparent;color:#fff}.button.is-dark:hover,.content kbd.button:hover,.button.is-dark.is-hovered,.content kbd.button.is-hovered{background-color:#2f2f2f;border-color:transparent;color:#fff}.button.is-dark:focus,.content kbd.button:focus,.button.is-dark.is-focused,.content kbd.button.is-focused{border-color:transparent;color:#fff}.button.is-dark:focus:not(:active),.content kbd.button:focus:not(:active),.button.is-dark.is-focused:not(:active),.content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.button.is-dark:active,.content kbd.button:active,.button.is-dark.is-active,.content kbd.button.is-active{background-color:#292929;border-color:transparent;color:#fff}.button.is-dark[disabled],.content kbd.button[disabled],fieldset[disabled] .button.is-dark,fieldset[disabled] .content kbd.button,.content fieldset[disabled] kbd.button{background-color:#363636;border-color:#363636;box-shadow:none}.button.is-dark.is-inverted,.content kbd.button.is-inverted{background-color:#fff;color:#363636}.button.is-dark.is-inverted:hover,.content kbd.button.is-inverted:hover,.button.is-dark.is-inverted.is-hovered,.content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-dark.is-inverted[disabled],.content kbd.button.is-inverted[disabled],fieldset[disabled] .button.is-dark.is-inverted,fieldset[disabled] .content kbd.button.is-inverted,.content fieldset[disabled] kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#363636}.button.is-dark.is-loading::after,.content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined,.content kbd.button.is-outlined{background-color:transparent;border-color:#363636;color:#363636}.button.is-dark.is-outlined:hover,.content kbd.button.is-outlined:hover,.button.is-dark.is-outlined.is-hovered,.content kbd.button.is-outlined.is-hovered,.button.is-dark.is-outlined:focus,.content kbd.button.is-outlined:focus,.button.is-dark.is-outlined.is-focused,.content kbd.button.is-outlined.is-focused{background-color:#363636;border-color:#363636;color:#fff}.button.is-dark.is-outlined.is-loading::after,.content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-outlined.is-loading:hover::after,.content kbd.button.is-outlined.is-loading:hover::after,.button.is-dark.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-outlined.is-loading:focus::after,.content kbd.button.is-outlined.is-loading:focus::after,.button.is-dark.is-outlined.is-loading.is-focused::after,.content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined[disabled],.content kbd.button.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-outlined,fieldset[disabled] .content kbd.button.is-outlined,.content fieldset[disabled] kbd.button.is-outlined{background-color:transparent;border-color:#363636;box-shadow:none;color:#363636}.button.is-dark.is-inverted.is-outlined,.content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-dark.is-inverted.is-outlined:hover,.content kbd.button.is-inverted.is-outlined:hover,.button.is-dark.is-inverted.is-outlined.is-hovered,.content kbd.button.is-inverted.is-outlined.is-hovered,.button.is-dark.is-inverted.is-outlined:focus,.content kbd.button.is-inverted.is-outlined:focus,.button.is-dark.is-inverted.is-outlined.is-focused,.content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#363636}.button.is-dark.is-inverted.is-outlined.is-loading:hover::after,.content kbd.button.is-inverted.is-outlined.is-loading:hover::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-inverted.is-outlined.is-loading:focus::after,.content kbd.button.is-inverted.is-outlined.is-loading:focus::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-inverted.is-outlined[disabled],.content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-inverted.is-outlined,fieldset[disabled] .content kbd.button.is-inverted.is-outlined,.content fieldset[disabled] kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary,.docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:transparent;color:#fff}.button.is-primary:hover,.docstring>section>a.button.docs-sourcelink:hover,.button.is-primary.is-hovered,.docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#43b1dc;border-color:transparent;color:#fff}.button.is-primary:focus,.docstring>section>a.button.docs-sourcelink:focus,.button.is-primary.is-focused,.docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}.button.is-primary:focus:not(:active),.docstring>section>a.button.docs-sourcelink:focus:not(:active),.button.is-primary.is-focused:not(:active),.docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.button.is-primary:active,.docstring>section>a.button.docs-sourcelink:active,.button.is-primary.is-active,.docstring>section>a.button.is-active.docs-sourcelink{background-color:#39acda;border-color:transparent;color:#fff}.button.is-primary[disabled],.docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary,fieldset[disabled] .docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;box-shadow:none}.button.is-primary.is-inverted,.docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted:hover,.docstring>section>a.button.is-inverted.docs-sourcelink:hover,.button.is-primary.is-inverted.is-hovered,.docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}.button.is-primary.is-inverted[disabled],.docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted,fieldset[disabled] .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#4eb5de}.button.is-primary.is-loading::after,.docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined,.docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;color:#4eb5de}.button.is-primary.is-outlined:hover,.docstring>section>a.button.is-outlined.docs-sourcelink:hover,.button.is-primary.is-outlined.is-hovered,.docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-outlined:focus,.docstring>section>a.button.is-outlined.docs-sourcelink:focus,.button.is-primary.is-outlined.is-focused,.docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.button.is-primary.is-outlined.is-loading::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined[disabled],.docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-outlined,fieldset[disabled] .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;box-shadow:none;color:#4eb5de}.button.is-primary.is-inverted.is-outlined,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}.button.is-primary.is-inverted.is-outlined:hover,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,.button.is-primary.is-inverted.is-outlined.is-hovered,.docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-inverted.is-outlined:focus,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,.button.is-primary.is-inverted.is-outlined.is-focused,.docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-inverted.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-inverted.is-outlined[disabled],.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted.is-outlined,fieldset[disabled] .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary.is-light,.docstring>section>a.button.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.button.is-primary.is-light:hover,.docstring>section>a.button.is-light.docs-sourcelink:hover,.button.is-primary.is-light.is-hovered,.docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e3f3fa;border-color:transparent;color:#1a6d8e}.button.is-primary.is-light:active,.docstring>section>a.button.is-light.docs-sourcelink:active,.button.is-primary.is-light.is-active,.docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#d8eff8;border-color:transparent;color:#1a6d8e}.button.is-link{background-color:#2e63b8;border-color:transparent;color:#fff}.button.is-link:hover,.button.is-link.is-hovered{background-color:#2b5eae;border-color:transparent;color:#fff}.button.is-link:focus,.button.is-link.is-focused{border-color:transparent;color:#fff}.button.is-link:focus:not(:active),.button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button.is-link:active,.button.is-link.is-active{background-color:#2958a4;border-color:transparent;color:#fff}.button.is-link[disabled],fieldset[disabled] .button.is-link{background-color:#2e63b8;border-color:#2e63b8;box-shadow:none}.button.is-link.is-inverted{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted:hover,.button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-link.is-inverted[disabled],fieldset[disabled] .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#2e63b8}.button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;color:#2e63b8}.button.is-link.is-outlined:hover,.button.is-link.is-outlined.is-hovered,.button.is-link.is-outlined:focus,.button.is-link.is-outlined.is-focused{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-outlined.is-loading:hover::after,.button.is-link.is-outlined.is-loading.is-hovered::after,.button.is-link.is-outlined.is-loading:focus::after,.button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined[disabled],fieldset[disabled] .button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;box-shadow:none;color:#2e63b8}.button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-link.is-inverted.is-outlined:hover,.button.is-link.is-inverted.is-outlined.is-hovered,.button.is-link.is-inverted.is-outlined:focus,.button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted.is-outlined.is-loading:hover::after,.button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-link.is-inverted.is-outlined.is-loading:focus::after,.button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-link.is-light{background-color:#eff3fb;color:#3169c4}.button.is-link.is-light:hover,.button.is-link.is-light.is-hovered{background-color:#e4ecf8;border-color:transparent;color:#3169c4}.button.is-link.is-light:active,.button.is-link.is-light.is-active{background-color:#dae5f6;border-color:transparent;color:#3169c4}.button.is-info{background-color:#209cee;border-color:transparent;color:#fff}.button.is-info:hover,.button.is-info.is-hovered{background-color:#1497ed;border-color:transparent;color:#fff}.button.is-info:focus,.button.is-info.is-focused{border-color:transparent;color:#fff}.button.is-info:focus:not(:active),.button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.button.is-info:active,.button.is-info.is-active{background-color:#1190e3;border-color:transparent;color:#fff}.button.is-info[disabled],fieldset[disabled] .button.is-info{background-color:#209cee;border-color:#209cee;box-shadow:none}.button.is-info.is-inverted{background-color:#fff;color:#209cee}.button.is-info.is-inverted:hover,.button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-info.is-inverted[disabled],fieldset[disabled] .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#209cee}.button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined{background-color:transparent;border-color:#209cee;color:#209cee}.button.is-info.is-outlined:hover,.button.is-info.is-outlined.is-hovered,.button.is-info.is-outlined:focus,.button.is-info.is-outlined.is-focused{background-color:#209cee;border-color:#209cee;color:#fff}.button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-outlined.is-loading:hover::after,.button.is-info.is-outlined.is-loading.is-hovered::after,.button.is-info.is-outlined.is-loading:focus::after,.button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined[disabled],fieldset[disabled] .button.is-info.is-outlined{background-color:transparent;border-color:#209cee;box-shadow:none;color:#209cee}.button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-info.is-inverted.is-outlined:hover,.button.is-info.is-inverted.is-outlined.is-hovered,.button.is-info.is-inverted.is-outlined:focus,.button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#209cee}.button.is-info.is-inverted.is-outlined.is-loading:hover::after,.button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-info.is-inverted.is-outlined.is-loading:focus::after,.button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.button.is-info.is-light:hover,.button.is-info.is-light.is-hovered{background-color:#e0f1fd;border-color:transparent;color:#0e72b4}.button.is-info.is-light:active,.button.is-info.is-light.is-active{background-color:#d4ecfc;border-color:transparent;color:#0e72b4}.button.is-success{background-color:#22c35b;border-color:transparent;color:#fff}.button.is-success:hover,.button.is-success.is-hovered{background-color:#20b856;border-color:transparent;color:#fff}.button.is-success:focus,.button.is-success.is-focused{border-color:transparent;color:#fff}.button.is-success:focus:not(:active),.button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.button.is-success:active,.button.is-success.is-active{background-color:#1ead51;border-color:transparent;color:#fff}.button.is-success[disabled],fieldset[disabled] .button.is-success{background-color:#22c35b;border-color:#22c35b;box-shadow:none}.button.is-success.is-inverted{background-color:#fff;color:#22c35b}.button.is-success.is-inverted:hover,.button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-success.is-inverted[disabled],fieldset[disabled] .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#22c35b}.button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;color:#22c35b}.button.is-success.is-outlined:hover,.button.is-success.is-outlined.is-hovered,.button.is-success.is-outlined:focus,.button.is-success.is-outlined.is-focused{background-color:#22c35b;border-color:#22c35b;color:#fff}.button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-outlined.is-loading:hover::after,.button.is-success.is-outlined.is-loading.is-hovered::after,.button.is-success.is-outlined.is-loading:focus::after,.button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined[disabled],fieldset[disabled] .button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;box-shadow:none;color:#22c35b}.button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-success.is-inverted.is-outlined:hover,.button.is-success.is-inverted.is-outlined.is-hovered,.button.is-success.is-inverted.is-outlined:focus,.button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#22c35b}.button.is-success.is-inverted.is-outlined.is-loading:hover::after,.button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-success.is-inverted.is-outlined.is-loading:focus::after,.button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-success.is-light{background-color:#eefcf3;color:#198f43}.button.is-success.is-light:hover,.button.is-success.is-light.is-hovered{background-color:#e3faeb;border-color:transparent;color:#198f43}.button.is-success.is-light:active,.button.is-success.is-light.is-active{background-color:#d8f8e3;border-color:transparent;color:#198f43}.button.is-warning{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:hover,.button.is-warning.is-hovered{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus,.button.is-warning.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus:not(:active),.button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.button.is-warning:active,.button.is-warning.is-active{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning[disabled],fieldset[disabled] .button.is-warning{background-color:#ffdd57;border-color:#ffdd57;box-shadow:none}.button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted:hover,.button.is-warning.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted[disabled],fieldset[disabled] .button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ffdd57}.button.is-warning.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;color:#ffdd57}.button.is-warning.is-outlined:hover,.button.is-warning.is-outlined.is-hovered,.button.is-warning.is-outlined:focus,.button.is-warning.is-outlined.is-focused{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-outlined.is-loading:hover::after,.button.is-warning.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-outlined.is-loading:focus::after,.button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;box-shadow:none;color:#ffdd57}.button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted.is-outlined:hover,.button.is-warning.is-inverted.is-outlined.is-hovered,.button.is-warning.is-inverted.is-outlined:focus,.button.is-warning.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted.is-outlined.is-loading:hover::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-inverted.is-outlined.is-loading:focus::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-warning.is-light{background-color:#fffbeb;color:#947600}.button.is-warning.is-light:hover,.button.is-warning.is-light.is-hovered{background-color:#fff8de;border-color:transparent;color:#947600}.button.is-warning.is-light:active,.button.is-warning.is-light.is-active{background-color:#fff6d1;border-color:transparent;color:#947600}.button.is-danger{background-color:#da0b00;border-color:transparent;color:#fff}.button.is-danger:hover,.button.is-danger.is-hovered{background-color:#cd0a00;border-color:transparent;color:#fff}.button.is-danger:focus,.button.is-danger.is-focused{border-color:transparent;color:#fff}.button.is-danger:focus:not(:active),.button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.button.is-danger:active,.button.is-danger.is-active{background-color:#c10a00;border-color:transparent;color:#fff}.button.is-danger[disabled],fieldset[disabled] .button.is-danger{background-color:#da0b00;border-color:#da0b00;box-shadow:none}.button.is-danger.is-inverted{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted:hover,.button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-danger.is-inverted[disabled],fieldset[disabled] .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#da0b00}.button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;color:#da0b00}.button.is-danger.is-outlined:hover,.button.is-danger.is-outlined.is-hovered,.button.is-danger.is-outlined:focus,.button.is-danger.is-outlined.is-focused{background-color:#da0b00;border-color:#da0b00;color:#fff}.button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-outlined.is-loading:hover::after,.button.is-danger.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-outlined.is-loading:focus::after,.button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;box-shadow:none;color:#da0b00}.button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-danger.is-inverted.is-outlined:hover,.button.is-danger.is-inverted.is-outlined.is-hovered,.button.is-danger.is-inverted.is-outlined:focus,.button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted.is-outlined.is-loading:hover::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-inverted.is-outlined.is-loading:focus::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.button.is-danger.is-light:hover,.button.is-danger.is-light.is-hovered{background-color:#ffe0de;border-color:transparent;color:#f50c00}.button.is-danger.is-light:active,.button.is-danger.is-light.is-active{background-color:#ffd3d1;border-color:transparent;color:#f50c00}.button.is-small,#documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}.button.is-small:not(.is-rounded),#documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:2px}.button.is-normal{font-size:1rem}.button.is-medium{font-size:1.25rem}.button.is-large{font-size:1.5rem}.button[disabled],fieldset[disabled] .button{background-color:#fff;border-color:#dbdbdb;box-shadow:none;opacity:.5}.button.is-fullwidth{display:flex;width:100%}.button.is-loading{color:transparent !important;pointer-events:none}.button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}.button.is-static{background-color:#f5f5f5;border-color:#dbdbdb;color:#6b6b6b;box-shadow:none;pointer-events:none}.button.is-rounded,#documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}.buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.buttons .button{margin-bottom:0.5rem}.buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}.buttons:last-child{margin-bottom:-0.5rem}.buttons:not(:last-child){margin-bottom:1rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:2px}.buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}.buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}.buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}.buttons.has-addons .button:last-child{margin-right:0}.buttons.has-addons .button:hover,.buttons.has-addons .button.is-hovered{z-index:2}.buttons.has-addons .button:focus,.buttons.has-addons .button.is-focused,.buttons.has-addons .button:active,.buttons.has-addons .button.is-active,.buttons.has-addons .button.is-selected{z-index:3}.buttons.has-addons .button:focus:hover,.buttons.has-addons .button.is-focused:hover,.buttons.has-addons .button:active:hover,.buttons.has-addons .button.is-active:hover,.buttons.has-addons .button.is-selected:hover{z-index:4}.buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}.buttons.is-centered{justify-content:center}.buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}.buttons.is-right{justify-content:flex-end}.buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.65625rem}.button.is-responsive.is-medium{font-size:.75rem}.button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.75rem}.button.is-responsive.is-medium{font-size:1rem}.button.is-responsive.is-large{font-size:1.25rem}}.container{flex-grow:1;margin:0 auto;position:relative;width:auto}.container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){.container{max-width:992px}}@media screen and (max-width: 1215px){.container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){.container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){.container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){.container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}.content li+li{margin-top:0.25em}.content p:not(:last-child),.content dl:not(:last-child),.content ol:not(:last-child),.content ul:not(:last-child),.content blockquote:not(:last-child),.content pre:not(:last-child),.content table:not(:last-child){margin-bottom:1em}.content h1,.content h2,.content h3,.content h4,.content h5,.content h6{color:#222;font-weight:600;line-height:1.125}.content h1{font-size:2em;margin-bottom:0.5em}.content h1:not(:first-child){margin-top:1em}.content h2{font-size:1.75em;margin-bottom:0.5714em}.content h2:not(:first-child){margin-top:1.1428em}.content h3{font-size:1.5em;margin-bottom:0.6666em}.content h3:not(:first-child){margin-top:1.3333em}.content h4{font-size:1.25em;margin-bottom:0.8em}.content h5{font-size:1.125em;margin-bottom:0.8888em}.content h6{font-size:1em;margin-bottom:1em}.content blockquote{background-color:#f5f5f5;border-left:5px solid #dbdbdb;padding:1.25em 1.5em}.content ol{list-style-position:outside;margin-left:2em;margin-top:1em}.content ol:not([type]){list-style-type:decimal}.content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}.content ol.is-lower-roman:not([type]){list-style-type:lower-roman}.content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}.content ol.is-upper-roman:not([type]){list-style-type:upper-roman}.content ul{list-style:disc outside;margin-left:2em;margin-top:1em}.content ul ul{list-style-type:circle;margin-top:0.5em}.content ul ul ul{list-style-type:square}.content dd{margin-left:2em}.content figure{margin-left:2em;margin-right:2em;text-align:center}.content figure:not(:first-child){margin-top:2em}.content figure:not(:last-child){margin-bottom:2em}.content figure img{display:inline-block}.content figure figcaption{font-style:italic}.content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}.content sup,.content sub{font-size:75%}.content table{width:100%}.content table td,.content table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.content table th{color:#222}.content table th:not([align]){text-align:inherit}.content table thead td,.content table thead th{border-width:0 0 2px;color:#222}.content table tfoot td,.content table tfoot th{border-width:2px 0 0;color:#222}.content table tbody tr:last-child td,.content table tbody tr:last-child th{border-bottom-width:0}.content .tabs li+li{margin-top:0}.content.is-small,#documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}.content.is-normal{font-size:1rem}.content.is-medium{font-size:1.25rem}.content.is-large{font-size:1.5rem}.icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}.icon.is-small,#documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}.icon.is-medium{height:2rem;width:2rem}.icon.is-large{height:3rem;width:3rem}.icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}.icon-text .icon{flex-grow:0;flex-shrink:0}.icon-text .icon:not(:last-child){margin-right:.25em}.icon-text .icon:not(:first-child){margin-left:.25em}div.icon-text{display:flex}.image,#documenter .docs-sidebar .docs-logo>img{display:block;position:relative}.image img,#documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}.image img.is-rounded,#documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}.image.is-fullwidth,#documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}.image.is-square,#documenter .docs-sidebar .docs-logo>img.is-square,.image.is-1by1,#documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}.image.is-5by4,#documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}.image.is-4by3,#documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}.image.is-3by2,#documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}.image.is-5by3,#documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}.image.is-16by9,#documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}.image.is-2by1,#documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}.image.is-3by1,#documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}.image.is-4by5,#documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}.image.is-3by4,#documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}.image.is-2by3,#documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}.image.is-3by5,#documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}.image.is-9by16,#documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}.image.is-1by2,#documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}.image.is-1by3,#documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}.image.is-16x16,#documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}.image.is-24x24,#documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}.image.is-32x32,#documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}.image.is-48x48,#documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}.image.is-64x64,#documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}.image.is-96x96,#documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}.image.is-128x128,#documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}.notification{background-color:#f5f5f5;border-radius:4px;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}.notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}.notification strong{color:currentColor}.notification code,.notification pre{background:#fff}.notification pre code{background:transparent}.notification>.delete{right:.5rem;position:absolute;top:0.5rem}.notification .title,.notification .subtitle,.notification .content{color:currentColor}.notification.is-white{background-color:#fff;color:#0a0a0a}.notification.is-black{background-color:#0a0a0a;color:#fff}.notification.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.notification.is-dark,.content kbd.notification{background-color:#363636;color:#fff}.notification.is-primary,.docstring>section>a.notification.docs-sourcelink{background-color:#4eb5de;color:#fff}.notification.is-primary.is-light,.docstring>section>a.notification.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.notification.is-link{background-color:#2e63b8;color:#fff}.notification.is-link.is-light{background-color:#eff3fb;color:#3169c4}.notification.is-info{background-color:#209cee;color:#fff}.notification.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.notification.is-success{background-color:#22c35b;color:#fff}.notification.is-success.is-light{background-color:#eefcf3;color:#198f43}.notification.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.notification.is-warning.is-light{background-color:#fffbeb;color:#947600}.notification.is-danger{background-color:#da0b00;color:#fff}.notification.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}.progress::-webkit-progress-bar{background-color:#ededed}.progress::-webkit-progress-value{background-color:#222}.progress::-moz-progress-bar{background-color:#222}.progress::-ms-fill{background-color:#222;border:none}.progress.is-white::-webkit-progress-value{background-color:#fff}.progress.is-white::-moz-progress-bar{background-color:#fff}.progress.is-white::-ms-fill{background-color:#fff}.progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #ededed 30%)}.progress.is-black::-webkit-progress-value{background-color:#0a0a0a}.progress.is-black::-moz-progress-bar{background-color:#0a0a0a}.progress.is-black::-ms-fill{background-color:#0a0a0a}.progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #ededed 30%)}.progress.is-light::-webkit-progress-value{background-color:#f5f5f5}.progress.is-light::-moz-progress-bar{background-color:#f5f5f5}.progress.is-light::-ms-fill{background-color:#f5f5f5}.progress.is-light:indeterminate{background-image:linear-gradient(to right, #f5f5f5 30%, #ededed 30%)}.progress.is-dark::-webkit-progress-value,.content kbd.progress::-webkit-progress-value{background-color:#363636}.progress.is-dark::-moz-progress-bar,.content kbd.progress::-moz-progress-bar{background-color:#363636}.progress.is-dark::-ms-fill,.content kbd.progress::-ms-fill{background-color:#363636}.progress.is-dark:indeterminate,.content kbd.progress:indeterminate{background-image:linear-gradient(to right, #363636 30%, #ededed 30%)}.progress.is-primary::-webkit-progress-value,.docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#4eb5de}.progress.is-primary::-moz-progress-bar,.docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#4eb5de}.progress.is-primary::-ms-fill,.docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#4eb5de}.progress.is-primary:indeterminate,.docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #4eb5de 30%, #ededed 30%)}.progress.is-link::-webkit-progress-value{background-color:#2e63b8}.progress.is-link::-moz-progress-bar{background-color:#2e63b8}.progress.is-link::-ms-fill{background-color:#2e63b8}.progress.is-link:indeterminate{background-image:linear-gradient(to right, #2e63b8 30%, #ededed 30%)}.progress.is-info::-webkit-progress-value{background-color:#209cee}.progress.is-info::-moz-progress-bar{background-color:#209cee}.progress.is-info::-ms-fill{background-color:#209cee}.progress.is-info:indeterminate{background-image:linear-gradient(to right, #209cee 30%, #ededed 30%)}.progress.is-success::-webkit-progress-value{background-color:#22c35b}.progress.is-success::-moz-progress-bar{background-color:#22c35b}.progress.is-success::-ms-fill{background-color:#22c35b}.progress.is-success:indeterminate{background-image:linear-gradient(to right, #22c35b 30%, #ededed 30%)}.progress.is-warning::-webkit-progress-value{background-color:#ffdd57}.progress.is-warning::-moz-progress-bar{background-color:#ffdd57}.progress.is-warning::-ms-fill{background-color:#ffdd57}.progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ffdd57 30%, #ededed 30%)}.progress.is-danger::-webkit-progress-value{background-color:#da0b00}.progress.is-danger::-moz-progress-bar{background-color:#da0b00}.progress.is-danger::-ms-fill{background-color:#da0b00}.progress.is-danger:indeterminate{background-image:linear-gradient(to right, #da0b00 30%, #ededed 30%)}.progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#ededed;background-image:linear-gradient(to right, #222 30%, #ededed 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}.progress:indeterminate::-webkit-progress-bar{background-color:transparent}.progress:indeterminate::-moz-progress-bar{background-color:transparent}.progress:indeterminate::-ms-fill{animation-name:none}.progress.is-small,#documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}.progress.is-medium{height:1.25rem}.progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}.table{background-color:#fff;color:#222}.table td,.table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.table td.is-white,.table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}.table td.is-black,.table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.table td.is-light,.table th.is-light{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.table td.is-dark,.table th.is-dark{background-color:#363636;border-color:#363636;color:#fff}.table td.is-primary,.table th.is-primary{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.table td.is-link,.table th.is-link{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.table td.is-info,.table th.is-info{background-color:#209cee;border-color:#209cee;color:#fff}.table td.is-success,.table th.is-success{background-color:#22c35b;border-color:#22c35b;color:#fff}.table td.is-warning,.table th.is-warning{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.table td.is-danger,.table th.is-danger{background-color:#da0b00;border-color:#da0b00;color:#fff}.table td.is-narrow,.table th.is-narrow{white-space:nowrap;width:1%}.table td.is-selected,.table th.is-selected{background-color:#4eb5de;color:#fff}.table td.is-selected a,.table td.is-selected strong,.table th.is-selected a,.table th.is-selected strong{color:currentColor}.table td.is-vcentered,.table th.is-vcentered{vertical-align:middle}.table th{color:#222}.table th:not([align]){text-align:left}.table tr.is-selected{background-color:#4eb5de;color:#fff}.table tr.is-selected a,.table tr.is-selected strong{color:currentColor}.table tr.is-selected td,.table tr.is-selected th{border-color:#fff;color:currentColor}.table thead{background-color:rgba(0,0,0,0)}.table thead td,.table thead th{border-width:0 0 2px;color:#222}.table tfoot{background-color:rgba(0,0,0,0)}.table tfoot td,.table tfoot th{border-width:2px 0 0;color:#222}.table tbody{background-color:rgba(0,0,0,0)}.table tbody tr:last-child td,.table tbody tr:last-child th{border-bottom-width:0}.table.is-bordered td,.table.is-bordered th{border-width:1px}.table.is-bordered tr:last-child td,.table.is-bordered tr:last-child th{border-bottom-width:1px}.table.is-fullwidth{width:100%}.table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#f5f5f5}.table.is-narrow td,.table.is-narrow th{padding:0.25em 0.5em}.table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#fafafa}.table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}.tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.tags .tag,.tags .content kbd,.content .tags kbd,.tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}.tags .tag:not(:last-child),.tags .content kbd:not(:last-child),.content .tags kbd:not(:last-child),.tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}.tags:last-child{margin-bottom:-0.5rem}.tags:not(:last-child){margin-bottom:1rem}.tags.are-medium .tag:not(.is-normal):not(.is-large),.tags.are-medium .content kbd:not(.is-normal):not(.is-large),.content .tags.are-medium kbd:not(.is-normal):not(.is-large),.tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}.tags.are-large .tag:not(.is-normal):not(.is-medium),.tags.are-large .content kbd:not(.is-normal):not(.is-medium),.content .tags.are-large kbd:not(.is-normal):not(.is-medium),.tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}.tags.is-centered{justify-content:center}.tags.is-centered .tag,.tags.is-centered .content kbd,.content .tags.is-centered kbd,.tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}.tags.is-right{justify-content:flex-end}.tags.is-right .tag:not(:first-child),.tags.is-right .content kbd:not(:first-child),.content .tags.is-right kbd:not(:first-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}.tags.is-right .tag:not(:last-child),.tags.is-right .content kbd:not(:last-child),.content .tags.is-right kbd:not(:last-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}.tags.has-addons .tag,.tags.has-addons .content kbd,.content .tags.has-addons kbd,.tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}.tags.has-addons .tag:not(:first-child),.tags.has-addons .content kbd:not(:first-child),.content .tags.has-addons kbd:not(:first-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}.tags.has-addons .tag:not(:last-child),.tags.has-addons .content kbd:not(:last-child),.content .tags.has-addons kbd:not(:last-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.tag:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#f5f5f5;border-radius:4px;color:#222;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}.tag:not(body) .delete,.content kbd:not(body) .delete,.docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}.tag.is-white:not(body),.content kbd.is-white:not(body),.docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}.tag.is-black:not(body),.content kbd.is-black:not(body),.docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}.tag.is-light:not(body),.content kbd.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.tag.is-dark:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink.is-dark:not(body),.content .docstring>section>kbd:not(body){background-color:#363636;color:#fff}.tag.is-primary:not(body),.content kbd.is-primary:not(body),.docstring>section>a.docs-sourcelink:not(body){background-color:#4eb5de;color:#fff}.tag.is-primary.is-light:not(body),.content kbd.is-primary.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#eef8fc;color:#1a6d8e}.tag.is-link:not(body),.content kbd.is-link:not(body),.docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#2e63b8;color:#fff}.tag.is-link.is-light:not(body),.content kbd.is-link.is-light:not(body),.docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#eff3fb;color:#3169c4}.tag.is-info:not(body),.content kbd.is-info:not(body),.docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#209cee;color:#fff}.tag.is-info.is-light:not(body),.content kbd.is-info.is-light:not(body),.docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ecf7fe;color:#0e72b4}.tag.is-success:not(body),.content kbd.is-success:not(body),.docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#22c35b;color:#fff}.tag.is-success.is-light:not(body),.content kbd.is-success.is-light:not(body),.docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#eefcf3;color:#198f43}.tag.is-warning:not(body),.content kbd.is-warning:not(body),.docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ffdd57;color:rgba(0,0,0,0.7)}.tag.is-warning.is-light:not(body),.content kbd.is-warning.is-light:not(body),.docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffbeb;color:#947600}.tag.is-danger:not(body),.content kbd.is-danger:not(body),.docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#da0b00;color:#fff}.tag.is-danger.is-light:not(body),.content kbd.is-danger.is-light:not(body),.docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#ffeceb;color:#f50c00}.tag.is-normal:not(body),.content kbd.is-normal:not(body),.docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}.tag.is-medium:not(body),.content kbd.is-medium:not(body),.docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}.tag.is-large:not(body),.content kbd.is-large:not(body),.docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}.tag:not(body) .icon:first-child:not(:last-child),.content kbd:not(body) .icon:first-child:not(:last-child),.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}.tag:not(body) .icon:last-child:not(:first-child),.content kbd:not(body) .icon:last-child:not(:first-child),.docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}.tag:not(body) .icon:first-child:last-child,.content kbd:not(body) .icon:first-child:last-child,.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}.tag.is-delete:not(body),.content kbd.is-delete:not(body),.docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before,.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}.tag.is-delete:not(body):hover,.content kbd.is-delete:not(body):hover,.docstring>section>a.docs-sourcelink.is-delete:not(body):hover,.tag.is-delete:not(body):focus,.content kbd.is-delete:not(body):focus,.docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#e8e8e8}.tag.is-delete:not(body):active,.content kbd.is-delete:not(body):active,.docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#dbdbdb}.tag.is-rounded:not(body),#documenter .docs-sidebar form.docs-search>input:not(body),.content kbd.is-rounded:not(body),#documenter .docs-sidebar .content form.docs-search>input:not(body),.docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}a.tag:hover,.docstring>section>a.docs-sourcelink:hover{text-decoration:underline}.title,.subtitle{word-break:break-word}.title em,.title span,.subtitle em,.subtitle span{font-weight:inherit}.title sub,.subtitle sub{font-size:.75em}.title sup,.subtitle sup{font-size:.75em}.title .tag,.title .content kbd,.content .title kbd,.title .docstring>section>a.docs-sourcelink,.subtitle .tag,.subtitle .content kbd,.content .subtitle kbd,.subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}.title{color:#222;font-size:2rem;font-weight:600;line-height:1.125}.title strong{color:inherit;font-weight:inherit}.title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}.title.is-1{font-size:3rem}.title.is-2{font-size:2.5rem}.title.is-3{font-size:2rem}.title.is-4{font-size:1.5rem}.title.is-5{font-size:1.25rem}.title.is-6{font-size:1rem}.title.is-7{font-size:.75rem}.subtitle{color:#222;font-size:1.25rem;font-weight:400;line-height:1.25}.subtitle strong{color:#222;font-weight:600}.subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}.subtitle.is-1{font-size:3rem}.subtitle.is-2{font-size:2.5rem}.subtitle.is-3{font-size:2rem}.subtitle.is-4{font-size:1.5rem}.subtitle.is-5{font-size:1.25rem}.subtitle.is-6{font-size:1rem}.subtitle.is-7{font-size:.75rem}.heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}.number{align-items:center;background-color:#f5f5f5;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input{background-color:#fff;border-color:#dbdbdb;border-radius:4px;color:#222}.select select::-moz-placeholder,.textarea::-moz-placeholder,.input::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#707070}.select select::-webkit-input-placeholder,.textarea::-webkit-input-placeholder,.input::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#707070}.select select:-moz-placeholder,.textarea:-moz-placeholder,.input:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#707070}.select select:-ms-input-placeholder,.textarea:-ms-input-placeholder,.input:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#707070}.select select:hover,.textarea:hover,.input:hover,#documenter .docs-sidebar form.docs-search>input:hover,.select select.is-hovered,.is-hovered.textarea,.is-hovered.input,#documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#b5b5b5}.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{border-color:#2e63b8;box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none;color:#6b6b6b}.select select[disabled]::-moz-placeholder,.textarea[disabled]::-moz-placeholder,.input[disabled]::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] .select select::-moz-placeholder,.select fieldset[disabled] select::-moz-placeholder,fieldset[disabled] .textarea::-moz-placeholder,fieldset[disabled] .input::-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]::-webkit-input-placeholder,.textarea[disabled]::-webkit-input-placeholder,.input[disabled]::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] .select select::-webkit-input-placeholder,.select fieldset[disabled] select::-webkit-input-placeholder,fieldset[disabled] .textarea::-webkit-input-placeholder,fieldset[disabled] .input::-webkit-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-webkit-input-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-moz-placeholder,.textarea[disabled]:-moz-placeholder,.input[disabled]:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] .select select:-moz-placeholder,.select fieldset[disabled] select:-moz-placeholder,fieldset[disabled] .textarea:-moz-placeholder,fieldset[disabled] .input:-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-ms-input-placeholder,.textarea[disabled]:-ms-input-placeholder,.input[disabled]:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] .select select:-ms-input-placeholder,.select fieldset[disabled] select:-ms-input-placeholder,fieldset[disabled] .textarea:-ms-input-placeholder,fieldset[disabled] .input:-ms-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-ms-input-placeholder{color:rgba(107,107,107,0.3)}.textarea,.input,#documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}.textarea[readonly],.input[readonly],#documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}.is-white.textarea,.is-white.input,#documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}.is-white.textarea:focus,.is-white.input:focus,#documenter .docs-sidebar form.docs-search>input.is-white:focus,.is-white.is-focused.textarea,.is-white.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-white.textarea:active,.is-white.input:active,#documenter .docs-sidebar form.docs-search>input.is-white:active,.is-white.is-active.textarea,.is-white.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.is-black.textarea,.is-black.input,#documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}.is-black.textarea:focus,.is-black.input:focus,#documenter .docs-sidebar form.docs-search>input.is-black:focus,.is-black.is-focused.textarea,.is-black.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-black.textarea:active,.is-black.input:active,#documenter .docs-sidebar form.docs-search>input.is-black:active,.is-black.is-active.textarea,.is-black.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.is-light.textarea,.is-light.input,#documenter .docs-sidebar form.docs-search>input.is-light{border-color:#f5f5f5}.is-light.textarea:focus,.is-light.input:focus,#documenter .docs-sidebar form.docs-search>input.is-light:focus,.is-light.is-focused.textarea,.is-light.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-light.textarea:active,.is-light.input:active,#documenter .docs-sidebar form.docs-search>input.is-light:active,.is-light.is-active.textarea,.is-light.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.is-dark.textarea,.content kbd.textarea,.is-dark.input,#documenter .docs-sidebar form.docs-search>input.is-dark,.content kbd.input{border-color:#363636}.is-dark.textarea:focus,.content kbd.textarea:focus,.is-dark.input:focus,#documenter .docs-sidebar form.docs-search>input.is-dark:focus,.content kbd.input:focus,.is-dark.is-focused.textarea,.content kbd.is-focused.textarea,.is-dark.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.content kbd.is-focused.input,#documenter .docs-sidebar .content form.docs-search>input.is-focused,.is-dark.textarea:active,.content kbd.textarea:active,.is-dark.input:active,#documenter .docs-sidebar form.docs-search>input.is-dark:active,.content kbd.input:active,.is-dark.is-active.textarea,.content kbd.is-active.textarea,.is-dark.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.content kbd.is-active.input,#documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.is-primary.textarea,.docstring>section>a.textarea.docs-sourcelink,.is-primary.input,#documenter .docs-sidebar form.docs-search>input.is-primary,.docstring>section>a.input.docs-sourcelink{border-color:#4eb5de}.is-primary.textarea:focus,.docstring>section>a.textarea.docs-sourcelink:focus,.is-primary.input:focus,#documenter .docs-sidebar form.docs-search>input.is-primary:focus,.docstring>section>a.input.docs-sourcelink:focus,.is-primary.is-focused.textarea,.docstring>section>a.is-focused.textarea.docs-sourcelink,.is-primary.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.docstring>section>a.is-focused.input.docs-sourcelink,.is-primary.textarea:active,.docstring>section>a.textarea.docs-sourcelink:active,.is-primary.input:active,#documenter .docs-sidebar form.docs-search>input.is-primary:active,.docstring>section>a.input.docs-sourcelink:active,.is-primary.is-active.textarea,.docstring>section>a.is-active.textarea.docs-sourcelink,.is-primary.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.is-link.textarea,.is-link.input,#documenter .docs-sidebar form.docs-search>input.is-link{border-color:#2e63b8}.is-link.textarea:focus,.is-link.input:focus,#documenter .docs-sidebar form.docs-search>input.is-link:focus,.is-link.is-focused.textarea,.is-link.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-link.textarea:active,.is-link.input:active,#documenter .docs-sidebar form.docs-search>input.is-link:active,.is-link.is-active.textarea,.is-link.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.is-info.textarea,.is-info.input,#documenter .docs-sidebar form.docs-search>input.is-info{border-color:#209cee}.is-info.textarea:focus,.is-info.input:focus,#documenter .docs-sidebar form.docs-search>input.is-info:focus,.is-info.is-focused.textarea,.is-info.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-info.textarea:active,.is-info.input:active,#documenter .docs-sidebar form.docs-search>input.is-info:active,.is-info.is-active.textarea,.is-info.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.is-success.textarea,.is-success.input,#documenter .docs-sidebar form.docs-search>input.is-success{border-color:#22c35b}.is-success.textarea:focus,.is-success.input:focus,#documenter .docs-sidebar form.docs-search>input.is-success:focus,.is-success.is-focused.textarea,.is-success.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-success.textarea:active,.is-success.input:active,#documenter .docs-sidebar form.docs-search>input.is-success:active,.is-success.is-active.textarea,.is-success.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.is-warning.textarea,.is-warning.input,#documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ffdd57}.is-warning.textarea:focus,.is-warning.input:focus,#documenter .docs-sidebar form.docs-search>input.is-warning:focus,.is-warning.is-focused.textarea,.is-warning.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-warning.textarea:active,.is-warning.input:active,#documenter .docs-sidebar form.docs-search>input.is-warning:active,.is-warning.is-active.textarea,.is-warning.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.is-danger.textarea,.is-danger.input,#documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#da0b00}.is-danger.textarea:focus,.is-danger.input:focus,#documenter .docs-sidebar form.docs-search>input.is-danger:focus,.is-danger.is-focused.textarea,.is-danger.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-danger.textarea:active,.is-danger.input:active,#documenter .docs-sidebar form.docs-search>input.is-danger:active,.is-danger.is-active.textarea,.is-danger.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.is-small.textarea,.is-small.input,#documenter .docs-sidebar form.docs-search>input{border-radius:2px;font-size:.75rem}.is-medium.textarea,.is-medium.input,#documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}.is-large.textarea,.is-large.input,#documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}.is-fullwidth.textarea,.is-fullwidth.input,#documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}.is-inline.textarea,.is-inline.input,#documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}.input.is-rounded,#documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}.input.is-static,#documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}.textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}.textarea:not([rows]){max-height:40em;min-height:8em}.textarea[rows]{height:initial}.textarea.has-fixed-size{resize:none}.radio,.checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}.radio input,.checkbox input{cursor:pointer}.radio:hover,.checkbox:hover{color:#222}.radio[disabled],.checkbox[disabled],fieldset[disabled] .radio,fieldset[disabled] .checkbox,.radio input[disabled],.checkbox input[disabled]{color:#6b6b6b;cursor:not-allowed}.radio+.radio{margin-left:.5em}.select{display:inline-block;max-width:100%;position:relative;vertical-align:top}.select:not(.is-multiple){height:2.5em}.select:not(.is-multiple):not(.is-loading)::after{border-color:#2e63b8;right:1.125em;z-index:4}.select.is-rounded select,#documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}.select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}.select select::-ms-expand{display:none}.select select[disabled]:hover,fieldset[disabled] .select select:hover{border-color:#f5f5f5}.select select:not([multiple]){padding-right:2.5em}.select select[multiple]{height:auto;padding:0}.select select[multiple] option{padding:0.5em 1em}.select:not(.is-multiple):not(.is-loading):hover::after{border-color:#222}.select.is-white:not(:hover)::after{border-color:#fff}.select.is-white select{border-color:#fff}.select.is-white select:hover,.select.is-white select.is-hovered{border-color:#f2f2f2}.select.is-white select:focus,.select.is-white select.is-focused,.select.is-white select:active,.select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.select.is-black:not(:hover)::after{border-color:#0a0a0a}.select.is-black select{border-color:#0a0a0a}.select.is-black select:hover,.select.is-black select.is-hovered{border-color:#000}.select.is-black select:focus,.select.is-black select.is-focused,.select.is-black select:active,.select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.select.is-light:not(:hover)::after{border-color:#f5f5f5}.select.is-light select{border-color:#f5f5f5}.select.is-light select:hover,.select.is-light select.is-hovered{border-color:#e8e8e8}.select.is-light select:focus,.select.is-light select.is-focused,.select.is-light select:active,.select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.select.is-dark:not(:hover)::after,.content kbd.select:not(:hover)::after{border-color:#363636}.select.is-dark select,.content kbd.select select{border-color:#363636}.select.is-dark select:hover,.content kbd.select select:hover,.select.is-dark select.is-hovered,.content kbd.select select.is-hovered{border-color:#292929}.select.is-dark select:focus,.content kbd.select select:focus,.select.is-dark select.is-focused,.content kbd.select select.is-focused,.select.is-dark select:active,.content kbd.select select:active,.select.is-dark select.is-active,.content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.select.is-primary:not(:hover)::after,.docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#4eb5de}.select.is-primary select,.docstring>section>a.select.docs-sourcelink select{border-color:#4eb5de}.select.is-primary select:hover,.docstring>section>a.select.docs-sourcelink select:hover,.select.is-primary select.is-hovered,.docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#39acda}.select.is-primary select:focus,.docstring>section>a.select.docs-sourcelink select:focus,.select.is-primary select.is-focused,.docstring>section>a.select.docs-sourcelink select.is-focused,.select.is-primary select:active,.docstring>section>a.select.docs-sourcelink select:active,.select.is-primary select.is-active,.docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.select.is-link:not(:hover)::after{border-color:#2e63b8}.select.is-link select{border-color:#2e63b8}.select.is-link select:hover,.select.is-link select.is-hovered{border-color:#2958a4}.select.is-link select:focus,.select.is-link select.is-focused,.select.is-link select:active,.select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select.is-info:not(:hover)::after{border-color:#209cee}.select.is-info select{border-color:#209cee}.select.is-info select:hover,.select.is-info select.is-hovered{border-color:#1190e3}.select.is-info select:focus,.select.is-info select.is-focused,.select.is-info select:active,.select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.select.is-success:not(:hover)::after{border-color:#22c35b}.select.is-success select{border-color:#22c35b}.select.is-success select:hover,.select.is-success select.is-hovered{border-color:#1ead51}.select.is-success select:focus,.select.is-success select.is-focused,.select.is-success select:active,.select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.select.is-warning:not(:hover)::after{border-color:#ffdd57}.select.is-warning select{border-color:#ffdd57}.select.is-warning select:hover,.select.is-warning select.is-hovered{border-color:#ffd83e}.select.is-warning select:focus,.select.is-warning select.is-focused,.select.is-warning select:active,.select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.select.is-danger:not(:hover)::after{border-color:#da0b00}.select.is-danger select{border-color:#da0b00}.select.is-danger select:hover,.select.is-danger select.is-hovered{border-color:#c10a00}.select.is-danger select:focus,.select.is-danger select.is-focused,.select.is-danger select:active,.select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.select.is-small,#documenter .docs-sidebar form.docs-search>input.select{border-radius:2px;font-size:.75rem}.select.is-medium{font-size:1.25rem}.select.is-large{font-size:1.5rem}.select.is-disabled::after{border-color:#6b6b6b !important;opacity:0.5}.select.is-fullwidth{width:100%}.select.is-fullwidth select{width:100%}.select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}.select.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.select.is-loading.is-medium:after{font-size:1.25rem}.select.is-loading.is-large:after{font-size:1.5rem}.file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}.file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}.file.is-white:hover .file-cta,.file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.file.is-white:focus .file-cta,.file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}.file.is-white:active .file-cta,.file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}.file.is-black:hover .file-cta,.file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}.file.is-black:focus .file-cta,.file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}.file.is-black:active .file-cta,.file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}.file.is-light .file-cta{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:hover .file-cta,.file.is-light.is-hovered .file-cta{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:focus .file-cta,.file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(245,245,245,0.25);color:rgba(0,0,0,0.7)}.file.is-light:active .file-cta,.file.is-light.is-active .file-cta{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-dark .file-cta,.content kbd.file .file-cta{background-color:#363636;border-color:transparent;color:#fff}.file.is-dark:hover .file-cta,.content kbd.file:hover .file-cta,.file.is-dark.is-hovered .file-cta,.content kbd.file.is-hovered .file-cta{background-color:#2f2f2f;border-color:transparent;color:#fff}.file.is-dark:focus .file-cta,.content kbd.file:focus .file-cta,.file.is-dark.is-focused .file-cta,.content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(54,54,54,0.25);color:#fff}.file.is-dark:active .file-cta,.content kbd.file:active .file-cta,.file.is-dark.is-active .file-cta,.content kbd.file.is-active .file-cta{background-color:#292929;border-color:transparent;color:#fff}.file.is-primary .file-cta,.docstring>section>a.file.docs-sourcelink .file-cta{background-color:#4eb5de;border-color:transparent;color:#fff}.file.is-primary:hover .file-cta,.docstring>section>a.file.docs-sourcelink:hover .file-cta,.file.is-primary.is-hovered .file-cta,.docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#43b1dc;border-color:transparent;color:#fff}.file.is-primary:focus .file-cta,.docstring>section>a.file.docs-sourcelink:focus .file-cta,.file.is-primary.is-focused .file-cta,.docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(78,181,222,0.25);color:#fff}.file.is-primary:active .file-cta,.docstring>section>a.file.docs-sourcelink:active .file-cta,.file.is-primary.is-active .file-cta,.docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#39acda;border-color:transparent;color:#fff}.file.is-link .file-cta{background-color:#2e63b8;border-color:transparent;color:#fff}.file.is-link:hover .file-cta,.file.is-link.is-hovered .file-cta{background-color:#2b5eae;border-color:transparent;color:#fff}.file.is-link:focus .file-cta,.file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(46,99,184,0.25);color:#fff}.file.is-link:active .file-cta,.file.is-link.is-active .file-cta{background-color:#2958a4;border-color:transparent;color:#fff}.file.is-info .file-cta{background-color:#209cee;border-color:transparent;color:#fff}.file.is-info:hover .file-cta,.file.is-info.is-hovered .file-cta{background-color:#1497ed;border-color:transparent;color:#fff}.file.is-info:focus .file-cta,.file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(32,156,238,0.25);color:#fff}.file.is-info:active .file-cta,.file.is-info.is-active .file-cta{background-color:#1190e3;border-color:transparent;color:#fff}.file.is-success .file-cta{background-color:#22c35b;border-color:transparent;color:#fff}.file.is-success:hover .file-cta,.file.is-success.is-hovered .file-cta{background-color:#20b856;border-color:transparent;color:#fff}.file.is-success:focus .file-cta,.file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(34,195,91,0.25);color:#fff}.file.is-success:active .file-cta,.file.is-success.is-active .file-cta{background-color:#1ead51;border-color:transparent;color:#fff}.file.is-warning .file-cta{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:hover .file-cta,.file.is-warning.is-hovered .file-cta{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:focus .file-cta,.file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,221,87,0.25);color:rgba(0,0,0,0.7)}.file.is-warning:active .file-cta,.file.is-warning.is-active .file-cta{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-danger .file-cta{background-color:#da0b00;border-color:transparent;color:#fff}.file.is-danger:hover .file-cta,.file.is-danger.is-hovered .file-cta{background-color:#cd0a00;border-color:transparent;color:#fff}.file.is-danger:focus .file-cta,.file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(218,11,0,0.25);color:#fff}.file.is-danger:active .file-cta,.file.is-danger.is-active .file-cta{background-color:#c10a00;border-color:transparent;color:#fff}.file.is-small,#documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}.file.is-normal{font-size:1rem}.file.is-medium{font-size:1.25rem}.file.is-medium .file-icon .fa{font-size:21px}.file.is-large{font-size:1.5rem}.file.is-large .file-icon .fa{font-size:28px}.file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}.file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}.file.has-name.is-empty .file-cta{border-radius:4px}.file.has-name.is-empty .file-name{display:none}.file.is-boxed .file-label{flex-direction:column}.file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}.file.is-boxed .file-name{border-width:0 1px 1px}.file.is-boxed .file-icon{height:1.5em;width:1.5em}.file.is-boxed .file-icon .fa{font-size:21px}.file.is-boxed.is-small .file-icon .fa,#documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}.file.is-boxed.is-medium .file-icon .fa{font-size:28px}.file.is-boxed.is-large .file-icon .fa{font-size:35px}.file.is-boxed.has-name .file-cta{border-radius:4px 4px 0 0}.file.is-boxed.has-name .file-name{border-radius:0 0 4px 4px;border-width:0 1px 1px}.file.is-centered{justify-content:center}.file.is-fullwidth .file-label{width:100%}.file.is-fullwidth .file-name{flex-grow:1;max-width:none}.file.is-right{justify-content:flex-end}.file.is-right .file-cta{border-radius:0 4px 4px 0}.file.is-right .file-name{border-radius:4px 0 0 4px;border-width:1px 0 1px 1px;order:-1}.file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}.file-label:hover .file-cta{background-color:#eee;color:#222}.file-label:hover .file-name{border-color:#d5d5d5}.file-label:active .file-cta{background-color:#e8e8e8;color:#222}.file-label:active .file-name{border-color:#cfcfcf}.file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}.file-cta,.file-name{border-color:#dbdbdb;border-radius:4px;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}.file-cta{background-color:#f5f5f5;color:#222}.file-name{border-color:#dbdbdb;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}.file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}.file-icon .fa{font-size:14px}.label{color:#222;display:block;font-size:1rem;font-weight:700}.label:not(:last-child){margin-bottom:0.5em}.label.is-small,#documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}.label.is-medium{font-size:1.25rem}.label.is-large{font-size:1.5rem}.help{display:block;font-size:.75rem;margin-top:0.25rem}.help.is-white{color:#fff}.help.is-black{color:#0a0a0a}.help.is-light{color:#f5f5f5}.help.is-dark,.content kbd.help{color:#363636}.help.is-primary,.docstring>section>a.help.docs-sourcelink{color:#4eb5de}.help.is-link{color:#2e63b8}.help.is-info{color:#209cee}.help.is-success{color:#22c35b}.help.is-warning{color:#ffdd57}.help.is-danger{color:#da0b00}.field:not(:last-child){margin-bottom:0.75rem}.field.has-addons{display:flex;justify-content:flex-start}.field.has-addons .control:not(:last-child){margin-right:-1px}.field.has-addons .control:not(:first-child):not(:last-child) .button,.field.has-addons .control:not(:first-child):not(:last-child) .input,.field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,.field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}.field.has-addons .control:first-child:not(:only-child) .button,.field.has-addons .control:first-child:not(:only-child) .input,.field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,.field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}.field.has-addons .control:last-child:not(:only-child) .button,.field.has-addons .control:last-child:not(:only-child) .input,.field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,.field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}.field.has-addons .control .button:not([disabled]):hover,.field.has-addons .control .button.is-hovered:not([disabled]),.field.has-addons .control .input:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,.field.has-addons .control .input.is-hovered:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),.field.has-addons .control .select select:not([disabled]):hover,.field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}.field.has-addons .control .button:not([disabled]):focus,.field.has-addons .control .button.is-focused:not([disabled]),.field.has-addons .control .button:not([disabled]):active,.field.has-addons .control .button.is-active:not([disabled]),.field.has-addons .control .input:not([disabled]):focus,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,.field.has-addons .control .input.is-focused:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),.field.has-addons .control .input:not([disabled]):active,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,.field.has-addons .control .input.is-active:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),.field.has-addons .control .select select:not([disabled]):focus,.field.has-addons .control .select select.is-focused:not([disabled]),.field.has-addons .control .select select:not([disabled]):active,.field.has-addons .control .select select.is-active:not([disabled]){z-index:3}.field.has-addons .control .button:not([disabled]):focus:hover,.field.has-addons .control .button.is-focused:not([disabled]):hover,.field.has-addons .control .button:not([disabled]):active:hover,.field.has-addons .control .button.is-active:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):focus:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,.field.has-addons .control .input.is-focused:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):active:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,.field.has-addons .control .input.is-active:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):focus:hover,.field.has-addons .control .select select.is-focused:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):active:hover,.field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}.field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}.field.has-addons.has-addons-centered{justify-content:center}.field.has-addons.has-addons-right{justify-content:flex-end}.field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}.field.is-grouped{display:flex;justify-content:flex-start}.field.is-grouped>.control{flex-shrink:0}.field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}.field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}.field.is-grouped.is-grouped-centered{justify-content:center}.field.is-grouped.is-grouped-right{justify-content:flex-end}.field.is-grouped.is-grouped-multiline{flex-wrap:wrap}.field.is-grouped.is-grouped-multiline>.control:last-child,.field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}.field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}.field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{.field.is-horizontal{display:flex}}.field-label .label{font-size:inherit}@media screen and (max-width: 768px){.field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{.field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}.field-label.is-small,#documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}.field-label.is-normal{padding-top:0.375em}.field-label.is-medium{font-size:1.25rem;padding-top:0.375em}.field-label.is-large{font-size:1.5rem;padding-top:0.375em}}.field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{.field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}.field-body .field{margin-bottom:0}.field-body>.field{flex-shrink:1}.field-body>.field:not(.is-narrow){flex-grow:1}.field-body>.field:not(:last-child){margin-right:.75rem}}.control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}.control.has-icons-left .input:focus~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,.control.has-icons-left .select:focus~.icon,.control.has-icons-right .input:focus~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,.control.has-icons-right .select:focus~.icon{color:#222}.control.has-icons-left .input.is-small~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,.control.has-icons-left .select.is-small~.icon,.control.has-icons-right .input.is-small~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,.control.has-icons-right .select.is-small~.icon{font-size:.75rem}.control.has-icons-left .input.is-medium~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,.control.has-icons-left .select.is-medium~.icon,.control.has-icons-right .input.is-medium~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,.control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}.control.has-icons-left .input.is-large~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,.control.has-icons-left .select.is-large~.icon,.control.has-icons-right .input.is-large~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,.control.has-icons-right .select.is-large~.icon{font-size:1.5rem}.control.has-icons-left .icon,.control.has-icons-right .icon{color:#dbdbdb;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}.control.has-icons-left .input,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input,.control.has-icons-left .select select{padding-left:2.5em}.control.has-icons-left .icon.is-left{left:0}.control.has-icons-right .input,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input,.control.has-icons-right .select select{padding-right:2.5em}.control.has-icons-right .icon.is-right{right:0}.control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}.control.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.control.is-loading.is-medium:after{font-size:1.25rem}.control.is-loading.is-large:after{font-size:1.5rem}.breadcrumb{font-size:1rem;white-space:nowrap}.breadcrumb a{align-items:center;color:#2e63b8;display:flex;justify-content:center;padding:0 .75em}.breadcrumb a:hover{color:#363636}.breadcrumb li{align-items:center;display:flex}.breadcrumb li:first-child a{padding-left:0}.breadcrumb li.is-active a{color:#222;cursor:default;pointer-events:none}.breadcrumb li+li::before{color:#b5b5b5;content:"\0002f"}.breadcrumb ul,.breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}.breadcrumb .icon:first-child{margin-right:.5em}.breadcrumb .icon:last-child{margin-left:.5em}.breadcrumb.is-centered ol,.breadcrumb.is-centered ul{justify-content:center}.breadcrumb.is-right ol,.breadcrumb.is-right ul{justify-content:flex-end}.breadcrumb.is-small,#documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}.breadcrumb.is-medium{font-size:1.25rem}.breadcrumb.is-large{font-size:1.5rem}.breadcrumb.has-arrow-separator li+li::before{content:"\02192"}.breadcrumb.has-bullet-separator li+li::before{content:"\02022"}.breadcrumb.has-dot-separator li+li::before{content:"\000b7"}.breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}.card{background-color:#fff;border-radius:.25rem;box-shadow:#bbb;color:#222;max-width:100%;position:relative}.card-footer:first-child,.card-content:first-child,.card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-footer:last-child,.card-content:last-child,.card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}.card-header-title{align-items:center;color:#222;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}.card-header-title.is-centered{justify-content:center}.card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}.card-image{display:block;position:relative}.card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-content{background-color:rgba(0,0,0,0);padding:1.5rem}.card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}.card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}.card-footer-item:not(:last-child){border-right:1px solid #ededed}.card .media:not(:last-child){margin-bottom:1.5rem}.dropdown{display:inline-flex;position:relative;vertical-align:top}.dropdown.is-active .dropdown-menu,.dropdown.is-hoverable:hover .dropdown-menu{display:block}.dropdown.is-right .dropdown-menu{left:auto;right:0}.dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}.dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}.dropdown-content{background-color:#fff;border-radius:4px;box-shadow:#bbb;padding-bottom:.5rem;padding-top:.5rem}.dropdown-item{color:#222;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}a.dropdown-item,button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}a.dropdown-item:hover,button.dropdown-item:hover{background-color:#f5f5f5;color:#0a0a0a}a.dropdown-item.is-active,button.dropdown-item.is-active{background-color:#2e63b8;color:#fff}.dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}.level{align-items:center;justify-content:space-between}.level code{border-radius:4px}.level img{display:inline-block;vertical-align:top}.level.is-mobile{display:flex}.level.is-mobile .level-left,.level.is-mobile .level-right{display:flex}.level.is-mobile .level-left+.level-right{margin-top:0}.level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}.level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{.level{display:flex}.level>.level-item:not(.is-narrow){flex-grow:1}}.level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}.level-item .title,.level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){.level-item:not(:last-child){margin-bottom:.75rem}}.level-left,.level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.level-left .level-item.is-flexible,.level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{.level-left .level-item:not(:last-child),.level-right .level-item:not(:last-child){margin-right:.75rem}}.level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){.level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{.level-left{display:flex}}.level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{.level-right{display:flex}}.media{align-items:flex-start;display:flex;text-align:inherit}.media .content:not(:last-child){margin-bottom:.75rem}.media .media{border-top:1px solid rgba(219,219,219,0.5);display:flex;padding-top:.75rem}.media .media .content:not(:last-child),.media .media .control:not(:last-child){margin-bottom:.5rem}.media .media .media{padding-top:.5rem}.media .media .media+.media{margin-top:.5rem}.media+.media{border-top:1px solid rgba(219,219,219,0.5);margin-top:1rem;padding-top:1rem}.media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}.media-left,.media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.media-left{margin-right:1rem}.media-right{margin-left:1rem}.media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){.media-content{overflow-x:auto}}.menu{font-size:1rem}.menu.is-small,#documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}.menu.is-medium{font-size:1.25rem}.menu.is-large{font-size:1.5rem}.menu-list{line-height:1.25}.menu-list a{border-radius:2px;color:#222;display:block;padding:0.5em 0.75em}.menu-list a:hover{background-color:#f5f5f5;color:#222}.menu-list a.is-active{background-color:#2e63b8;color:#fff}.menu-list li ul{border-left:1px solid #dbdbdb;margin:.75em;padding-left:.75em}.menu-label{color:#6b6b6b;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}.menu-label:not(:first-child){margin-top:1em}.menu-label:not(:last-child){margin-bottom:1em}.message{background-color:#f5f5f5;border-radius:4px;font-size:1rem}.message strong{color:currentColor}.message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}.message.is-small,#documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}.message.is-medium{font-size:1.25rem}.message.is-large{font-size:1.5rem}.message.is-white{background-color:#fff}.message.is-white .message-header{background-color:#fff;color:#0a0a0a}.message.is-white .message-body{border-color:#fff}.message.is-black{background-color:#fafafa}.message.is-black .message-header{background-color:#0a0a0a;color:#fff}.message.is-black .message-body{border-color:#0a0a0a}.message.is-light{background-color:#fafafa}.message.is-light .message-header{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.message.is-light .message-body{border-color:#f5f5f5}.message.is-dark,.content kbd.message{background-color:#fafafa}.message.is-dark .message-header,.content kbd.message .message-header{background-color:#363636;color:#fff}.message.is-dark .message-body,.content kbd.message .message-body{border-color:#363636}.message.is-primary,.docstring>section>a.message.docs-sourcelink{background-color:#eef8fc}.message.is-primary .message-header,.docstring>section>a.message.docs-sourcelink .message-header{background-color:#4eb5de;color:#fff}.message.is-primary .message-body,.docstring>section>a.message.docs-sourcelink .message-body{border-color:#4eb5de;color:#1a6d8e}.message.is-link{background-color:#eff3fb}.message.is-link .message-header{background-color:#2e63b8;color:#fff}.message.is-link .message-body{border-color:#2e63b8;color:#3169c4}.message.is-info{background-color:#ecf7fe}.message.is-info .message-header{background-color:#209cee;color:#fff}.message.is-info .message-body{border-color:#209cee;color:#0e72b4}.message.is-success{background-color:#eefcf3}.message.is-success .message-header{background-color:#22c35b;color:#fff}.message.is-success .message-body{border-color:#22c35b;color:#198f43}.message.is-warning{background-color:#fffbeb}.message.is-warning .message-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.message.is-warning .message-body{border-color:#ffdd57;color:#947600}.message.is-danger{background-color:#ffeceb}.message.is-danger .message-header{background-color:#da0b00;color:#fff}.message.is-danger .message-body{border-color:#da0b00;color:#f50c00}.message-header{align-items:center;background-color:#222;border-radius:4px 4px 0 0;color:#fff;display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}.message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}.message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}.message-body{border-color:#dbdbdb;border-radius:4px;border-style:solid;border-width:0 0 0 4px;color:#222;padding:1.25em 1.5em}.message-body code,.message-body pre{background-color:#fff}.message-body pre code{background-color:rgba(0,0,0,0)}.modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}.modal.is-active{display:flex}.modal-background{background-color:rgba(10,10,10,0.86)}.modal-content,.modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){.modal-content,.modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}.modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}.modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}.modal-card-head,.modal-card-foot{align-items:center;background-color:#f5f5f5;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}.modal-card-head{border-bottom:1px solid #dbdbdb;border-top-left-radius:6px;border-top-right-radius:6px}.modal-card-title{color:#222;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}.modal-card-foot{border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:1px solid #dbdbdb}.modal-card-foot .button:not(:last-child){margin-right:.5em}.modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}.navbar{background-color:#fff;min-height:3.25rem;position:relative;z-index:30}.navbar.is-white{background-color:#fff;color:#0a0a0a}.navbar.is-white .navbar-brand>.navbar-item,.navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-brand>a.navbar-item:focus,.navbar.is-white .navbar-brand>a.navbar-item:hover,.navbar.is-white .navbar-brand>a.navbar-item.is-active,.navbar.is-white .navbar-brand .navbar-link:focus,.navbar.is-white .navbar-brand .navbar-link:hover,.navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){.navbar.is-white .navbar-start>.navbar-item,.navbar.is-white .navbar-start .navbar-link,.navbar.is-white .navbar-end>.navbar-item,.navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-start>a.navbar-item:focus,.navbar.is-white .navbar-start>a.navbar-item:hover,.navbar.is-white .navbar-start>a.navbar-item.is-active,.navbar.is-white .navbar-start .navbar-link:focus,.navbar.is-white .navbar-start .navbar-link:hover,.navbar.is-white .navbar-start .navbar-link.is-active,.navbar.is-white .navbar-end>a.navbar-item:focus,.navbar.is-white .navbar-end>a.navbar-item:hover,.navbar.is-white .navbar-end>a.navbar-item.is-active,.navbar.is-white .navbar-end .navbar-link:focus,.navbar.is-white .navbar-end .navbar-link:hover,.navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-start .navbar-link::after,.navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}.navbar.is-black{background-color:#0a0a0a;color:#fff}.navbar.is-black .navbar-brand>.navbar-item,.navbar.is-black .navbar-brand .navbar-link{color:#fff}.navbar.is-black .navbar-brand>a.navbar-item:focus,.navbar.is-black .navbar-brand>a.navbar-item:hover,.navbar.is-black .navbar-brand>a.navbar-item.is-active,.navbar.is-black .navbar-brand .navbar-link:focus,.navbar.is-black .navbar-brand .navbar-link:hover,.navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-black .navbar-start>.navbar-item,.navbar.is-black .navbar-start .navbar-link,.navbar.is-black .navbar-end>.navbar-item,.navbar.is-black .navbar-end .navbar-link{color:#fff}.navbar.is-black .navbar-start>a.navbar-item:focus,.navbar.is-black .navbar-start>a.navbar-item:hover,.navbar.is-black .navbar-start>a.navbar-item.is-active,.navbar.is-black .navbar-start .navbar-link:focus,.navbar.is-black .navbar-start .navbar-link:hover,.navbar.is-black .navbar-start .navbar-link.is-active,.navbar.is-black .navbar-end>a.navbar-item:focus,.navbar.is-black .navbar-end>a.navbar-item:hover,.navbar.is-black .navbar-end>a.navbar-item.is-active,.navbar.is-black .navbar-end .navbar-link:focus,.navbar.is-black .navbar-end .navbar-link:hover,.navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-start .navbar-link::after,.navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}.navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}.navbar.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>.navbar-item,.navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>a.navbar-item:focus,.navbar.is-light .navbar-brand>a.navbar-item:hover,.navbar.is-light .navbar-brand>a.navbar-item.is-active,.navbar.is-light .navbar-brand .navbar-link:focus,.navbar.is-light .navbar-brand .navbar-link:hover,.navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-light .navbar-start>.navbar-item,.navbar.is-light .navbar-start .navbar-link,.navbar.is-light .navbar-end>.navbar-item,.navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start>a.navbar-item:focus,.navbar.is-light .navbar-start>a.navbar-item:hover,.navbar.is-light .navbar-start>a.navbar-item.is-active,.navbar.is-light .navbar-start .navbar-link:focus,.navbar.is-light .navbar-start .navbar-link:hover,.navbar.is-light .navbar-start .navbar-link.is-active,.navbar.is-light .navbar-end>a.navbar-item:focus,.navbar.is-light .navbar-end>a.navbar-item:hover,.navbar.is-light .navbar-end>a.navbar-item.is-active,.navbar.is-light .navbar-end .navbar-link:focus,.navbar.is-light .navbar-end .navbar-link:hover,.navbar.is-light .navbar-end .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start .navbar-link::after,.navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}}.navbar.is-dark,.content kbd.navbar{background-color:#363636;color:#fff}.navbar.is-dark .navbar-brand>.navbar-item,.content kbd.navbar .navbar-brand>.navbar-item,.navbar.is-dark .navbar-brand .navbar-link,.content kbd.navbar .navbar-brand .navbar-link{color:#fff}.navbar.is-dark .navbar-brand>a.navbar-item:focus,.content kbd.navbar .navbar-brand>a.navbar-item:focus,.navbar.is-dark .navbar-brand>a.navbar-item:hover,.content kbd.navbar .navbar-brand>a.navbar-item:hover,.navbar.is-dark .navbar-brand>a.navbar-item.is-active,.content kbd.navbar .navbar-brand>a.navbar-item.is-active,.navbar.is-dark .navbar-brand .navbar-link:focus,.content kbd.navbar .navbar-brand .navbar-link:focus,.navbar.is-dark .navbar-brand .navbar-link:hover,.content kbd.navbar .navbar-brand .navbar-link:hover,.navbar.is-dark .navbar-brand .navbar-link.is-active,.content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-brand .navbar-link::after,.content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-burger,.content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-dark .navbar-start>.navbar-item,.content kbd.navbar .navbar-start>.navbar-item,.navbar.is-dark .navbar-start .navbar-link,.content kbd.navbar .navbar-start .navbar-link,.navbar.is-dark .navbar-end>.navbar-item,.content kbd.navbar .navbar-end>.navbar-item,.navbar.is-dark .navbar-end .navbar-link,.content kbd.navbar .navbar-end .navbar-link{color:#fff}.navbar.is-dark .navbar-start>a.navbar-item:focus,.content kbd.navbar .navbar-start>a.navbar-item:focus,.navbar.is-dark .navbar-start>a.navbar-item:hover,.content kbd.navbar .navbar-start>a.navbar-item:hover,.navbar.is-dark .navbar-start>a.navbar-item.is-active,.content kbd.navbar .navbar-start>a.navbar-item.is-active,.navbar.is-dark .navbar-start .navbar-link:focus,.content kbd.navbar .navbar-start .navbar-link:focus,.navbar.is-dark .navbar-start .navbar-link:hover,.content kbd.navbar .navbar-start .navbar-link:hover,.navbar.is-dark .navbar-start .navbar-link.is-active,.content kbd.navbar .navbar-start .navbar-link.is-active,.navbar.is-dark .navbar-end>a.navbar-item:focus,.content kbd.navbar .navbar-end>a.navbar-item:focus,.navbar.is-dark .navbar-end>a.navbar-item:hover,.content kbd.navbar .navbar-end>a.navbar-item:hover,.navbar.is-dark .navbar-end>a.navbar-item.is-active,.content kbd.navbar .navbar-end>a.navbar-item.is-active,.navbar.is-dark .navbar-end .navbar-link:focus,.content kbd.navbar .navbar-end .navbar-link:focus,.navbar.is-dark .navbar-end .navbar-link:hover,.content kbd.navbar .navbar-end .navbar-link:hover,.navbar.is-dark .navbar-end .navbar-link.is-active,.content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-start .navbar-link::after,.content kbd.navbar .navbar-start .navbar-link::after,.navbar.is-dark .navbar-end .navbar-link::after,.content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,.content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#292929;color:#fff}.navbar.is-dark .navbar-dropdown a.navbar-item.is-active,.content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#363636;color:#fff}}.navbar.is-primary,.docstring>section>a.navbar.docs-sourcelink{background-color:#4eb5de;color:#fff}.navbar.is-primary .navbar-brand>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,.navbar.is-primary .navbar-brand .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}.navbar.is-primary .navbar-brand>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,.navbar.is-primary .navbar-brand>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,.navbar.is-primary .navbar-brand>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,.navbar.is-primary .navbar-brand .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,.navbar.is-primary .navbar-brand .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,.navbar.is-primary .navbar-brand .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-brand .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-burger,.docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-primary .navbar-start>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,.navbar.is-primary .navbar-start .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,.navbar.is-primary .navbar-end>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,.navbar.is-primary .navbar-end .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}.navbar.is-primary .navbar-start>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,.navbar.is-primary .navbar-start>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,.navbar.is-primary .navbar-start>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,.navbar.is-primary .navbar-start .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,.navbar.is-primary .navbar-start .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,.navbar.is-primary .navbar-start .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,.navbar.is-primary .navbar-end>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,.navbar.is-primary .navbar-end>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,.navbar.is-primary .navbar-end>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,.navbar.is-primary .navbar-end .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,.navbar.is-primary .navbar-end .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,.navbar.is-primary .navbar-end .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-start .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,.navbar.is-primary .navbar-end .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-dropdown a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#4eb5de;color:#fff}}.navbar.is-link{background-color:#2e63b8;color:#fff}.navbar.is-link .navbar-brand>.navbar-item,.navbar.is-link .navbar-brand .navbar-link{color:#fff}.navbar.is-link .navbar-brand>a.navbar-item:focus,.navbar.is-link .navbar-brand>a.navbar-item:hover,.navbar.is-link .navbar-brand>a.navbar-item.is-active,.navbar.is-link .navbar-brand .navbar-link:focus,.navbar.is-link .navbar-brand .navbar-link:hover,.navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-link .navbar-start>.navbar-item,.navbar.is-link .navbar-start .navbar-link,.navbar.is-link .navbar-end>.navbar-item,.navbar.is-link .navbar-end .navbar-link{color:#fff}.navbar.is-link .navbar-start>a.navbar-item:focus,.navbar.is-link .navbar-start>a.navbar-item:hover,.navbar.is-link .navbar-start>a.navbar-item.is-active,.navbar.is-link .navbar-start .navbar-link:focus,.navbar.is-link .navbar-start .navbar-link:hover,.navbar.is-link .navbar-start .navbar-link.is-active,.navbar.is-link .navbar-end>a.navbar-item:focus,.navbar.is-link .navbar-end>a.navbar-item:hover,.navbar.is-link .navbar-end>a.navbar-item.is-active,.navbar.is-link .navbar-end .navbar-link:focus,.navbar.is-link .navbar-end .navbar-link:hover,.navbar.is-link .navbar-end .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-start .navbar-link::after,.navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#2e63b8;color:#fff}}.navbar.is-info{background-color:#209cee;color:#fff}.navbar.is-info .navbar-brand>.navbar-item,.navbar.is-info .navbar-brand .navbar-link{color:#fff}.navbar.is-info .navbar-brand>a.navbar-item:focus,.navbar.is-info .navbar-brand>a.navbar-item:hover,.navbar.is-info .navbar-brand>a.navbar-item.is-active,.navbar.is-info .navbar-brand .navbar-link:focus,.navbar.is-info .navbar-brand .navbar-link:hover,.navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-info .navbar-start>.navbar-item,.navbar.is-info .navbar-start .navbar-link,.navbar.is-info .navbar-end>.navbar-item,.navbar.is-info .navbar-end .navbar-link{color:#fff}.navbar.is-info .navbar-start>a.navbar-item:focus,.navbar.is-info .navbar-start>a.navbar-item:hover,.navbar.is-info .navbar-start>a.navbar-item.is-active,.navbar.is-info .navbar-start .navbar-link:focus,.navbar.is-info .navbar-start .navbar-link:hover,.navbar.is-info .navbar-start .navbar-link.is-active,.navbar.is-info .navbar-end>a.navbar-item:focus,.navbar.is-info .navbar-end>a.navbar-item:hover,.navbar.is-info .navbar-end>a.navbar-item.is-active,.navbar.is-info .navbar-end .navbar-link:focus,.navbar.is-info .navbar-end .navbar-link:hover,.navbar.is-info .navbar-end .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-start .navbar-link::after,.navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#209cee;color:#fff}}.navbar.is-success{background-color:#22c35b;color:#fff}.navbar.is-success .navbar-brand>.navbar-item,.navbar.is-success .navbar-brand .navbar-link{color:#fff}.navbar.is-success .navbar-brand>a.navbar-item:focus,.navbar.is-success .navbar-brand>a.navbar-item:hover,.navbar.is-success .navbar-brand>a.navbar-item.is-active,.navbar.is-success .navbar-brand .navbar-link:focus,.navbar.is-success .navbar-brand .navbar-link:hover,.navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-success .navbar-start>.navbar-item,.navbar.is-success .navbar-start .navbar-link,.navbar.is-success .navbar-end>.navbar-item,.navbar.is-success .navbar-end .navbar-link{color:#fff}.navbar.is-success .navbar-start>a.navbar-item:focus,.navbar.is-success .navbar-start>a.navbar-item:hover,.navbar.is-success .navbar-start>a.navbar-item.is-active,.navbar.is-success .navbar-start .navbar-link:focus,.navbar.is-success .navbar-start .navbar-link:hover,.navbar.is-success .navbar-start .navbar-link.is-active,.navbar.is-success .navbar-end>a.navbar-item:focus,.navbar.is-success .navbar-end>a.navbar-item:hover,.navbar.is-success .navbar-end>a.navbar-item.is-active,.navbar.is-success .navbar-end .navbar-link:focus,.navbar.is-success .navbar-end .navbar-link:hover,.navbar.is-success .navbar-end .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-start .navbar-link::after,.navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#22c35b;color:#fff}}.navbar.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>.navbar-item,.navbar.is-warning .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>a.navbar-item:focus,.navbar.is-warning .navbar-brand>a.navbar-item:hover,.navbar.is-warning .navbar-brand>a.navbar-item.is-active,.navbar.is-warning .navbar-brand .navbar-link:focus,.navbar.is-warning .navbar-brand .navbar-link:hover,.navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-warning .navbar-start>.navbar-item,.navbar.is-warning .navbar-start .navbar-link,.navbar.is-warning .navbar-end>.navbar-item,.navbar.is-warning .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start>a.navbar-item:focus,.navbar.is-warning .navbar-start>a.navbar-item:hover,.navbar.is-warning .navbar-start>a.navbar-item.is-active,.navbar.is-warning .navbar-start .navbar-link:focus,.navbar.is-warning .navbar-start .navbar-link:hover,.navbar.is-warning .navbar-start .navbar-link.is-active,.navbar.is-warning .navbar-end>a.navbar-item:focus,.navbar.is-warning .navbar-end>a.navbar-item:hover,.navbar.is-warning .navbar-end>a.navbar-item.is-active,.navbar.is-warning .navbar-end .navbar-link:focus,.navbar.is-warning .navbar-end .navbar-link:hover,.navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start .navbar-link::after,.navbar.is-warning .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ffdd57;color:rgba(0,0,0,0.7)}}.navbar.is-danger{background-color:#da0b00;color:#fff}.navbar.is-danger .navbar-brand>.navbar-item,.navbar.is-danger .navbar-brand .navbar-link{color:#fff}.navbar.is-danger .navbar-brand>a.navbar-item:focus,.navbar.is-danger .navbar-brand>a.navbar-item:hover,.navbar.is-danger .navbar-brand>a.navbar-item.is-active,.navbar.is-danger .navbar-brand .navbar-link:focus,.navbar.is-danger .navbar-brand .navbar-link:hover,.navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-danger .navbar-start>.navbar-item,.navbar.is-danger .navbar-start .navbar-link,.navbar.is-danger .navbar-end>.navbar-item,.navbar.is-danger .navbar-end .navbar-link{color:#fff}.navbar.is-danger .navbar-start>a.navbar-item:focus,.navbar.is-danger .navbar-start>a.navbar-item:hover,.navbar.is-danger .navbar-start>a.navbar-item.is-active,.navbar.is-danger .navbar-start .navbar-link:focus,.navbar.is-danger .navbar-start .navbar-link:hover,.navbar.is-danger .navbar-start .navbar-link.is-active,.navbar.is-danger .navbar-end>a.navbar-item:focus,.navbar.is-danger .navbar-end>a.navbar-item:hover,.navbar.is-danger .navbar-end>a.navbar-item.is-active,.navbar.is-danger .navbar-end .navbar-link:focus,.navbar.is-danger .navbar-end .navbar-link:hover,.navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-start .navbar-link::after,.navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#da0b00;color:#fff}}.navbar>.container{align-items:stretch;display:flex;min-height:3.25rem;width:100%}.navbar.has-shadow{box-shadow:0 2px 0 0 #f5f5f5}.navbar.is-fixed-bottom,.navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom{bottom:0}.navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #f5f5f5}.navbar.is-fixed-top{top:0}html.has-navbar-fixed-top,body.has-navbar-fixed-top{padding-top:3.25rem}html.has-navbar-fixed-bottom,body.has-navbar-fixed-bottom{padding-bottom:3.25rem}.navbar-brand,.navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:3.25rem}.navbar-brand a.navbar-item:focus,.navbar-brand a.navbar-item:hover{background-color:transparent}.navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}.navbar-burger{color:#222;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:3.25rem;position:relative;width:3.25rem;margin-left:auto}.navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}.navbar-burger span:nth-child(1){top:calc(50% - 6px)}.navbar-burger span:nth-child(2){top:calc(50% - 1px)}.navbar-burger span:nth-child(3){top:calc(50% + 4px)}.navbar-burger:hover{background-color:rgba(0,0,0,0.05)}.navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}.navbar-burger.is-active span:nth-child(2){opacity:0}.navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}.navbar-menu{display:none}.navbar-item,.navbar-link{color:#222;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}.navbar-item .icon:only-child,.navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}a.navbar-item,.navbar-link{cursor:pointer}a.navbar-item:focus,a.navbar-item:focus-within,a.navbar-item:hover,a.navbar-item.is-active,.navbar-link:focus,.navbar-link:focus-within,.navbar-link:hover,.navbar-link.is-active{background-color:#fafafa;color:#2e63b8}.navbar-item{flex-grow:0;flex-shrink:0}.navbar-item img{max-height:1.75rem}.navbar-item.has-dropdown{padding:0}.navbar-item.is-expanded{flex-grow:1;flex-shrink:1}.navbar-item.is-tab{border-bottom:1px solid transparent;min-height:3.25rem;padding-bottom:calc(0.5rem - 1px)}.navbar-item.is-tab:focus,.navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8}.navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8;border-bottom-style:solid;border-bottom-width:3px;color:#2e63b8;padding-bottom:calc(0.5rem - 3px)}.navbar-content{flex-grow:1;flex-shrink:1}.navbar-link:not(.is-arrowless){padding-right:2.5em}.navbar-link:not(.is-arrowless)::after{border-color:#2e63b8;margin-top:-0.375em;right:1.125em}.navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}.navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}.navbar-divider{background-color:#f5f5f5;border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){.navbar>.container{display:block}.navbar-brand .navbar-item,.navbar-tabs .navbar-item{align-items:center;display:flex}.navbar-link::after{display:none}.navbar-menu{background-color:#fff;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}.navbar-menu.is-active{display:block}.navbar.is-fixed-bottom-touch,.navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-touch{bottom:0}.navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-touch{top:0}.navbar.is-fixed-top .navbar-menu,.navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 3.25rem);overflow:auto}html.has-navbar-fixed-top-touch,body.has-navbar-fixed-top-touch{padding-top:3.25rem}html.has-navbar-fixed-bottom-touch,body.has-navbar-fixed-bottom-touch{padding-bottom:3.25rem}}@media screen and (min-width: 1056px){.navbar,.navbar-menu,.navbar-start,.navbar-end{align-items:stretch;display:flex}.navbar{min-height:3.25rem}.navbar.is-spaced{padding:1rem 2rem}.navbar.is-spaced .navbar-start,.navbar.is-spaced .navbar-end{align-items:center}.navbar.is-spaced a.navbar-item,.navbar.is-spaced .navbar-link{border-radius:4px}.navbar.is-transparent a.navbar-item:focus,.navbar.is-transparent a.navbar-item:hover,.navbar.is-transparent a.navbar-item.is-active,.navbar.is-transparent .navbar-link:focus,.navbar.is-transparent .navbar-link:hover,.navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}.navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}.navbar.is-transparent .navbar-dropdown a.navbar-item:focus,.navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar-burger{display:none}.navbar-item,.navbar-link{align-items:center;display:flex}.navbar-item.has-dropdown{align-items:stretch}.navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}.navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:2px solid #dbdbdb;border-radius:6px 6px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}.navbar-item.is-active .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced .navbar-item.is-active .navbar-dropdown,.navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:hover .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}.navbar-menu{flex-grow:1;flex-shrink:0}.navbar-start{justify-content:flex-start;margin-right:auto}.navbar-end{justify-content:flex-end;margin-left:auto}.navbar-dropdown{background-color:#fff;border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:2px solid #dbdbdb;box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}.navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}.navbar-dropdown a.navbar-item{padding-right:3rem}.navbar-dropdown a.navbar-item:focus,.navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar.is-spaced .navbar-dropdown,.navbar-dropdown.is-boxed{border-radius:6px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}.navbar-dropdown.is-right{left:auto;right:0}.navbar-divider{display:block}.navbar>.container .navbar-brand,.container>.navbar .navbar-brand{margin-left:-.75rem}.navbar>.container .navbar-menu,.container>.navbar .navbar-menu{margin-right:-.75rem}.navbar.is-fixed-bottom-desktop,.navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-desktop{bottom:0}.navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-desktop{top:0}html.has-navbar-fixed-top-desktop,body.has-navbar-fixed-top-desktop{padding-top:3.25rem}html.has-navbar-fixed-bottom-desktop,body.has-navbar-fixed-bottom-desktop{padding-bottom:3.25rem}html.has-spaced-navbar-fixed-top,body.has-spaced-navbar-fixed-top{padding-top:5.25rem}html.has-spaced-navbar-fixed-bottom,body.has-spaced-navbar-fixed-bottom{padding-bottom:5.25rem}a.navbar-item.is-active,.navbar-link.is-active{color:#0a0a0a}a.navbar-item.is-active:not(:focus):not(:hover),.navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}.navbar-item.has-dropdown:focus .navbar-link,.navbar-item.has-dropdown:hover .navbar-link,.navbar-item.has-dropdown.is-active .navbar-link{background-color:#fafafa}}.hero.is-fullheight-with-navbar{min-height:calc(100vh - 3.25rem)}.pagination{font-size:1rem;margin:-.25rem}.pagination.is-small,#documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}.pagination.is-medium{font-size:1.25rem}.pagination.is-large{font-size:1.5rem}.pagination.is-rounded .pagination-previous,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,.pagination.is-rounded .pagination-next,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}.pagination.is-rounded .pagination-link,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}.pagination,.pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}.pagination-previous,.pagination-next,.pagination-link{border-color:#dbdbdb;color:#222;min-width:2.5em}.pagination-previous:hover,.pagination-next:hover,.pagination-link:hover{border-color:#b5b5b5;color:#363636}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus{border-color:#3c5dcd}.pagination-previous:active,.pagination-next:active,.pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}.pagination-previous[disabled],.pagination-previous.is-disabled,.pagination-next[disabled],.pagination-next.is-disabled,.pagination-link[disabled],.pagination-link.is-disabled{background-color:#dbdbdb;border-color:#dbdbdb;box-shadow:none;color:#6b6b6b;opacity:0.5}.pagination-previous,.pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}.pagination-link.is-current{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.pagination-ellipsis{color:#b5b5b5;pointer-events:none}.pagination-list{flex-wrap:wrap}.pagination-list li{list-style:none}@media screen and (max-width: 768px){.pagination{flex-wrap:wrap}.pagination-previous,.pagination-next{flex-grow:1;flex-shrink:1}.pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{.pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{margin-bottom:0;margin-top:0}.pagination-previous{order:2}.pagination-next{order:3}.pagination{justify-content:space-between;margin-bottom:0;margin-top:0}.pagination.is-centered .pagination-previous{order:1}.pagination.is-centered .pagination-list{justify-content:center;order:2}.pagination.is-centered .pagination-next{order:3}.pagination.is-right .pagination-previous{order:1}.pagination.is-right .pagination-next{order:2}.pagination.is-right .pagination-list{justify-content:flex-end;order:3}}.panel{border-radius:6px;box-shadow:#bbb;font-size:1rem}.panel:not(:last-child){margin-bottom:1.5rem}.panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}.panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}.panel.is-white .panel-block.is-active .panel-icon{color:#fff}.panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}.panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}.panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}.panel.is-light .panel-heading{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.panel.is-light .panel-tabs a.is-active{border-bottom-color:#f5f5f5}.panel.is-light .panel-block.is-active .panel-icon{color:#f5f5f5}.panel.is-dark .panel-heading,.content kbd.panel .panel-heading{background-color:#363636;color:#fff}.panel.is-dark .panel-tabs a.is-active,.content kbd.panel .panel-tabs a.is-active{border-bottom-color:#363636}.panel.is-dark .panel-block.is-active .panel-icon,.content kbd.panel .panel-block.is-active .panel-icon{color:#363636}.panel.is-primary .panel-heading,.docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#4eb5de;color:#fff}.panel.is-primary .panel-tabs a.is-active,.docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#4eb5de}.panel.is-primary .panel-block.is-active .panel-icon,.docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#4eb5de}.panel.is-link .panel-heading{background-color:#2e63b8;color:#fff}.panel.is-link .panel-tabs a.is-active{border-bottom-color:#2e63b8}.panel.is-link .panel-block.is-active .panel-icon{color:#2e63b8}.panel.is-info .panel-heading{background-color:#209cee;color:#fff}.panel.is-info .panel-tabs a.is-active{border-bottom-color:#209cee}.panel.is-info .panel-block.is-active .panel-icon{color:#209cee}.panel.is-success .panel-heading{background-color:#22c35b;color:#fff}.panel.is-success .panel-tabs a.is-active{border-bottom-color:#22c35b}.panel.is-success .panel-block.is-active .panel-icon{color:#22c35b}.panel.is-warning .panel-heading{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ffdd57}.panel.is-warning .panel-block.is-active .panel-icon{color:#ffdd57}.panel.is-danger .panel-heading{background-color:#da0b00;color:#fff}.panel.is-danger .panel-tabs a.is-active{border-bottom-color:#da0b00}.panel.is-danger .panel-block.is-active .panel-icon{color:#da0b00}.panel-tabs:not(:last-child),.panel-block:not(:last-child){border-bottom:1px solid #ededed}.panel-heading{background-color:#ededed;border-radius:6px 6px 0 0;color:#222;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}.panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}.panel-tabs a{border-bottom:1px solid #dbdbdb;margin-bottom:-1px;padding:0.5em}.panel-tabs a.is-active{border-bottom-color:#4a4a4a;color:#363636}.panel-list a{color:#222}.panel-list a:hover{color:#2e63b8}.panel-block{align-items:center;color:#222;display:flex;justify-content:flex-start;padding:0.5em 0.75em}.panel-block input[type="checkbox"]{margin-right:.75em}.panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}.panel-block.is-wrapped{flex-wrap:wrap}.panel-block.is-active{border-left-color:#2e63b8;color:#363636}.panel-block.is-active .panel-icon{color:#2e63b8}.panel-block:last-child{border-bottom-left-radius:6px;border-bottom-right-radius:6px}a.panel-block,label.panel-block{cursor:pointer}a.panel-block:hover,label.panel-block:hover{background-color:#f5f5f5}.panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#6b6b6b;margin-right:.75em}.panel-icon .fa{font-size:inherit;line-height:inherit}.tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}.tabs a{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;color:#222;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}.tabs a:hover{border-bottom-color:#222;color:#222}.tabs li{display:block}.tabs li.is-active a{border-bottom-color:#2e63b8;color:#2e63b8}.tabs ul{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}.tabs ul.is-left{padding-right:0.75em}.tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}.tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}.tabs .icon:first-child{margin-right:.5em}.tabs .icon:last-child{margin-left:.5em}.tabs.is-centered ul{justify-content:center}.tabs.is-right ul{justify-content:flex-end}.tabs.is-boxed a{border:1px solid transparent;border-radius:4px 4px 0 0}.tabs.is-boxed a:hover{background-color:#f5f5f5;border-bottom-color:#dbdbdb}.tabs.is-boxed li.is-active a{background-color:#fff;border-color:#dbdbdb;border-bottom-color:rgba(0,0,0,0) !important}.tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}.tabs.is-toggle a{border-color:#dbdbdb;border-style:solid;border-width:1px;margin-bottom:0;position:relative}.tabs.is-toggle a:hover{background-color:#f5f5f5;border-color:#b5b5b5;z-index:2}.tabs.is-toggle li+li{margin-left:-1px}.tabs.is-toggle li:first-child a{border-top-left-radius:4px;border-bottom-left-radius:4px}.tabs.is-toggle li:last-child a{border-top-right-radius:4px;border-bottom-right-radius:4px}.tabs.is-toggle li.is-active a{background-color:#2e63b8;border-color:#2e63b8;color:#fff;z-index:1}.tabs.is-toggle ul{border-bottom:none}.tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}.tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}.tabs.is-small,#documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}.tabs.is-medium{font-size:1.25rem}.tabs.is-large{font-size:1.5rem}.column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>.column.is-narrow{flex:none;width:unset}.columns.is-mobile>.column.is-full{flex:none;width:100%}.columns.is-mobile>.column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>.column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>.column.is-half{flex:none;width:50%}.columns.is-mobile>.column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>.column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>.column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>.column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>.column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>.column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>.column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>.column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>.column.is-offset-half{margin-left:50%}.columns.is-mobile>.column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>.column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>.column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>.column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>.column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>.column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>.column.is-0{flex:none;width:0%}.columns.is-mobile>.column.is-offset-0{margin-left:0%}.columns.is-mobile>.column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>.column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>.column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>.column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>.column.is-3{flex:none;width:25%}.columns.is-mobile>.column.is-offset-3{margin-left:25%}.columns.is-mobile>.column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>.column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>.column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>.column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>.column.is-6{flex:none;width:50%}.columns.is-mobile>.column.is-offset-6{margin-left:50%}.columns.is-mobile>.column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>.column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>.column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>.column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>.column.is-9{flex:none;width:75%}.columns.is-mobile>.column.is-offset-9{margin-left:75%}.columns.is-mobile>.column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>.column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>.column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>.column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>.column.is-12{flex:none;width:100%}.columns.is-mobile>.column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){.column.is-narrow-mobile{flex:none;width:unset}.column.is-full-mobile{flex:none;width:100%}.column.is-three-quarters-mobile{flex:none;width:75%}.column.is-two-thirds-mobile{flex:none;width:66.6666%}.column.is-half-mobile{flex:none;width:50%}.column.is-one-third-mobile{flex:none;width:33.3333%}.column.is-one-quarter-mobile{flex:none;width:25%}.column.is-one-fifth-mobile{flex:none;width:20%}.column.is-two-fifths-mobile{flex:none;width:40%}.column.is-three-fifths-mobile{flex:none;width:60%}.column.is-four-fifths-mobile{flex:none;width:80%}.column.is-offset-three-quarters-mobile{margin-left:75%}.column.is-offset-two-thirds-mobile{margin-left:66.6666%}.column.is-offset-half-mobile{margin-left:50%}.column.is-offset-one-third-mobile{margin-left:33.3333%}.column.is-offset-one-quarter-mobile{margin-left:25%}.column.is-offset-one-fifth-mobile{margin-left:20%}.column.is-offset-two-fifths-mobile{margin-left:40%}.column.is-offset-three-fifths-mobile{margin-left:60%}.column.is-offset-four-fifths-mobile{margin-left:80%}.column.is-0-mobile{flex:none;width:0%}.column.is-offset-0-mobile{margin-left:0%}.column.is-1-mobile{flex:none;width:8.33333337%}.column.is-offset-1-mobile{margin-left:8.33333337%}.column.is-2-mobile{flex:none;width:16.66666674%}.column.is-offset-2-mobile{margin-left:16.66666674%}.column.is-3-mobile{flex:none;width:25%}.column.is-offset-3-mobile{margin-left:25%}.column.is-4-mobile{flex:none;width:33.33333337%}.column.is-offset-4-mobile{margin-left:33.33333337%}.column.is-5-mobile{flex:none;width:41.66666674%}.column.is-offset-5-mobile{margin-left:41.66666674%}.column.is-6-mobile{flex:none;width:50%}.column.is-offset-6-mobile{margin-left:50%}.column.is-7-mobile{flex:none;width:58.33333337%}.column.is-offset-7-mobile{margin-left:58.33333337%}.column.is-8-mobile{flex:none;width:66.66666674%}.column.is-offset-8-mobile{margin-left:66.66666674%}.column.is-9-mobile{flex:none;width:75%}.column.is-offset-9-mobile{margin-left:75%}.column.is-10-mobile{flex:none;width:83.33333337%}.column.is-offset-10-mobile{margin-left:83.33333337%}.column.is-11-mobile{flex:none;width:91.66666674%}.column.is-offset-11-mobile{margin-left:91.66666674%}.column.is-12-mobile{flex:none;width:100%}.column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{.column.is-narrow,.column.is-narrow-tablet{flex:none;width:unset}.column.is-full,.column.is-full-tablet{flex:none;width:100%}.column.is-three-quarters,.column.is-three-quarters-tablet{flex:none;width:75%}.column.is-two-thirds,.column.is-two-thirds-tablet{flex:none;width:66.6666%}.column.is-half,.column.is-half-tablet{flex:none;width:50%}.column.is-one-third,.column.is-one-third-tablet{flex:none;width:33.3333%}.column.is-one-quarter,.column.is-one-quarter-tablet{flex:none;width:25%}.column.is-one-fifth,.column.is-one-fifth-tablet{flex:none;width:20%}.column.is-two-fifths,.column.is-two-fifths-tablet{flex:none;width:40%}.column.is-three-fifths,.column.is-three-fifths-tablet{flex:none;width:60%}.column.is-four-fifths,.column.is-four-fifths-tablet{flex:none;width:80%}.column.is-offset-three-quarters,.column.is-offset-three-quarters-tablet{margin-left:75%}.column.is-offset-two-thirds,.column.is-offset-two-thirds-tablet{margin-left:66.6666%}.column.is-offset-half,.column.is-offset-half-tablet{margin-left:50%}.column.is-offset-one-third,.column.is-offset-one-third-tablet{margin-left:33.3333%}.column.is-offset-one-quarter,.column.is-offset-one-quarter-tablet{margin-left:25%}.column.is-offset-one-fifth,.column.is-offset-one-fifth-tablet{margin-left:20%}.column.is-offset-two-fifths,.column.is-offset-two-fifths-tablet{margin-left:40%}.column.is-offset-three-fifths,.column.is-offset-three-fifths-tablet{margin-left:60%}.column.is-offset-four-fifths,.column.is-offset-four-fifths-tablet{margin-left:80%}.column.is-0,.column.is-0-tablet{flex:none;width:0%}.column.is-offset-0,.column.is-offset-0-tablet{margin-left:0%}.column.is-1,.column.is-1-tablet{flex:none;width:8.33333337%}.column.is-offset-1,.column.is-offset-1-tablet{margin-left:8.33333337%}.column.is-2,.column.is-2-tablet{flex:none;width:16.66666674%}.column.is-offset-2,.column.is-offset-2-tablet{margin-left:16.66666674%}.column.is-3,.column.is-3-tablet{flex:none;width:25%}.column.is-offset-3,.column.is-offset-3-tablet{margin-left:25%}.column.is-4,.column.is-4-tablet{flex:none;width:33.33333337%}.column.is-offset-4,.column.is-offset-4-tablet{margin-left:33.33333337%}.column.is-5,.column.is-5-tablet{flex:none;width:41.66666674%}.column.is-offset-5,.column.is-offset-5-tablet{margin-left:41.66666674%}.column.is-6,.column.is-6-tablet{flex:none;width:50%}.column.is-offset-6,.column.is-offset-6-tablet{margin-left:50%}.column.is-7,.column.is-7-tablet{flex:none;width:58.33333337%}.column.is-offset-7,.column.is-offset-7-tablet{margin-left:58.33333337%}.column.is-8,.column.is-8-tablet{flex:none;width:66.66666674%}.column.is-offset-8,.column.is-offset-8-tablet{margin-left:66.66666674%}.column.is-9,.column.is-9-tablet{flex:none;width:75%}.column.is-offset-9,.column.is-offset-9-tablet{margin-left:75%}.column.is-10,.column.is-10-tablet{flex:none;width:83.33333337%}.column.is-offset-10,.column.is-offset-10-tablet{margin-left:83.33333337%}.column.is-11,.column.is-11-tablet{flex:none;width:91.66666674%}.column.is-offset-11,.column.is-offset-11-tablet{margin-left:91.66666674%}.column.is-12,.column.is-12-tablet{flex:none;width:100%}.column.is-offset-12,.column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){.column.is-narrow-touch{flex:none;width:unset}.column.is-full-touch{flex:none;width:100%}.column.is-three-quarters-touch{flex:none;width:75%}.column.is-two-thirds-touch{flex:none;width:66.6666%}.column.is-half-touch{flex:none;width:50%}.column.is-one-third-touch{flex:none;width:33.3333%}.column.is-one-quarter-touch{flex:none;width:25%}.column.is-one-fifth-touch{flex:none;width:20%}.column.is-two-fifths-touch{flex:none;width:40%}.column.is-three-fifths-touch{flex:none;width:60%}.column.is-four-fifths-touch{flex:none;width:80%}.column.is-offset-three-quarters-touch{margin-left:75%}.column.is-offset-two-thirds-touch{margin-left:66.6666%}.column.is-offset-half-touch{margin-left:50%}.column.is-offset-one-third-touch{margin-left:33.3333%}.column.is-offset-one-quarter-touch{margin-left:25%}.column.is-offset-one-fifth-touch{margin-left:20%}.column.is-offset-two-fifths-touch{margin-left:40%}.column.is-offset-three-fifths-touch{margin-left:60%}.column.is-offset-four-fifths-touch{margin-left:80%}.column.is-0-touch{flex:none;width:0%}.column.is-offset-0-touch{margin-left:0%}.column.is-1-touch{flex:none;width:8.33333337%}.column.is-offset-1-touch{margin-left:8.33333337%}.column.is-2-touch{flex:none;width:16.66666674%}.column.is-offset-2-touch{margin-left:16.66666674%}.column.is-3-touch{flex:none;width:25%}.column.is-offset-3-touch{margin-left:25%}.column.is-4-touch{flex:none;width:33.33333337%}.column.is-offset-4-touch{margin-left:33.33333337%}.column.is-5-touch{flex:none;width:41.66666674%}.column.is-offset-5-touch{margin-left:41.66666674%}.column.is-6-touch{flex:none;width:50%}.column.is-offset-6-touch{margin-left:50%}.column.is-7-touch{flex:none;width:58.33333337%}.column.is-offset-7-touch{margin-left:58.33333337%}.column.is-8-touch{flex:none;width:66.66666674%}.column.is-offset-8-touch{margin-left:66.66666674%}.column.is-9-touch{flex:none;width:75%}.column.is-offset-9-touch{margin-left:75%}.column.is-10-touch{flex:none;width:83.33333337%}.column.is-offset-10-touch{margin-left:83.33333337%}.column.is-11-touch{flex:none;width:91.66666674%}.column.is-offset-11-touch{margin-left:91.66666674%}.column.is-12-touch{flex:none;width:100%}.column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){.column.is-narrow-desktop{flex:none;width:unset}.column.is-full-desktop{flex:none;width:100%}.column.is-three-quarters-desktop{flex:none;width:75%}.column.is-two-thirds-desktop{flex:none;width:66.6666%}.column.is-half-desktop{flex:none;width:50%}.column.is-one-third-desktop{flex:none;width:33.3333%}.column.is-one-quarter-desktop{flex:none;width:25%}.column.is-one-fifth-desktop{flex:none;width:20%}.column.is-two-fifths-desktop{flex:none;width:40%}.column.is-three-fifths-desktop{flex:none;width:60%}.column.is-four-fifths-desktop{flex:none;width:80%}.column.is-offset-three-quarters-desktop{margin-left:75%}.column.is-offset-two-thirds-desktop{margin-left:66.6666%}.column.is-offset-half-desktop{margin-left:50%}.column.is-offset-one-third-desktop{margin-left:33.3333%}.column.is-offset-one-quarter-desktop{margin-left:25%}.column.is-offset-one-fifth-desktop{margin-left:20%}.column.is-offset-two-fifths-desktop{margin-left:40%}.column.is-offset-three-fifths-desktop{margin-left:60%}.column.is-offset-four-fifths-desktop{margin-left:80%}.column.is-0-desktop{flex:none;width:0%}.column.is-offset-0-desktop{margin-left:0%}.column.is-1-desktop{flex:none;width:8.33333337%}.column.is-offset-1-desktop{margin-left:8.33333337%}.column.is-2-desktop{flex:none;width:16.66666674%}.column.is-offset-2-desktop{margin-left:16.66666674%}.column.is-3-desktop{flex:none;width:25%}.column.is-offset-3-desktop{margin-left:25%}.column.is-4-desktop{flex:none;width:33.33333337%}.column.is-offset-4-desktop{margin-left:33.33333337%}.column.is-5-desktop{flex:none;width:41.66666674%}.column.is-offset-5-desktop{margin-left:41.66666674%}.column.is-6-desktop{flex:none;width:50%}.column.is-offset-6-desktop{margin-left:50%}.column.is-7-desktop{flex:none;width:58.33333337%}.column.is-offset-7-desktop{margin-left:58.33333337%}.column.is-8-desktop{flex:none;width:66.66666674%}.column.is-offset-8-desktop{margin-left:66.66666674%}.column.is-9-desktop{flex:none;width:75%}.column.is-offset-9-desktop{margin-left:75%}.column.is-10-desktop{flex:none;width:83.33333337%}.column.is-offset-10-desktop{margin-left:83.33333337%}.column.is-11-desktop{flex:none;width:91.66666674%}.column.is-offset-11-desktop{margin-left:91.66666674%}.column.is-12-desktop{flex:none;width:100%}.column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){.column.is-narrow-widescreen{flex:none;width:unset}.column.is-full-widescreen{flex:none;width:100%}.column.is-three-quarters-widescreen{flex:none;width:75%}.column.is-two-thirds-widescreen{flex:none;width:66.6666%}.column.is-half-widescreen{flex:none;width:50%}.column.is-one-third-widescreen{flex:none;width:33.3333%}.column.is-one-quarter-widescreen{flex:none;width:25%}.column.is-one-fifth-widescreen{flex:none;width:20%}.column.is-two-fifths-widescreen{flex:none;width:40%}.column.is-three-fifths-widescreen{flex:none;width:60%}.column.is-four-fifths-widescreen{flex:none;width:80%}.column.is-offset-three-quarters-widescreen{margin-left:75%}.column.is-offset-two-thirds-widescreen{margin-left:66.6666%}.column.is-offset-half-widescreen{margin-left:50%}.column.is-offset-one-third-widescreen{margin-left:33.3333%}.column.is-offset-one-quarter-widescreen{margin-left:25%}.column.is-offset-one-fifth-widescreen{margin-left:20%}.column.is-offset-two-fifths-widescreen{margin-left:40%}.column.is-offset-three-fifths-widescreen{margin-left:60%}.column.is-offset-four-fifths-widescreen{margin-left:80%}.column.is-0-widescreen{flex:none;width:0%}.column.is-offset-0-widescreen{margin-left:0%}.column.is-1-widescreen{flex:none;width:8.33333337%}.column.is-offset-1-widescreen{margin-left:8.33333337%}.column.is-2-widescreen{flex:none;width:16.66666674%}.column.is-offset-2-widescreen{margin-left:16.66666674%}.column.is-3-widescreen{flex:none;width:25%}.column.is-offset-3-widescreen{margin-left:25%}.column.is-4-widescreen{flex:none;width:33.33333337%}.column.is-offset-4-widescreen{margin-left:33.33333337%}.column.is-5-widescreen{flex:none;width:41.66666674%}.column.is-offset-5-widescreen{margin-left:41.66666674%}.column.is-6-widescreen{flex:none;width:50%}.column.is-offset-6-widescreen{margin-left:50%}.column.is-7-widescreen{flex:none;width:58.33333337%}.column.is-offset-7-widescreen{margin-left:58.33333337%}.column.is-8-widescreen{flex:none;width:66.66666674%}.column.is-offset-8-widescreen{margin-left:66.66666674%}.column.is-9-widescreen{flex:none;width:75%}.column.is-offset-9-widescreen{margin-left:75%}.column.is-10-widescreen{flex:none;width:83.33333337%}.column.is-offset-10-widescreen{margin-left:83.33333337%}.column.is-11-widescreen{flex:none;width:91.66666674%}.column.is-offset-11-widescreen{margin-left:91.66666674%}.column.is-12-widescreen{flex:none;width:100%}.column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){.column.is-narrow-fullhd{flex:none;width:unset}.column.is-full-fullhd{flex:none;width:100%}.column.is-three-quarters-fullhd{flex:none;width:75%}.column.is-two-thirds-fullhd{flex:none;width:66.6666%}.column.is-half-fullhd{flex:none;width:50%}.column.is-one-third-fullhd{flex:none;width:33.3333%}.column.is-one-quarter-fullhd{flex:none;width:25%}.column.is-one-fifth-fullhd{flex:none;width:20%}.column.is-two-fifths-fullhd{flex:none;width:40%}.column.is-three-fifths-fullhd{flex:none;width:60%}.column.is-four-fifths-fullhd{flex:none;width:80%}.column.is-offset-three-quarters-fullhd{margin-left:75%}.column.is-offset-two-thirds-fullhd{margin-left:66.6666%}.column.is-offset-half-fullhd{margin-left:50%}.column.is-offset-one-third-fullhd{margin-left:33.3333%}.column.is-offset-one-quarter-fullhd{margin-left:25%}.column.is-offset-one-fifth-fullhd{margin-left:20%}.column.is-offset-two-fifths-fullhd{margin-left:40%}.column.is-offset-three-fifths-fullhd{margin-left:60%}.column.is-offset-four-fifths-fullhd{margin-left:80%}.column.is-0-fullhd{flex:none;width:0%}.column.is-offset-0-fullhd{margin-left:0%}.column.is-1-fullhd{flex:none;width:8.33333337%}.column.is-offset-1-fullhd{margin-left:8.33333337%}.column.is-2-fullhd{flex:none;width:16.66666674%}.column.is-offset-2-fullhd{margin-left:16.66666674%}.column.is-3-fullhd{flex:none;width:25%}.column.is-offset-3-fullhd{margin-left:25%}.column.is-4-fullhd{flex:none;width:33.33333337%}.column.is-offset-4-fullhd{margin-left:33.33333337%}.column.is-5-fullhd{flex:none;width:41.66666674%}.column.is-offset-5-fullhd{margin-left:41.66666674%}.column.is-6-fullhd{flex:none;width:50%}.column.is-offset-6-fullhd{margin-left:50%}.column.is-7-fullhd{flex:none;width:58.33333337%}.column.is-offset-7-fullhd{margin-left:58.33333337%}.column.is-8-fullhd{flex:none;width:66.66666674%}.column.is-offset-8-fullhd{margin-left:66.66666674%}.column.is-9-fullhd{flex:none;width:75%}.column.is-offset-9-fullhd{margin-left:75%}.column.is-10-fullhd{flex:none;width:83.33333337%}.column.is-offset-10-fullhd{margin-left:83.33333337%}.column.is-11-fullhd{flex:none;width:91.66666674%}.column.is-offset-11-fullhd{margin-left:91.66666674%}.column.is-12-fullhd{flex:none;width:100%}.column.is-offset-12-fullhd{margin-left:100%}}.columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.columns:last-child{margin-bottom:-.75rem}.columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}.columns.is-centered{justify-content:center}.columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}.columns.is-gapless>.column{margin:0;padding:0 !important}.columns.is-gapless:not(:last-child){margin-bottom:1.5rem}.columns.is-gapless:last-child{margin-bottom:0}.columns.is-mobile{display:flex}.columns.is-multiline{flex-wrap:wrap}.columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{.columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){.columns.is-desktop{display:flex}}.columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}.columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}.columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){.columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-0-fullhd{--columnGap: 0rem}}.columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){.columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-1-fullhd{--columnGap: .25rem}}.columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){.columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-2-fullhd{--columnGap: .5rem}}.columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){.columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-3-fullhd{--columnGap: .75rem}}.columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){.columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-4-fullhd{--columnGap: 1rem}}.columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){.columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}.columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){.columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}.columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){.columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}.columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){.columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-8-fullhd{--columnGap: 2rem}}.tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}.tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.tile.is-ancestor:last-child{margin-bottom:-.75rem}.tile.is-ancestor:not(:last-child){margin-bottom:.75rem}.tile.is-child{margin:0 !important}.tile.is-parent{padding:.75rem}.tile.is-vertical{flex-direction:column}.tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{.tile:not(.is-child){display:flex}.tile.is-1{flex:none;width:8.33333337%}.tile.is-2{flex:none;width:16.66666674%}.tile.is-3{flex:none;width:25%}.tile.is-4{flex:none;width:33.33333337%}.tile.is-5{flex:none;width:41.66666674%}.tile.is-6{flex:none;width:50%}.tile.is-7{flex:none;width:58.33333337%}.tile.is-8{flex:none;width:66.66666674%}.tile.is-9{flex:none;width:75%}.tile.is-10{flex:none;width:83.33333337%}.tile.is-11{flex:none;width:91.66666674%}.tile.is-12{flex:none;width:100%}}.hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}.hero .navbar{background:none}.hero .tabs ul{border-bottom:none}.hero.is-white{background-color:#fff;color:#0a0a0a}.hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-white strong{color:inherit}.hero.is-white .title{color:#0a0a0a}.hero.is-white .subtitle{color:rgba(10,10,10,0.9)}.hero.is-white .subtitle a:not(.button),.hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){.hero.is-white .navbar-menu{background-color:#fff}}.hero.is-white .navbar-item,.hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}.hero.is-white a.navbar-item:hover,.hero.is-white a.navbar-item.is-active,.hero.is-white .navbar-link:hover,.hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}.hero.is-white .tabs a:hover{opacity:1}.hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}.hero.is-white .tabs.is-boxed a,.hero.is-white .tabs.is-toggle a{color:#0a0a0a}.hero.is-white .tabs.is-boxed a:hover,.hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-white .tabs.is-boxed li.is-active a,.hero.is-white .tabs.is-boxed li.is-active a:hover,.hero.is-white .tabs.is-toggle li.is-active a,.hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}.hero.is-black{background-color:#0a0a0a;color:#fff}.hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-black strong{color:inherit}.hero.is-black .title{color:#fff}.hero.is-black .subtitle{color:rgba(255,255,255,0.9)}.hero.is-black .subtitle a:not(.button),.hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-black .navbar-menu{background-color:#0a0a0a}}.hero.is-black .navbar-item,.hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-black a.navbar-item:hover,.hero.is-black a.navbar-item.is-active,.hero.is-black .navbar-link:hover,.hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}.hero.is-black .tabs a{color:#fff;opacity:0.9}.hero.is-black .tabs a:hover{opacity:1}.hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}.hero.is-black .tabs.is-boxed a,.hero.is-black .tabs.is-toggle a{color:#fff}.hero.is-black .tabs.is-boxed a:hover,.hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-black .tabs.is-boxed li.is-active a,.hero.is-black .tabs.is-boxed li.is-active a:hover,.hero.is-black .tabs.is-toggle li.is-active a,.hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}.hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){.hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}.hero.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-light strong{color:inherit}.hero.is-light .title{color:rgba(0,0,0,0.7)}.hero.is-light .subtitle{color:rgba(0,0,0,0.9)}.hero.is-light .subtitle a:not(.button),.hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-light .navbar-menu{background-color:#f5f5f5}}.hero.is-light .navbar-item,.hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-light a.navbar-item:hover,.hero.is-light a.navbar-item.is-active,.hero.is-light .navbar-link:hover,.hero.is-light .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-light .tabs a:hover{opacity:1}.hero.is-light .tabs li.is-active a{color:#f5f5f5 !important;opacity:1}.hero.is-light .tabs.is-boxed a,.hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-light .tabs.is-boxed a:hover,.hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-light .tabs.is-boxed li.is-active a,.hero.is-light .tabs.is-boxed li.is-active a:hover,.hero.is-light .tabs.is-toggle li.is-active a,.hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#f5f5f5}.hero.is-light.is-bold{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}}.hero.is-dark,.content kbd.hero{background-color:#363636;color:#fff}.hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-dark strong,.content kbd.hero strong{color:inherit}.hero.is-dark .title,.content kbd.hero .title{color:#fff}.hero.is-dark .subtitle,.content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}.hero.is-dark .subtitle a:not(.button),.content kbd.hero .subtitle a:not(.button),.hero.is-dark .subtitle strong,.content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-dark .navbar-menu,.content kbd.hero .navbar-menu{background-color:#363636}}.hero.is-dark .navbar-item,.content kbd.hero .navbar-item,.hero.is-dark .navbar-link,.content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-dark a.navbar-item:hover,.content kbd.hero a.navbar-item:hover,.hero.is-dark a.navbar-item.is-active,.content kbd.hero a.navbar-item.is-active,.hero.is-dark .navbar-link:hover,.content kbd.hero .navbar-link:hover,.hero.is-dark .navbar-link.is-active,.content kbd.hero .navbar-link.is-active{background-color:#292929;color:#fff}.hero.is-dark .tabs a,.content kbd.hero .tabs a{color:#fff;opacity:0.9}.hero.is-dark .tabs a:hover,.content kbd.hero .tabs a:hover{opacity:1}.hero.is-dark .tabs li.is-active a,.content kbd.hero .tabs li.is-active a{color:#363636 !important;opacity:1}.hero.is-dark .tabs.is-boxed a,.content kbd.hero .tabs.is-boxed a,.hero.is-dark .tabs.is-toggle a,.content kbd.hero .tabs.is-toggle a{color:#fff}.hero.is-dark .tabs.is-boxed a:hover,.content kbd.hero .tabs.is-boxed a:hover,.hero.is-dark .tabs.is-toggle a:hover,.content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-dark .tabs.is-boxed li.is-active a,.content kbd.hero .tabs.is-boxed li.is-active a,.hero.is-dark .tabs.is-boxed li.is-active a:hover,.hero.is-dark .tabs.is-toggle li.is-active a,.content kbd.hero .tabs.is-toggle li.is-active a,.hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#363636}.hero.is-dark.is-bold,.content kbd.hero.is-bold{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}@media screen and (max-width: 768px){.hero.is-dark.is-bold .navbar-menu,.content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}}.hero.is-primary,.docstring>section>a.hero.docs-sourcelink{background-color:#4eb5de;color:#fff}.hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-primary strong,.docstring>section>a.hero.docs-sourcelink strong{color:inherit}.hero.is-primary .title,.docstring>section>a.hero.docs-sourcelink .title{color:#fff}.hero.is-primary .subtitle,.docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}.hero.is-primary .subtitle a:not(.button),.docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),.hero.is-primary .subtitle strong,.docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-primary .navbar-menu,.docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#4eb5de}}.hero.is-primary .navbar-item,.docstring>section>a.hero.docs-sourcelink .navbar-item,.hero.is-primary .navbar-link,.docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-primary a.navbar-item:hover,.docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,.hero.is-primary a.navbar-item.is-active,.docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,.hero.is-primary .navbar-link:hover,.docstring>section>a.hero.docs-sourcelink .navbar-link:hover,.hero.is-primary .navbar-link.is-active,.docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#39acda;color:#fff}.hero.is-primary .tabs a,.docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}.hero.is-primary .tabs a:hover,.docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}.hero.is-primary .tabs li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#4eb5de !important;opacity:1}.hero.is-primary .tabs.is-boxed a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,.hero.is-primary .tabs.is-toggle a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}.hero.is-primary .tabs.is-boxed a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,.hero.is-primary .tabs.is-toggle a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-primary .tabs.is-boxed li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,.hero.is-primary .tabs.is-boxed li.is-active a:hover,.hero.is-primary .tabs.is-toggle li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,.hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#4eb5de}.hero.is-primary.is-bold,.docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}@media screen and (max-width: 768px){.hero.is-primary.is-bold .navbar-menu,.docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}}.hero.is-link{background-color:#2e63b8;color:#fff}.hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-link strong{color:inherit}.hero.is-link .title{color:#fff}.hero.is-link .subtitle{color:rgba(255,255,255,0.9)}.hero.is-link .subtitle a:not(.button),.hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-link .navbar-menu{background-color:#2e63b8}}.hero.is-link .navbar-item,.hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-link a.navbar-item:hover,.hero.is-link a.navbar-item.is-active,.hero.is-link .navbar-link:hover,.hero.is-link .navbar-link.is-active{background-color:#2958a4;color:#fff}.hero.is-link .tabs a{color:#fff;opacity:0.9}.hero.is-link .tabs a:hover{opacity:1}.hero.is-link .tabs li.is-active a{color:#2e63b8 !important;opacity:1}.hero.is-link .tabs.is-boxed a,.hero.is-link .tabs.is-toggle a{color:#fff}.hero.is-link .tabs.is-boxed a:hover,.hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-link .tabs.is-boxed li.is-active a,.hero.is-link .tabs.is-boxed li.is-active a:hover,.hero.is-link .tabs.is-toggle li.is-active a,.hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#2e63b8}.hero.is-link.is-bold{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}@media screen and (max-width: 768px){.hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}}.hero.is-info{background-color:#209cee;color:#fff}.hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-info strong{color:inherit}.hero.is-info .title{color:#fff}.hero.is-info .subtitle{color:rgba(255,255,255,0.9)}.hero.is-info .subtitle a:not(.button),.hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-info .navbar-menu{background-color:#209cee}}.hero.is-info .navbar-item,.hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-info a.navbar-item:hover,.hero.is-info a.navbar-item.is-active,.hero.is-info .navbar-link:hover,.hero.is-info .navbar-link.is-active{background-color:#1190e3;color:#fff}.hero.is-info .tabs a{color:#fff;opacity:0.9}.hero.is-info .tabs a:hover{opacity:1}.hero.is-info .tabs li.is-active a{color:#209cee !important;opacity:1}.hero.is-info .tabs.is-boxed a,.hero.is-info .tabs.is-toggle a{color:#fff}.hero.is-info .tabs.is-boxed a:hover,.hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-info .tabs.is-boxed li.is-active a,.hero.is-info .tabs.is-boxed li.is-active a:hover,.hero.is-info .tabs.is-toggle li.is-active a,.hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#209cee}.hero.is-info.is-bold{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}@media screen and (max-width: 768px){.hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}}.hero.is-success{background-color:#22c35b;color:#fff}.hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-success strong{color:inherit}.hero.is-success .title{color:#fff}.hero.is-success .subtitle{color:rgba(255,255,255,0.9)}.hero.is-success .subtitle a:not(.button),.hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-success .navbar-menu{background-color:#22c35b}}.hero.is-success .navbar-item,.hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-success a.navbar-item:hover,.hero.is-success a.navbar-item.is-active,.hero.is-success .navbar-link:hover,.hero.is-success .navbar-link.is-active{background-color:#1ead51;color:#fff}.hero.is-success .tabs a{color:#fff;opacity:0.9}.hero.is-success .tabs a:hover{opacity:1}.hero.is-success .tabs li.is-active a{color:#22c35b !important;opacity:1}.hero.is-success .tabs.is-boxed a,.hero.is-success .tabs.is-toggle a{color:#fff}.hero.is-success .tabs.is-boxed a:hover,.hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-success .tabs.is-boxed li.is-active a,.hero.is-success .tabs.is-boxed li.is-active a:hover,.hero.is-success .tabs.is-toggle li.is-active a,.hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#22c35b}.hero.is-success.is-bold{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}@media screen and (max-width: 768px){.hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}}.hero.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-warning strong{color:inherit}.hero.is-warning .title{color:rgba(0,0,0,0.7)}.hero.is-warning .subtitle{color:rgba(0,0,0,0.9)}.hero.is-warning .subtitle a:not(.button),.hero.is-warning .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-warning .navbar-menu{background-color:#ffdd57}}.hero.is-warning .navbar-item,.hero.is-warning .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-warning a.navbar-item:hover,.hero.is-warning a.navbar-item.is-active,.hero.is-warning .navbar-link:hover,.hero.is-warning .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.hero.is-warning .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-warning .tabs a:hover{opacity:1}.hero.is-warning .tabs li.is-active a{color:#ffdd57 !important;opacity:1}.hero.is-warning .tabs.is-boxed a,.hero.is-warning .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-warning .tabs.is-boxed a:hover,.hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-warning .tabs.is-boxed li.is-active a,.hero.is-warning .tabs.is-boxed li.is-active a:hover,.hero.is-warning .tabs.is-toggle li.is-active a,.hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ffdd57}.hero.is-warning.is-bold{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}@media screen and (max-width: 768px){.hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}}.hero.is-danger{background-color:#da0b00;color:#fff}.hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-danger strong{color:inherit}.hero.is-danger .title{color:#fff}.hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}.hero.is-danger .subtitle a:not(.button),.hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-danger .navbar-menu{background-color:#da0b00}}.hero.is-danger .navbar-item,.hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-danger a.navbar-item:hover,.hero.is-danger a.navbar-item.is-active,.hero.is-danger .navbar-link:hover,.hero.is-danger .navbar-link.is-active{background-color:#c10a00;color:#fff}.hero.is-danger .tabs a{color:#fff;opacity:0.9}.hero.is-danger .tabs a:hover{opacity:1}.hero.is-danger .tabs li.is-active a{color:#da0b00 !important;opacity:1}.hero.is-danger .tabs.is-boxed a,.hero.is-danger .tabs.is-toggle a{color:#fff}.hero.is-danger .tabs.is-boxed a:hover,.hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-danger .tabs.is-boxed li.is-active a,.hero.is-danger .tabs.is-boxed li.is-active a:hover,.hero.is-danger .tabs.is-toggle li.is-active a,.hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#da0b00}.hero.is-danger.is-bold{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}@media screen and (max-width: 768px){.hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}}.hero.is-small .hero-body,#documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{.hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{.hero.is-large .hero-body{padding:18rem 6rem}}.hero.is-halfheight .hero-body,.hero.is-fullheight .hero-body,.hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}.hero.is-halfheight .hero-body>.container,.hero.is-fullheight .hero-body>.container,.hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}.hero.is-halfheight{min-height:50vh}.hero.is-fullheight{min-height:100vh}.hero-video{overflow:hidden}.hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}.hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){.hero-video{display:none}}.hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){.hero-buttons .button{display:flex}.hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{.hero-buttons{display:flex;justify-content:center}.hero-buttons .button:not(:last-child){margin-right:1.5rem}}.hero-head,.hero-foot{flex-grow:0;flex-shrink:0}.hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{.hero-body{padding:3rem 3rem}}.section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){.section{padding:3rem 3rem}.section.is-medium{padding:9rem 4.5rem}.section.is-large{padding:18rem 6rem}}.footer{background-color:#fafafa;padding:3rem 1.5rem 6rem}h1 .docs-heading-anchor,h1 .docs-heading-anchor:hover,h1 .docs-heading-anchor:visited,h2 .docs-heading-anchor,h2 .docs-heading-anchor:hover,h2 .docs-heading-anchor:visited,h3 .docs-heading-anchor,h3 .docs-heading-anchor:hover,h3 .docs-heading-anchor:visited,h4 .docs-heading-anchor,h4 .docs-heading-anchor:hover,h4 .docs-heading-anchor:visited,h5 .docs-heading-anchor,h5 .docs-heading-anchor:hover,h5 .docs-heading-anchor:visited,h6 .docs-heading-anchor,h6 .docs-heading-anchor:hover,h6 .docs-heading-anchor:visited{color:#222}h1 .docs-heading-anchor-permalink,h2 .docs-heading-anchor-permalink,h3 .docs-heading-anchor-permalink,h4 .docs-heading-anchor-permalink,h5 .docs-heading-anchor-permalink,h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}h1 .docs-heading-anchor-permalink::before,h2 .docs-heading-anchor-permalink::before,h3 .docs-heading-anchor-permalink::before,h4 .docs-heading-anchor-permalink::before,h5 .docs-heading-anchor-permalink::before,h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}h1:hover .docs-heading-anchor-permalink,h2:hover .docs-heading-anchor-permalink,h3:hover .docs-heading-anchor-permalink,h4:hover .docs-heading-anchor-permalink,h5:hover .docs-heading-anchor-permalink,h6:hover .docs-heading-anchor-permalink{visibility:visible}.docs-dark-only{display:none !important}pre{position:relative;overflow:hidden}pre code,pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}pre code:first-of-type,pre code.hljs:first-of-type{padding-top:0.5rem !important}pre code:last-of-type,pre code.hljs:last-of-type{padding-bottom:0.5rem !important}pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#222;cursor:pointer;text-align:center}pre .copy-button:focus,pre .copy-button:hover{opacity:1;background:rgba(34,34,34,0.1);color:#2e63b8}pre .copy-button.success{color:#259a12;opacity:1}pre .copy-button.error{color:#cb3c33;opacity:1}pre:hover .copy-button{opacity:1}.admonition{background-color:#b5b5b5;border-style:solid;border-width:1px;border-color:#363636;border-radius:4px;font-size:1rem}.admonition strong{color:currentColor}.admonition.is-small,#documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}.admonition.is-medium{font-size:1.25rem}.admonition.is-large{font-size:1.5rem}.admonition.is-default{background-color:#b5b5b5;border-color:#363636}.admonition.is-default>.admonition-header{background-color:#363636;color:#fff}.admonition.is-default>.admonition-body{color:#fff}.admonition.is-info{background-color:#def0fc;border-color:#209cee}.admonition.is-info>.admonition-header{background-color:#209cee;color:#fff}.admonition.is-info>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-success{background-color:#bdf4d1;border-color:#22c35b}.admonition.is-success>.admonition-header{background-color:#22c35b;color:#fff}.admonition.is-success>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-warning{background-color:#fff3c5;border-color:#ffdd57}.admonition.is-warning>.admonition-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.admonition.is-warning>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-danger{background-color:#ffaba7;border-color:#da0b00}.admonition.is-danger>.admonition-header{background-color:#da0b00;color:#fff}.admonition.is-danger>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-compat{background-color:#bdeff5;border-color:#1db5c9}.admonition.is-compat>.admonition-header{background-color:#1db5c9;color:#fff}.admonition.is-compat>.admonition-body{color:rgba(0,0,0,0.7)}.admonition-header{color:#fff;background-color:#363636;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}details.admonition.is-details>.admonition-header{list-style:none}details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}.admonition-body{color:#222;padding:0.5rem .75rem}.admonition-body pre{background-color:#f5f5f5}.admonition-body code{background-color:rgba(0,0,0,0.05)}.docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #dbdbdb;box-shadow:2px 2px 3px rgba(10,10,10,0.1);max-width:100%}.docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#f5f5f5;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #dbdbdb;overflow:auto}.docstring>header code{background-color:transparent}.docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}.docstring>header .docstring-binding{margin-right:0.3em}.docstring>header .docstring-category{margin-left:0.3em}.docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #dbdbdb}.docstring>section:last-child{border-bottom:none}.docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}.docstring>section>a.docs-sourcelink:focus{opacity:1 !important}.docstring:hover>section>a.docs-sourcelink{opacity:0.2}.docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}.docstring>section:hover a.docs-sourcelink{opacity:1}.documenter-example-output{background-color:#fff}.outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#ffaba7;color:rgba(0,0,0,0.7);border-bottom:3px solid #da0b00;padding:10px 35px;text-align:center;font-size:15px}.outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}.outdated-warning-overlay a{color:#2e63b8}.outdated-warning-overlay a:hover{color:#363636}.content pre{border:1px solid #dbdbdb}.content code{font-weight:inherit}.content a code{color:#2e63b8}.content h1 code,.content h2 code,.content h3 code,.content h4 code,.content h5 code,.content h6 code{color:#222}.content table{display:block;width:initial;max-width:100%;overflow-x:auto}.content blockquote>ul:first-child,.content blockquote>ol:first-child,.content .admonition-body>ul:first-child,.content .admonition-body>ol:first-child{margin-top:0}pre,code{font-variant-ligatures:no-contextual}.breadcrumb a.is-disabled{cursor:default;pointer-events:none}.breadcrumb a.is-disabled,.breadcrumb a.is-disabled:hover{color:#222}.hljs{background:initial !important}.katex .katex-mathml{top:0;right:0}.katex-display,mjx-container,.MathJax_Display{margin:0.5em 0 !important}html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}li.no-marker{list-style:none}#documenter .docs-main>article{overflow-wrap:break-word}#documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){#documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){#documenter .docs-main{width:100%}#documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}#documenter .docs-main>header,#documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}#documenter .docs-main header.docs-navbar{background-color:#fff;border-bottom:1px solid #dbdbdb;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}#documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}#documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}#documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}#documenter .docs-main header.docs-navbar .docs-right .docs-icon,#documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}#documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}#documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}#documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #bbb;transition-duration:0.7s;-webkit-transition-duration:0.7s}#documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}#documenter .docs-main section.footnotes{border-top:1px solid #dbdbdb}#documenter .docs-main section.footnotes li .tag:first-child,#documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,#documenter .docs-main section.footnotes li .content kbd:first-child,.content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}#documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #dbdbdb;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){#documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}#documenter .docs-main .docs-footer .docs-footer-nextpage,#documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}#documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}#documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}#documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}#documenter .docs-sidebar{display:flex;flex-direction:column;color:#0a0a0a;background-color:#f5f5f5;border-right:1px solid #dbdbdb;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}#documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #bbb}@media screen and (min-width: 1056px){#documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){#documenter .docs-sidebar{left:0;top:0}}#documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}#documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}#documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}#documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}#documenter .docs-sidebar .docs-package-name a,#documenter .docs-sidebar .docs-package-name a:hover{color:#0a0a0a}#documenter .docs-sidebar .docs-version-selector{border-top:1px solid #dbdbdb;display:none;padding:0.5rem}#documenter .docs-sidebar .docs-version-selector.visible{display:flex}#documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #dbdbdb;padding-bottom:1.5rem}#documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}#documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}#documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}#documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}#documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}#documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}#documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}#documenter .docs-sidebar ul.docs-menu .tocitem,#documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#0a0a0a;background:#f5f5f5}#documenter .docs-sidebar ul.docs-menu a.tocitem:hover,#documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#0a0a0a;background-color:#ebebeb}#documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #dbdbdb;border-bottom:1px solid #dbdbdb;background-color:#fff}#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#fff;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#ebebeb;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}#documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}#documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}#documenter .docs-sidebar form.docs-search>input{width:14.4rem}#documenter .docs-sidebar #documenter-search-query{color:#707070;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){#documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#ccc}}@media screen and (max-width: 1055px){#documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#ccc}}kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(0,0,0,0.6);box-shadow:0 2px 0 1px rgba(0,0,0,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}.search-min-width-50{min-width:50%}.search-min-height-100{min-height:100%}.search-modal-card-body{max-height:calc(100vh - 15rem)}.search-result-link{border-radius:0.7em;transition:all 300ms}.search-result-link:hover,.search-result-link:focus{background-color:rgba(0,128,128,0.1)}.search-result-link .property-search-result-badge,.search-result-link .search-filter{transition:all 300ms}.property-search-result-badge,.search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}.search-result-link:hover .property-search-result-badge,.search-result-link:hover .search-filter,.search-result-link:focus .property-search-result-badge,.search-result-link:focus .search-filter{color:#f1f5f9;background-color:#333}.search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}.search-filter:hover,.search-filter:focus{color:#333}.search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}.search-filter-selected:hover,.search-filter-selected:focus{color:#f5f5f5}.search-result-highlight{background-color:#ffdd57;color:black}.search-divider{border-bottom:1px solid #dbdbdb}.search-result-title{width:85%;color:#333}.search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}#search-modal .modal-card-body::-webkit-scrollbar,#search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}#search-modal .modal-card-body::-webkit-scrollbar-thumb,#search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}#search-modal .modal-card-body::-webkit-scrollbar-track,#search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}.w-100{width:100%}.gap-2{gap:0.5rem}.gap-4{gap:1rem}.gap-8{gap:2rem}.ansi span.sgr1{font-weight:bolder}.ansi span.sgr2{font-weight:lighter}.ansi span.sgr3{font-style:italic}.ansi span.sgr4{text-decoration:underline}.ansi span.sgr7{color:#fff;background-color:#222}.ansi span.sgr8{color:transparent}.ansi span.sgr8 span{color:transparent}.ansi span.sgr9{text-decoration:line-through}.ansi span.sgr30{color:#242424}.ansi span.sgr31{color:#a7201f}.ansi span.sgr32{color:#066f00}.ansi span.sgr33{color:#856b00}.ansi span.sgr34{color:#2149b0}.ansi span.sgr35{color:#7d4498}.ansi span.sgr36{color:#007989}.ansi span.sgr37{color:gray}.ansi span.sgr40{background-color:#242424}.ansi span.sgr41{background-color:#a7201f}.ansi span.sgr42{background-color:#066f00}.ansi span.sgr43{background-color:#856b00}.ansi span.sgr44{background-color:#2149b0}.ansi span.sgr45{background-color:#7d4498}.ansi span.sgr46{background-color:#007989}.ansi span.sgr47{background-color:gray}.ansi span.sgr90{color:#616161}.ansi span.sgr91{color:#cb3c33}.ansi span.sgr92{color:#0e8300}.ansi span.sgr93{color:#a98800}.ansi span.sgr94{color:#3c5dcd}.ansi span.sgr95{color:#9256af}.ansi span.sgr96{color:#008fa3}.ansi span.sgr97{color:#f5f5f5}.ansi span.sgr100{background-color:#616161}.ansi span.sgr101{background-color:#cb3c33}.ansi span.sgr102{background-color:#0e8300}.ansi span.sgr103{background-color:#a98800}.ansi span.sgr104{background-color:#3c5dcd}.ansi span.sgr105{background-color:#9256af}.ansi span.sgr106{background-color:#008fa3}.ansi span.sgr107{background-color:#f5f5f5}code.language-julia-repl>span.hljs-meta{color:#066f00;font-weight:bolder}/*! + Theme: Default + Description: Original highlight.js style + Author: (c) Ivan Sagalaev + Maintainer: @highlightjs/core-team + Website: https://highlightjs.org/ + License: see project LICENSE + Touched: 2021 +*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{background:#F3F3F3;color:#444}.hljs-comment{color:#697070}.hljs-tag,.hljs-punctuation{color:#444a}.hljs-tag .hljs-name,.hljs-tag .hljs-attr{color:#444}.hljs-keyword,.hljs-attribute,.hljs-selector-tag,.hljs-meta .hljs-keyword,.hljs-doctag,.hljs-name{font-weight:bold}.hljs-type,.hljs-string,.hljs-number,.hljs-selector-id,.hljs-selector-class,.hljs-quote,.hljs-template-tag,.hljs-deletion{color:#880000}.hljs-title,.hljs-section{color:#880000;font-weight:bold}.hljs-regexp,.hljs-symbol,.hljs-variable,.hljs-template-variable,.hljs-link,.hljs-selector-attr,.hljs-operator,.hljs-selector-pseudo{color:#ab5656}.hljs-literal{color:#695}.hljs-built_in,.hljs-bullet,.hljs-code,.hljs-addition{color:#397300}.hljs-meta{color:#1f7199}.hljs-meta .hljs-string{color:#38a}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold}.gap-4{gap:1rem} diff --git a/dev/assets/themeswap.js b/dev/assets/themeswap.js new file mode 100644 index 000000000..9f5eebe6a --- /dev/null +++ b/dev/assets/themeswap.js @@ -0,0 +1,84 @@ +// Small function to quickly swap out themes. Gets put into the tag.. +function set_theme_from_local_storage() { + // Initialize the theme to null, which means default + var theme = null; + // If the browser supports the localstorage and is not disabled then try to get the + // documenter theme + if (window.localStorage != null) { + // Get the user-picked theme from localStorage. May be `null`, which means the default + // theme. + theme = window.localStorage.getItem("documenter-theme"); + } + // Check if the users preference is for dark color scheme + var darkPreference = + window.matchMedia("(prefers-color-scheme: dark)").matches === true; + // Initialize a few variables for the loop: + // + // - active: will contain the index of the theme that should be active. Note that there + // is no guarantee that localStorage contains sane values. If `active` stays `null` + // we either could not find the theme or it is the default (primary) theme anyway. + // Either way, we then need to stick to the primary theme. + // + // - disabled: style sheets that should be disabled (i.e. all the theme style sheets + // that are not the currently active theme) + var active = null; + var disabled = []; + var primaryLightTheme = null; + var primaryDarkTheme = null; + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // To distinguish the default (primary) theme, it needs to have the data-theme-primary + // attribute set. + if (ss.ownerNode.getAttribute("data-theme-primary") !== null) { + primaryLightTheme = themename; + } + // Check if the theme is primary dark theme so that we could store its name in darkTheme + if (ss.ownerNode.getAttribute("data-theme-primary-dark") !== null) { + primaryDarkTheme = themename; + } + // If we find a matching theme (and it's not the default), we'll set active to non-null + if (themename === theme) active = i; + // Store the style sheets of inactive themes so that we could disable them + if (themename !== theme) disabled.push(ss); + } + var activeTheme = null; + if (active !== null) { + // If we did find an active theme, we'll (1) add the theme--$(theme) class to + document.getElementsByTagName("html")[0].className = "theme--" + theme; + activeTheme = theme; + } else { + // If we did _not_ find an active theme, then we need to fall back to the primary theme + // which can either be dark or light, depending on the user's OS preference. + var activeTheme = darkPreference ? primaryDarkTheme : primaryLightTheme; + // In case it somehow happens that the relevant primary theme was not found in the + // preceding loop, we abort without doing anything. + if (activeTheme === null) { + console.error("Unable to determine primary theme."); + return; + } + // When switching to the primary light theme, then we must not have a class name + // for the tag. That's only for non-primary or the primary dark theme. + if (darkPreference) { + document.getElementsByTagName("html")[0].className = + "theme--" + activeTheme; + } else { + document.getElementsByTagName("html")[0].className = ""; + } + } + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // we'll disable all the stylesheets, except for the active one + ss.disabled = !(themename == activeTheme); + } +} +set_theme_from_local_storage(); diff --git a/dev/assets/warner.js b/dev/assets/warner.js new file mode 100644 index 000000000..3f6f5d008 --- /dev/null +++ b/dev/assets/warner.js @@ -0,0 +1,52 @@ +function maybeAddWarning() { + // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE + // in siteinfo.js. + // If either of these are undefined something went horribly wrong, so we abort. + if ( + window.DOCUMENTER_NEWEST === undefined || + window.DOCUMENTER_CURRENT_VERSION === undefined || + window.DOCUMENTER_STABLE === undefined + ) { + return; + } + + // Current version is not a version number, so we can't tell if it's the newest version. Abort. + if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) { + return; + } + + // Current version is newest version, so no need to add a warning. + if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) { + return; + } + + // Add a noindex meta tag (unless one exists) so that search engines don't index this version of the docs. + if (document.body.querySelector('meta[name="robots"]') === null) { + const meta = document.createElement("meta"); + meta.name = "robots"; + meta.content = "noindex"; + + document.getElementsByTagName("head")[0].appendChild(meta); + } + + const div = document.createElement("div"); + div.classList.add("outdated-warning-overlay"); + const closer = document.createElement("button"); + closer.classList.add("outdated-warning-closer", "delete"); + closer.addEventListener("click", function () { + document.body.removeChild(div); + }); + const href = window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE; + div.innerHTML = + 'This documentation is not for the latest stable release, but for either the development version or an older release.
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/dev/contributing/new-documentation/index.html b/dev/contributing/new-documentation/index.html new file mode 100644 index 000000000..00733cf97 --- /dev/null +++ b/dev/contributing/new-documentation/index.html @@ -0,0 +1,2 @@ + +Contributing to the documentation · RxInfer.jl
GitHub

Contributing to the documentation

Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:

  1. Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.

  2. Identify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.

  3. Fork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.

  4. Make Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.

  5. Submit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.

  6. Review and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.

  7. Merging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!

By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.

Use LiveServer.jl

LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.

To use LiveServer.jl, simply follow these steps[1]

  • Make sure to import the required packages 
julia> using LiveServer, Documenter
  • After importing the required packages, you can start the live server with the following command:
julia> servedocs()
  • 1Make sure to install the LiveServer and Documenter in your current working environment.
diff --git a/dev/contributing/new-example/index.html b/dev/contributing/new-example/index.html new file mode 100644 index 000000000..80569dc3d --- /dev/null +++ b/dev/contributing/new-example/index.html @@ -0,0 +1,7 @@ + +Contributing to the examples · RxInfer.jl
GitHub

Contributing to the examples

We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.

In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/"subcategory" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.

After preparing the new example it is necessary to modify the examples/.meta.jl file.

  1. Make sure that the very first cell of the notebook contains ONLY # <title> in it and has the markdown cell type. This is important for generating links in our documentation.
  2. The path option must be set to a local path in a category sub-folder.
  3. The text in the description option will be used on the Examples page in the documentation.
  4. Set category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).
  5. Please do no use Overview as a name for the new example, the title Overview is reserved.
  6. Use the following template for equations, note that $$ and both \begin and \end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.
$$\begin{aligned}
+      <latex equations here>
+\end{aligned}$$
  1. When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.
  2. Notebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.
variable = 0
+for i in 1:10
+    global variable = variable + i
+end
  1. All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.
  2. All plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.
Note

Please avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.

Note

Use make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.

diff --git a/dev/contributing/new-package/index.html b/dev/contributing/new-package/index.html new file mode 100644 index 000000000..bb5b29384 --- /dev/null +++ b/dev/contributing/new-package/index.html @@ -0,0 +1,28 @@ + +Contributing to the dependencies · RxInfer.jl
GitHub

Contributing to the dependencies

Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.

The benefits of small packages for the ecosystem

In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:

  1. Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.

  2. Collaboration: Teams can work on different packages concurrently, speeding up development.

  3. Version Control: Precise versioning and fewer dependencies lead to leaner projects.

  4. Performance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.

  5. Flexibility: Developers can select and customize packages for their needs.

  6. Community: Smaller packages attract contributors, fostering collaboration and faster feedback.

In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.

Use PkgTemplates

PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:

julia> using PkgTemplates
+
+julia> USER = "your github user name" # Use `reactivebayes` if developing within the ReactiveBayes organisation
+
+julia> template = Template(
+    user = USER, 
+    plugins = [
+        CompatHelper(), 
+        ProjectFile(), 
+        SrcDir(), 
+        Git(), 
+        License(), 
+        Readme(), 
+        Tests(), 
+        GitHubActions(), 
+        Codecov(), 
+        Documenter{GitHubActions}(), 
+        Formatter(style="blue"), 
+        BlueStyleBadge(), 
+        PkgEvalBadge()
+])
+
+julia> template("MyNewCoolPackage")

This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.

  • Adjust the minimum supported version of Julia

After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:

[compat]
+julia = "1.9.2"

Try to be conservative and set as low version of Julia as possible.

  • Adjust the authors of the package

The authors field is present in the Project.toml, e.g 

authors = ["John Wick <john.wick@continental.com>", ...]

  • Add requires dependencies and their [compat] bounds

To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:

julia --project=.

or 

julia
julia> ] activate .

Then, add dependencies like this:

julia> ] add SomeCoolDependency, SomeOtherCoolDependency

For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:

[compat]
+julia = "1.9"
+SomeCoolDependency = "0.19.2"
+SomeOtherCoolDependency = "1.3.12"

For more details on compat bounds, check the official Julia documentation.

Adjust README.md

The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.

Note

Some badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.

Write code and tests

The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.

Simplify Testing with ReTestItems

You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.

Write code and the documentation

Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):

julia --project=docs docs/make.jl

For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.

Hosting Documentation with GitHub Actions

The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.

Enable GitHub Pages in Repository Settings

The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:

  1. Navigate to the GitHub Pages settings of your repository.
  2. Choose the Deploy from a branch option.
  3. Select the gh-pages branch.
diff --git a/dev/contributing/new-release/index.html b/dev/contributing/new-release/index.html new file mode 100644 index 000000000..6c096149e --- /dev/null +++ b/dev/contributing/new-release/index.html @@ -0,0 +1,2 @@ + +Publishing a new release · RxInfer.jl
GitHub

Publishing a new release

Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.

Start the release process

In order to start the release process a person with the associated permissions should:

  • Open a commit page on GitHub
  • Write the @JuliaRegistrator register comment for the commit:

Release comment

The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.

diff --git a/dev/contributing/overview/index.html b/dev/contributing/overview/index.html new file mode 100644 index 000000000..adb355040 --- /dev/null +++ b/dev/contributing/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Contributing

We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.

Reporting bugs

We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.

Nightly Julia status

The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.

PkgEval

Suggesting features

We welcome new feature proposals. However, before submitting a feature request, consider a few things:

  • Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.
  • If you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.

Contributing code

Installing RxInfer

We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:

] dev git@github.com:your_username/RxInfer.jl.git

The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.

Note

It is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.

Core dependencies

RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.

Committing code

We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.

Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well.

Note

Use make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.

Style conventions

We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:

  • Use 4 spaces for indentation
  • Type names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..
  • Function names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..
  • Variable names and function arguments use snake_case
  • The name of a method that modifies its argument(s) must end in !
Note

RxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.

Unit tests

We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.

All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.

The tests can be evaluated by running following command in the Julia REPL:

] test RxInfer

In addition tests can be evaluated by running following command in the RxInfer root directory:

make test
Note

Use make devtest to use local dev-ed versions of the core packages.

Makefile

RxInfer.jl uses Makefile for most common operations:

  • make help: Shows help snippet
  • make test: Run tests, supports extra arguments
    • make test test_args="distributions:normal_mean_variance" would run tests only from distributions/test_normal_mean_variance.jl
    • make test test_args="distributions:normal_mean_variance models:lgssm" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl
    • make test dev=true would run tests while using dev-ed versions of core packages
  • make devtest: Alias for the make test dev=true ...
  • make docs: Compile documentation
  • make devdocs: Same as make docs, but uses dev-ed versions of core packages
  • make examples: Run all examples and put them in the docs/ folder if successfull
  • make devexamples: Same as make examples, but uses dev-ed versions of core packages
  • make lint: Check codestyle
  • make format: Check and fix codestyle
Note

Core packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.

diff --git a/dev/examples/advanced_examples/Active Inference Mountain car/index.html b/dev/examples/advanced_examples/Active Inference Mountain car/index.html new file mode 100644 index 000000000..d1a698a40 --- /dev/null +++ b/dev/examples/advanced_examples/Active Inference Mountain car/index.html @@ -0,0 +1,286 @@ + +Active Inference Mountain car · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Active Inference Mountain car

import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.

The environmental process of the mountain

Firstly, we specify the environmental process according to Ueltzhoeffer (2017) "Deep active inference". This process shows how the environment evolves after interacting with the agent.

Particularly, let's denote $z_t = (\phi_t, \,\,\dot{\phi_t})$ as the environmental state depending on the position $\phi_t$ and velocity $\dot{\phi_t}$ of the car; $a_t$ as the action of the environment on the car. Then the evolution of the state is described as follows

\[\begin{aligned} +\dot{\phi_t} &= \dot{\phi}_{t-1} + F_g(\phi_{t-1}) + F_f(\dot{\phi}_{t-1}) + F_a(a_t)\\ +\phi_t &= \phi_{t-1} + \dot{\phi_t} +\end{aligned}\]

where $F_g(\phi_{t-1})$ is the gravitational force of the hill landscape that depends on the car's position

\[F_g(\phi) = \begin{cases} + -0.05(2\phi + 1) , \, & \mathrm{if} \, \phi < 0 \\ + -0.05 \left[(1 + 5\phi^2)^{-\frac{1}{2}} + \phi^2 (1 + 5\phi^2)^{-\frac{3}{2}} + \frac{1}{16}\phi^4 \right], \, & \mathrm{otherwise} +\end{cases}\]

\[F_f(\dot{\phi})\]

is the friction on the car defined through the car's velocity $F_f(\dot{\phi}) = -0.1 \, \dot{\phi}\,$ and $F_a(a)$ is the engine force $F_a(a) = 0.04 \,\tanh(a).$ Since the car is on low battery, we use the $\tanh(\cdot)$ function to limit the engine force to the interval [-0.04, 0.04].

In the cell below, the create_physics function defines forces $F_g,\, F_f,\, F_a\,$; and the create_world function defines the environmental process of the mountain.

import HypergeometricFunctions: _₂F₁
+
+function create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)
+    # Engine force as function of action
+    Fa = (a::Real) -> engine_force_limit * tanh(a) 
+
+    # Friction force as function of velocity
+    Ff = (y_dot::Real) -> -friction_coefficient * y_dot 
+    
+    # Gravitational force (horizontal component) as function of position
+    Fg = (y::Real) -> begin
+        if y < 0
+            0.05*(-2*y - 1)
+        else
+            0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)
+        end
+    end
+    
+    # The height of the landscape as a function of the horizontal coordinate
+    height = (x::Float64) -> begin
+        if x < 0
+            h = x^2 + x
+        else
+            h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80
+        end
+        return 0.05*h
+    end
+
+    return (Fa, Ff, Fg,height)
+end;
+
+function create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)
+
+    y_t_min = initial_position
+    y_dot_t_min = initial_velocity
+    
+    y_t = y_t_min
+    y_dot_t = y_dot_t_min
+    
+    execute = (a_t::Float64) -> begin
+        # Compute next state
+        y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)
+        y_t = y_t_min + y_dot_t
+    
+        # Reset state for next step
+        y_t_min = y_t
+        y_dot_t_min = y_dot_t
+    end
+    
+    observe = () -> begin 
+        return [y_t, y_dot_t]
+    end
+        
+    return (execute, observe)
+end
create_world (generic function with 1 method)

Let's visualize the mountain landscape and the situation of the car. 

engine_force_limit   = 0.04
+friction_coefficient = 0.1
+
+Fa, Ff, Fg, height = create_physics(
+    engine_force_limit = engine_force_limit,
+    friction_coefficient = friction_coefficient
+);
+initial_position = -0.5
+initial_velocity = 0.0
+
+x_target = [0.5, 0.0] 
+
+valley_x = range(-2, 2, length=400)
+valley_y = [ height(xs) for xs in valley_x ]
+plot(valley_x, valley_y, title = "Mountain valley", label = "Landscape", color = "black")
+scatter!([ initial_position ], [ height(initial_position) ], label="initial car position")   
+scatter!([x_target[1]], [height(x_target[1])], label="camping site")

Naive approach

Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.

N_naive  = 100 # Total simulation time
+pi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only
+
+# Let there be a world
+(execute_naive, observe_naive) = create_world(; 
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+);
+
+y_naive = Vector{Vector{Float64}}(undef, N_naive)
+for t = 1:N_naive
+    execute_naive(pi_naive[t]) # Execute environmental process
+    y_naive[t] = observe_naive() # Observe external states
+end
+
+animation_naive = @animate for i in 1:N_naive
+    plot(valley_x, valley_y, title = "Naive policy", label = "Landscape", color = "black", size = (800, 400))
+    scatter!([y_naive[i][1]], [height(y_naive[i][1])], label="car")
+    scatter!([x_target[1]], [height(x_target[1])], label="goal")   
+end
+
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_naive, "../pics/ai-mountain-car-naive.gif", fps = 24, show_msg = false);

They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.

Active inference approach

Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.

We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows

\[\begin{aligned} +p_t(x,s,u) \propto p(s_{t-1}) \prod_{k=t}^{t+T} p(x_k \mid s_k) \, p(s_k \mid s_{k-1},u_k) \, p(u_k) \, p'(x_k) \nonumber +\end{aligned}\]

where the factors are defined as

\[p'(x_k) = \mathcal{N}(x_k \mid x_{goal},\,V_{goal}) , \quad (\mathrm{target})\]

\[p(s_k \mid s_{k-1},u_k) = \mathcal{N}(s_k \mid \tilde{g}(s_{k-1})+h(u_k),\,\gamma^{-1}) , \quad (\mathrm{state \,\, transition})\]

\[p(x_k \mid s_k) = \mathcal{N}(x_k \mid s_k,\,\theta), \quad (\mathrm{observation})\]

\[p(u_k) = \mathcal{N}(u_k \mid m_u,\,V_u), \quad (\mathrm{control})\]

\[p(s_{t-1}) = \mathcal{N}(s_{t-1} \mid m_{t-1},\,V_{t-1}), \quad (\mathrm{previous \,\, state})\]

where

  • \[x\]

    denotes observations of the agent after interacting with the environment;

  • \[s_t = (s_t,\dot{s_t})\]

    is the state of the car embodying its position and velocity;

  • \[u_t\]

    denotes the control state of the agent;

  • \[h(\cdot)\]

    is the $\tanh(\cdot)$ function modeling engine control;

  • \[\tilde{g}(\cdot)\]

    executes a linear approximation of equations (1) and (2):

\[\begin{aligned} +\dot{s_t} &= \dot{s}_{t-1} + F_g(s_{t-1}) + F_f(\dot{s}_{t-1})\\ +s_t &= s_{t-1} + \dot{s_t} +\end{aligned}\]

In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.

@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)
+    
+    # Transition function modeling transition due to gravity and friction
+    g = (s_t_min::AbstractVector) -> begin 
+        s_t = similar(s_t_min) # Next state
+        s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity
+        s_t[1] = s_t_min[1] + s_t[2] # Update position
+        return s_t
+    end
+    
+    # Function for modeling engine control
+    h = (u::AbstractVector) -> [0.0, Fa(u[1])] 
+    
+    # Inverse engine force, from change in state to corresponding engine force
+    h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] 
+    
+    # Internal model perameters
+    Gamma = 1e4*diageye(2) # Transition precision
+    Theta = 1e-4*diageye(2) # Observation variance
+    
+    m_s_t_min = datavar(Vector{Float64})
+    V_s_t_min = datavar(Matrix{Float64})
+
+    s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)
+    s_k_min = s_t_min
+    
+    m_u = datavar(Vector{Float64}, T)
+    V_u = datavar(Matrix{Float64}, T)
+    
+    m_x = datavar(Vector{Float64}, T)
+    V_x = datavar(Matrix{Float64}, T)
+    
+    u = randomvar(T)
+    s = randomvar(T)
+    x = randomvar(T)
+    
+    u_h_k = randomvar(T)
+    s_g_k = randomvar(T)
+    u_s_sum = randomvar(T)
+    
+    for k in 1:T
+        u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])
+        u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }
+        s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }
+        u_s_sum[k] ~ s_g_k[k] + u_h_k[k]
+        s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)
+        x[k] ~ MvNormal(mean = s[k], cov = Theta)
+        x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal
+        s_k_min = s[k]
+    end
+    
+    return (s, )
+end

After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.

  1. Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time $t$ and gets $T$ observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next $T$ time step.
  2. Infer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state $s_t$ and control $u_t$, i.e. $p(s_t\mid x_t)$ and $p(u_t\mid x_t)$.
  3. Slide: After updating its internal belief, the agent moves to the next time step and uses the inferred action $u_t$ in the previous time step to interact with the environment.

In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:

  • The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next $T$ positions based on the current action. These two function implement the Act-Execute-Observe phase.
  • The compute function infers the policy (which is a set of actions for the next $T$ time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.
  • The slide function implements the Slide phase, which moves the agent internal model to the next time step.
# We are going to use some private functionality from ReactiveMP, 
+# in the future we should expose a proper API for this
+import RxInfer.ReactiveMP: getrecent, messageout
+
+function create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)
+    Epsilon = fill(huge, 1, 1)                # Control prior variance
+    m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors
+    V_u = Matrix{Float64}[ Epsilon for k=1:T ]
+
+    Sigma    = 1e-4*diageye(2) # Goal prior variance
+    m_x      = [zeros(2) for k=1:T]
+    V_x      = [huge*diageye(2) for k=1:T]
+    V_x[end] = Sigma # Set prior to reach goal at t=T
+
+    # Set initial brain state prior
+    m_s_t_min = [initial_position, initial_velocity] 
+    V_s_t_min = tiny * diageye(2)
+    
+    # Set current inference results
+    result = nothing
+
+    # The `infer` function is the heart of the agent
+    # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing
+    compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin
+        m_u[1] = [ upsilon_t ] # Register action with the generative model
+        V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action
+
+        m_x[1] = y_hat_t # Register observation with the generative model
+        V_x[1] = tiny*diageye(2) # Clamp goal prior to observation
+
+        data = Dict(:m_u       => m_u, 
+                    :V_u       => V_u, 
+                    :m_x       => m_x, 
+                    :V_x       => V_x,
+                    :m_s_t_min => m_s_t_min,
+                    :V_s_t_min => V_s_t_min)
+        
+        model  = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) 
+        result = infer(model = model, data = data)
+    end
+    
+    # The `act` function returns the inferred best possible action
+    act = () -> begin
+        if result !== nothing
+            return mode(result.posteriors[:u][2])[1]
+        else
+            return 0.0 # Without inference result we return some 'random' action
+        end
+    end
+    
+    # The `future` function returns the inferred future states
+    future = () -> begin 
+        if result !== nothing 
+            return getindex.(mode.(result.posteriors[:s]), 1)
+        else
+            return zeros(T)
+        end
+    end
+
+    # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step
+    # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`
+    slide = () -> begin
+        (s, ) = result.returnval
+        
+        slide_msg_idx = 3 # This index is model dependend
+        (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))
+
+        m_u = circshift(m_u, -1)
+        m_u[end] = [0.0]
+        V_u = circshift(V_u, -1)
+        V_u[end] = Epsilon
+
+        m_x = circshift(m_x, -1)
+        m_x[end] = x_target
+        V_x = circshift(V_x, -1)
+        V_x[end] = Sigma
+    end
+
+    return (compute, act, slide, future)    
+end
create_agent (generic function with 1 method)

Now it's time to see if we can help our friends arrive at the camping site by midnight?

(execute_ai, observe_ai) = create_world(
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+) # Let there be a world
+
+T_ai = 50
+
+(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent
+    T  = T_ai, 
+    Fa = Fa,
+    Fg = Fg, 
+    Ff = Ff, 
+    engine_force_limit = engine_force_limit,
+    x_target = x_target,
+    initial_position = initial_position,
+    initial_velocity = initial_velocity
+) 
+
+N_ai = 100
+
+# Step through experimental protocol
+agent_a = Vector{Float64}(undef, N_ai) # Actions
+agent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future
+agent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations
+
+for t=1:N_ai
+    agent_a[t] = act_ai()               # Invoke an action from the agent
+    agent_f[t] = future_ai()            # Fetch the predicted future states
+    execute_ai(agent_a[t])              # The action influences hidden external states
+    agent_x[t] = observe_ai()           # Observe the current environmental outcome (update p)
+    compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)
+    slide_ai()                          # Prepare for next iteration
+end
+
+animation_ai = @animate for i in 1:N_ai
+    # pls - plot landscape
+    pls = plot(valley_x, valley_y, title = "Active inference results", label = "Landscape", color = "black")
+    pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label="car")
+    pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label="goal")   
+    pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = "Predicted future", alpha = map(i -> 0.5 / i, 1:T_ai))
+    
+    # pef - plot engine force
+    pef = plot(Fa.(agent_a[1:i]), title = "Engine force (agents actions)", xlim = (0, N_ai), ylim = (-0.05, 0.05))
+    
+    plot(pls, pef, size = (800, 400))
+end
+    
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_ai, "../pics/ai-mountain-car-ai.gif", fps = 24, show_msg = false);

Voila! The car now is able to reach the camping site with a smart strategy.

The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.

Now our friends can enjoy their trip at the camping site!.

Reference

We refer reader to the Thijs van de Laar (2019) "Simulating active inference processes by message passing" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) "Deep active inference".

diff --git a/dev/examples/advanced_examples/Advanced Tutorial/index.html b/dev/examples/advanced_examples/Advanced Tutorial/index.html new file mode 100644 index 000000000..c7d087b05 --- /dev/null +++ b/dev/examples/advanced_examples/Advanced Tutorial/index.html @@ -0,0 +1,416 @@ + +Advanced Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Advanced Tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.

This tutorial is also available in the documentation.

General model specification syntax

We use the @model macro from the RxInfer.jl package to create a probabilistic model $p(s, y)$ and we also specify extra constraints on the variational family of distributions $\mathcal{Q}$, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.

# the `@model` macro accepts a regular Julia function
+@model function test_model1(s_mean, s_precision)
+    
+    # We use the `randomvar` function to create 
+    # a random variable in our model
+    s = randomvar()
+    
+    # the `tilde` operator creates a functional dependency
+    # between variables in our model and can be read as 
+    # `sampled from` or `is modeled by`
+    s ~ Normal(mean = s_mean, precision = s_precision)
+    
+    # We use the `datavar` function to create 
+    # observed data variables in our models
+    # We also need to specify the type of our data 
+    # In this example it is `Float64`
+    y = datavar(Float64)
+    
+    y ~ Normal(mean = s, precision = 1.0)
+    
+    # It is possible to return something from the model specification (including variables and nodes)
+    return "Hello world"
+end

The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.

modelgenerator = test_model1(0.0, 1.0)
+
+model, returnval = create_model(modelgenerator)
(FactorGraphModel(), "Hello world")

The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.

RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as:

  • getnodes(): returns an array of factor nodes in a corresponding factor graph
  • getrandom(): returns an array of random variables in the model
  • getdata(): returns an array of data inputs in the model
  • getconstant(): returns an array of constant values in the model
getnodes(model)
FactorNodesCollection(nodes: 2)
getrandom(model) .|> name
1-element Vector{Symbol}:
+ :s
getdata(model) .|> name
1-element Vector{Symbol}:
+ :y
getconstant(model) .|> getconst
3-element Vector{Float64}:
+ 0.0
+ 1.0
+ 1.0

It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:

@model function test_model2(n)
+    
+    if n <= 1
+        error("`n` argument must be greater than one.")
+    end
+    
+    # `randomvar(n)` creates a dense sequence of 
+    # random variables
+    s = randomvar(n)
+    
+    # `datavar(Float64, n)` creates a dense sequence of 
+    # observed data variables of type `Float64`
+    y = datavar(Float64, n)
+    
+    s[1] ~ Normal(mean = 0.0, precision = 0.1)
+    y[1] ~ Normal(mean = s[1], precision = 1.0)
+    
+    for i in 2:n
+        s[i] ~ Normal(mean = s[i - 1], precision = 1.0)
+        y[i] ~ Normal(mean = s[i], precision = 1.0)
+    end
+    
+end
model, _ = create_model(test_model2(10));
# An amount of factor nodes in generated Factor Graph
+getnodes(model) |> length
20
# An amount of random variables
+getrandom(model) |> length
10
# An amount of data inputs
+getdata(model) |> length
10
# An amount of constant values
+getconstant(model) |> length
21

It is also possible to use complex expressions inside the functional dependency expressions

y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)

The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists

# s = randomvar() here is optional
+# `~` creates random variables automatically
+s ~ NormalMeanPrecision(0.0, 1.0)

An example model which will throw an error:

@model function error_model1()
+    s = 1.0
+    s ~ NormalMeanPrecision(0.0, 1.0)
+end

By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as

# Creates constant reference in a model with a prespecified value
+c = constvar(0.0)

An example:

@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)
+    
+    s = randomvar(n)
+    
+    y = datavar(Vector{Float64}, n)
+    
+    # Here we create constant references
+    # for constant matrices in our model 
+    # to make inference more memory efficient
+    cA = constvar(A)
+    cP = constvar(P)
+    cQ = constvar(Q)
+    
+    s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)
+    y[1] ~ MvNormal(mean = s[1], covariance = cQ)
+    
+    for i in 2:n
+        s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)
+        y[i] ~ MvNormal(mean = s[i], covariance = cQ)
+    end
+    
+end

The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:

@model function test_model()
+
+    # In this example `ynode` refers to the corresponding 
+    # `GaussianMeanVariance` node created in the factor graph
+    ynode, y ~ GaussianMeanVariance(0.0, 1.0)
+    
+    return ynode, y
+end

Probabilistic inference in RxInfer.jl

RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.

Observables

Observables are lazy push-based collections and they deliver their values over time.

# Timer that emits a new value every second and has an initial one second delay 
+observable = timer(300, 300)
TimerObservable(300, 300)

A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:

actor = (value) -> println(value)
+subscription1 = subscribe!(observable, actor)
TimerSubscription()
# We always need to unsubscribe from some observables
+unsubscribe!(subscription1)
# We can modify our observables
+modified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)
ProxyObservable(Int64, MapProxy(Int64))
subscription2 = subscribe!(modified, (value) -> println(value))
TimerSubscription()
unsubscribe!(subscription2)
@model function coin_toss_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+    
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    
+    # We assume that the outcome of each coin flip 
+    # is modeled by a Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+    
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during the inference step
+    return y, θ
+end

We can call the inference function to run inference in such model:

p = 0.75 # Bias of a coin
+
+dataset = float.(rand(Bernoulli(p), 500));
+
+result = infer(
+    model = coin_toss_model(length(dataset)),
+    data  = (y = dataset, )
+)
+
+println("Inferred bias: ", mean_var(result.posteriors[:θ]))
Inferred bias: (0.7406679764243614, 0.00037662534338000586)

We can see that the inferred bias is quite close to the actual value we used in the dataset generation.

The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions:

  • getmarginal(x): for a single random variable x
  • getmarginals(xs): for a dense sequence of random variables sx

Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.

_, (y, θ) = create_model(coin_toss_model(length(dataset)));
# As soon as we have a new value for the marginal posterior over the `θ` variable
+# we simply print the first two statistics of it
+θ_subscription = subscribe!(getmarginal(θ), (marginal) -> println("New update: mean(θ) = ", mean(marginal), ", std(θ) = ", std(marginal)));

To pass data to our model we use update! function

update!(y, dataset)
New update: mean(θ) = 0.7406679764243614, std(θ) = 0.01940683754195943
# It is necessary to always unsubscribe from running observables
+unsubscribe!(θ_subscription)
# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them
+# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing
+update!(y, dataset)

Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.

# the `keep` actor simply keeps all incoming updates in an internal storage, ordered
+θvalues = keep(Marginal)
KeepActor{Marginal}(Marginal[])
# `getmarginal` always emits last cached value as its first value
+subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=377.0, β=132.0))
subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
2-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=377.0, β=132.0))
+ Marginal(Beta{Float64}(α=377.0, β=132.0))
# the `buffer` actor keeps very last incoming update in an internal storage and can also store 
+# an array of updates for a sequence of random variables
+θbuffer = buffer(Marginal, 1)
BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=377.0, β=132.0))
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=377.0, β=132.0))

Reactive Online Inference

RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.

@model function online_coin_toss_model()
+    
+    # We create datavars for the prior 
+    # over `θ` variable
+    θ_a = datavar(Float64)
+    θ_b = datavar(Float64)
+    
+    θ ~ Beta(θ_a, θ_b)
+    
+    y = datavar(Float64)
+    y ~ Bernoulli(θ)
+
+end
autoupdates = @autoupdates begin 
+    θ_a, θ_b = params(q(θ))
+end
(θ_a,θ_b = params(q(θ)),)
rxresult = infer(
+    model = online_coin_toss_model(),
+    data  = (y = dataset, ),
+    autoupdates = autoupdates,
+    historyvars = (θ = KeepLast(), ),
+    keephistory = length(dataset),
+    initmarginals = (
+        θ = vague(Beta),
+    ),
+    autostart = true
+);
animation = @animate for i in 1:length(dataset)
+    plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = "Online coin bias inference", label = "Inferred bias", legend = :bottomright)
+    hline!([ p ], label = "Real bias", size = (600, 200))
+end
+
+gif(animation, "../pics/online-coin-bias-inference.gif", fps = 24, show_msg = false);

In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.

That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.

Variational inference

On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions $q \in \mathcal{Q}$. Often this involves assuming some factorization over $q$. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.

@model function test_model6_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+
+end

In this example we specified an extra constraints for $q_a$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

There are several options to specify the mean-field factorisation constraint. 

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name

It is also possible to use local structured factorisation:

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification

RxInfer.jl constraints macro

RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:

constraints6 = @constraints begin
+     q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

Note: where blocks have higher priority over constraints specification

@model function test_model6(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end

Inference

To run inference in this model we again need to create a synthetic dataset:

dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);

inference function

In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:

Use ?inference to quickly check the documentation for the inference function.

result = infer(
+    model         = test_model6(length(dataset)),
+    data          = (y = dataset, ),
+    constraints   = constraints6, 
+    initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),
+    returnvars    = (μ = KeepLast(), τ = KeepLast()),
+    iterations    = 10,
+    free_energy   = true,
+    showprogress  = true
+)
Inference results:
+  Posteriors       | available for (μ, τ)
+  Free Energy:     | Real[14763.3, 3276.35, 693.1, 656.243, 656.243, 656.24
+3, 656.243, 656.243, 656.243, 656.243]
println("μ: mean = ", mean(result.posteriors[:μ]), ", std = ", std(result.posteriors[:μ]))
μ: mean = -3.0157043055468535, std = 0.014635651570634027
println("τ: mean = ", mean(result.posteriors[:τ]), ", std = ", std(result.posteriors[:τ]))
τ: mean = 4.668474019482058, std = 0.2085720373196144

Manual inference

For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);

For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:

setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values)
10-element Vector{Marginal}:
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.0217421867709698e-9, w
+=0.010000001002000566))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.644059446887734, w=9.
+17668128961832))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9343.678975344314, w=309
+8.3439261025555))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14071.65054777373, w=466
+6.124108101663))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.760251762773, w=46
+68.481663100324))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.76735083667, w=466
+8.484017130393))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357921546, w=46
+68.484019479642))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357928664, w=46
+68.484019482041))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357928651, w=46
+68.484019482041))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357928633, w=46
+68.484019482028))
getvalues(τ_values)
10-element Vector{Marginal}:
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=5.000000000046544e14))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=54654.4582680546))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=161.69980768671172))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.36985602862222))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.3156347847015))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558067189445))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061788989))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061783582))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061783593))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061783606))
println("μ: mean = ", mean(last(μ_values)), ", std = ", std(last(μ_values)))
μ: mean = -3.0157043055468535, std = 0.014635651570634027
println("τ: mean = ", mean(last(τ_values)), ", std = ", std(last(τ_values)))
τ: mean = 4.668474019482058, std = 0.2085720373196144

Form constraints

In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.

<img style="display: block; margin-left: auto; margin-right: auto; width: 50%;" src="./pics/posterior.png" />

@model function test_model7_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+    
+    return μ, τ, y
+end

As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:

constraints7 = @constraints begin 
+    q(μ) :: PointMass
+    
+    q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+    q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

In this example we specified an extra constraints for $q_i$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

@model function test_model7(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar()
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end
model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);
setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, PointMass(1.0))
+
+μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values) |> last
Marginal(PointMass{Float64}(-3.0157043119936424))
getvalues(τ_values) |> last
Marginal(GammaShapeRate{Float64}(a=501.0, b=107.20847946934565))

By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.

μ = randomvar() where { 
+    prod_constraint = ProdGeneric(),
+    form_constraint = SampleListFormConstraint() 
+}

Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:

μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }

Note: @constraints macro specifies required prod_constraint automatically.

Free Energy

During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);
bfe_observable = score(model, Float64, BetheFreeEnergy())
ProxyObservable(Float64, ErrorIfProxy())
bfe_subscription = subscribe!(bfe_observable, (fe) -> println("Current BFE value: ", fe));
# Reset the model with vague marginals
+setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
+
+for i in 1:10
+    update!(y, dataset)
+end
Current BFE value: 668.7879683577721
+Current BFE value: 656.2431248164271
+Current BFE value: 656.2431245675102
+Current BFE value: 656.2431245675134
+Current BFE value: 656.2431245675061
+Current BFE value: 656.2431245675098
+Current BFE value: 656.2431245675107
+Current BFE value: 656.2431245675107
+Current BFE value: 656.2431245675107
+Current BFE value: 656.2431245675107
# It always necessary to unsubscribe and release computer resources
+unsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])

Meta data specification

During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:

# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of 
+# the autoregressive process and its order. In addition it specifies that the message computation rules should
+# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations
+# by cost of possible numerical instabilities during an inference procedure
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }
+...
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }

Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:

# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` 
+# method with `21` sigma points for approximation of non-lineariety between hierarchy layers
+xt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }

The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.

RxInfer.jl @meta macro

Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:

@meta begin 
+     AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())
+end
Meta specification:
+  AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())
+Options:
+  warn = true

Creating custom nodes and message computation rules

Custom nodes

To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:

# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification
+@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]
+
+# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error
+struct NormalMeanVariance end 
+
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# It is also possible to use function objects as a node functional form
+function dot end
+
+# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them 
+# out = dot(x, a)
+@node typeof(dot) Deterministic [ out, x, a ]

Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.

After that it is possible to use the newly created node during model specification:

@model function test_model()
+    ...
+    y ~ dot(x, a)
+    ...
+end

Custom messages computation rules

RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:

\[\begin{aligned} +\mu_z = \mu_x + \mu_y\\ +V_z = V_x + V_y +\end{aligned}\]

To specify this in RxInfer.jl we use the @node and @rule macros:

@node typeof(+) Deterministic  [ z, x, y ]
+
+@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin
+    x_mean, x_var = mean_var(m_x)
+    y_mean, y_var = mean_var(m_y)
+    return NormalMeanVariance(x_mean + y_mean, x_var + y_var)
+end

In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:

\[\begin{aligned} +q(z) = \int q(z, x, y) \mathrm{d}x\mathrm{d}y +\end{aligned}\]

If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:

\[\begin{aligned} +\mu(z) = \int f(x, y, z)\mu(x)\mu(y)\mathrm{d}x\mathrm{d}y +\end{aligned}\]

\[\begin{aligned} +\nu(z) = \exp{ \int \log f(x, y, z)q(x)q(y)\mathrm{d}x\mathrm{d}y } +\end{aligned}\]

The @rule macro supports both cases with special prefixes during rule specification:

  • m_ prefix corresponds to the incoming message on a specific edge
  • q_ prefix corresponds to the posterior marginal of a specific edge

Example of a Sum-Product rule with m_ messages used:

@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin 
+    m_out_mean, m_out_cov = mean_cov(m_out)
+    return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))
+end

Example of a Variational rule with Mean-Field assumption with q_ posteriors used:

@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin 
+    return NormalMeanPrecision(mean(q_out), mean(q_τ))
+end

RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:

@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin
+    m, V = mean_cov(q_out_μ)
+    θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))
+    α = convert(typeof(θ), 1.5)
+    return Gamma(α, θ)
+end

NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:

# Inference backend expects arguments in `@rule` macro to be in the same order
+@node NormalMeanPrecision Stochastic [ out, μ, τ ]

Any rule always has access to the meta information with hidden the meta::Any variable:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin 
+    ...
+    println(meta)
+    ...
+end

It is also possible to dispatch on a specific type of a meta object:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin 
+    ...
+end

or

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin 
+    ...
+end

Customizing messages computational pipeline

In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.

<img style="display: block; margin-left: auto; margin-right: auto; width: 30%;" src="./pics/pipeline.png" width="20%" />

# Logs all outbound messages
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }
+# Initialise messages to be vague
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }
+# In principle, it is possible to approximate outbound messages with Laplace Approximation
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }

Let us return to the coin toss model, but this time we want to print flowing messages:

@model function coin_toss_model_log(n)
+
+    y = datavar(Float64, n)
+
+    θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage("θ") }
+
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)  where { pipeline = LoggerPipelineStage("y[$i]") }
+    end
+    
+    return y, θ
+end
_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));
θ_subscription = subscribe!(getmarginal(θ), (value) -> println("New posterior marginal for θ: ", value));
[θ][Beta][out]: VariationalMessage()
coinflips = float.(rand(Bernoulli(0.5), 5));
update!(y, coinflips)
[y[1]][Bernoulli][p]: VariationalMessage()
+[y[2]][Bernoulli][p]: VariationalMessage()
+[y[3]][Bernoulli][p]: VariationalMessage()
+[y[4]][Bernoulli][p]: VariationalMessage()
+[y[5]][Bernoulli][p]: VariationalMessage()
+New posterior marginal for θ: Marginal(Beta{Float64}(α=3.0, β=11.0))
unsubscribe!(θ_subscription)
# Inference is lazy and does not send messages if no one is listening for them
+update!(y, coinflips)
diff --git a/dev/examples/advanced_examples/Assessing People Skills/index.html b/dev/examples/advanced_examples/Assessing People Skills/index.html new file mode 100644 index 000000000..99e49a137 --- /dev/null +++ b/dev/examples/advanced_examples/Assessing People Skills/index.html @@ -0,0 +1,49 @@ + +Assessing People’s Skills · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Assessing People’s Skills

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of "Model-Based Machine Learning" by Winn et al.

Problem Statement

We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?

We model the result for question $i$ as a continuous variable $r_i\in[0,1]$, and skill/attitude as a binary variable $s_i \in \{0, 1\}$, where $s_1$ represents whether the student has partied, and $s_2$ and $s_3$ represent whether the student has studied the chapters for the corresponding questions.

We assume the following logic:

  • If the student is alert (has not partied), then they will score on the first question;
  • If the student is alert or has studied chapter two, then they will score on question two;
  • If the student can answer question two and has studied chapter three, then they will score on question three.

Generative Model Definition

To model the probability for correct answers, we assume a latent state variable $t_i \in \{0,1\}$. The dependencies between the variables can then be modeled by the following Bayesian network:

(s_1)   (s_2)   (s_3)
+  |       |       |
+  v       v       v
+(t_1)-->(t_2)-->(t_3)
+  |       |       |
+  v       v       v
+(r_1)   (r_2)   (r_3)

As prior beliefs, we assume that a student is equally likely to study/party or not: $s_i \sim Ber(0.5)\,,$ for all $i$. Next, we model the domain logic as $\begin{aligned} t_1 &= ¬s_1\\ + t_2 &= t_1 ∨ s_2\\ + t_3 &= t_2 ∧ s_3\,. \end{aligned}$ For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as $t_i \sim Ber(s_i)\,,$ for all $i$.

Custom Nodes and Rules

The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.

In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.

using RxInfer, Random
+
+# Create Score node
+struct Score end
+
+@node Score Stochastic [out, in]

We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.

# Adding update rule for the Score node
+@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin     
+    return Bernoulli(mean(q_out))
+end

Generative Model Specification

We can now build the full generative model.

# GraphPPL.jl exports the `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function skill_model()
+    s = randomvar(3)
+    t = randomvar(3)
+    r = datavar(Float64, 3)
+
+    # Priors
+    for i=1:3
+        s[i] ~ Bernoulli(0.5)
+    end
+
+    # Domain logic
+    t[1] ~ ¬s[1]
+    t[2] ~ t[1] || s[2]
+    t[3] ~ t[2] && s[3]
+    
+    # Results
+    for i=1:3
+        r[i] ~ Score(t[i])
+    end
+end

Inference Specification

Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.

test_results = [0.1, 0.1, 0.1]
+inference_result = infer(
+    model = skill_model(),
+    data  = (r = test_results, )
+)
Inference results:
+  Posteriors       | available for (s, t)

Results

# Inspect the results
+map(params, inference_result.posteriors[:s])
3-element Vector{Tuple{Float64}}:
+ (0.9872448979591837,)
+ (0.06377551020408162,)
+ (0.4719387755102041,)

These results suggest that this particular student was very likely out on the town last night.

diff --git a/dev/examples/advanced_examples/Chance Constraints/index.html b/dev/examples/advanced_examples/Chance Constraints/index.html new file mode 100644 index 000000000..61c0abfb7 --- /dev/null +++ b/dev/examples/advanced_examples/Chance Constraints/index.html @@ -0,0 +1,166 @@ + +Chance-Constrained Active Inference · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Chance-Constrained Active Inference

This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, "Chance-constrained active inference") and discussion with John Boik.

We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. 

using Pkg; Pkg.activate(".."); Pkg.instantiate();
using Plots, Distributions, StatsFuns, RxInfer

Chance-Constraint Node Definition

A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not "overflow" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.

In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.

struct ChanceConstraint end  
+
+# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol
+@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]
# Function to compute normalizing constant and central moments of a truncated Gaussian distribution
+function truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)
+    V = clamp(V, tiny, huge)
+    StdG = Distributions.Normal(m, sqrt(V))
+    TrG = Distributions.Truncated(StdG, a, b)
+    
+    Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a)  # safe mass for standard Gaussian
+    
+    if Z < tiny
+        # Invalid region; return undefined mean and variance of truncated distribution
+        Z    = 0.0
+        m_tr = 0.0
+        V_tr = 0.0
+    else
+        m_tr = Distributions.mean(TrG)
+        V_tr = Distributions.var(TrG)
+    end
+    
+    return (Z, m_tr, V_tr)
+end;
@rule ChanceConstraint(:out, Marginalisation) (
+    m_out::UnivariateNormalDistributionsFamily, # Require inbound message
+    q_lo::PointMass, 
+    q_hi::PointMass, 
+    q_epsilon::PointMass, 
+    q_atol::PointMass) = begin 
+
+    # Extract parameters
+    lo = mean(q_lo)
+    hi = mean(q_hi)
+    epsilon = mean(q_epsilon)
+    atol = mean(q_atol)
+    
+    (m_bw, V_bw) = mean_var(m_out)
+    (xi_bw, W_bw) = (m_bw, 1. /V_bw)  # check division by  zero
+    (m_tilde, V_tilde) = (m_bw, V_bw)
+    
+    # Compute statistics (and normalizing constant) of q in safe region G
+    # Phi_G is called the "safe mass" 
+    (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)
+
+    xi_fw = xi_bw
+    W_fw  = W_bw
+    if epsilon <= 1.0 - Phi_G # If constraint is active
+        # Initialize statistics of uncorrected belief
+        m_tilde = m_bw
+        V_tilde = V_bw
+        for i = 1:100 # Iterate at most this many times
+            (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G
+            (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G
+
+            # Compute moments of non-G region as a mixture of left and right truncations
+            Phi_nG = Phi_lG + Phi_rG
+            m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG
+            V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2
+
+            # Compute moments of corrected belief as a mixture of G and non-G regions
+            m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG
+            V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2
+            # Re-compute statistics (and normalizing constant) of corrected belief
+            (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)
+            if (1.0 - Phi_G) < (1.0 + atol)*epsilon
+                break # Break the loop if the belief is sufficiently corrected
+            end
+        end
+        
+        # Convert moments of corrected belief to canonical form
+        W_tilde = inv(V_tilde)
+        xi_tilde = W_tilde * m_tilde
+
+        # Compute canonical parameters of forward message
+        xi_fw = xi_tilde - xi_bw
+        W_fw  = W_tilde - W_bw
+    end
+
+    return NormalWeightedMeanPrecision(xi_fw, W_fw)
+end

Definition of the Environment

We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.

wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile
+
+function initializeWorld()
+    x_0 = 0.0 # Initial elevation
+    
+    x_t_last = x_0
+    function execute(t::Int64, a_t::Float64)
+        x_t = x_t_last + a_t + wind(t) # Update elevation
+    
+        x_t_last = x_t # Reset state
+                
+        return x_t
+    end
+
+    x_t = x_0 # Predefine outcome variable
+    observe() = x_t # State is fully observed
+
+    return (execute, observe)
+end;

Generative Model for Regulator

We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.

@model function regulator_model(; T, lo, hi, epsilon, atol)
+    # Fully observed state
+    x_t = datavar(Float64)
+
+    # Control prior statistics
+    m_u = datavar(Float64, T)
+    v_u = datavar(Float64, T)    
+        
+    # Random variables
+    u = randomvar(T) # Control
+    x = randomvar(T) # Elevation
+    
+    # Loop over horizon
+    x_k_last = x_t
+    for k = 1:T
+        u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior
+        x[k] ~ x_k_last + u[k] # Transition model
+        x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state
+            pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency
+        x_k_last = x[k]
+    end
+    
+    return (u, x)
+end

Reactive Agent Definition

function initializeAgent()
+    # Set control prior statistics
+    m_u = zeros(T)
+    v_u = lambda^(-1)*ones(T)
+    
+    function compute(x_t::Float64)
+        model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)
+        data_t = (m_u = m_u, v_u = v_u, x_t = x_t)
+        
+        result = infer(
+            model = model_t, 
+            data = data_t,
+            iterations = n_its)
+
+        # Extract policy from inference results
+        pol = mode.(result.posteriors[:u][end])
+
+        return pol
+    end
+
+    pol = zeros(T) # Predefine policy variable
+    act() = pol[1]
+
+    return (compute, act)
+end;

Action-Perception Cycle

Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. 

# Simulation parameters
+N = 160 # Total simulation time
+T = 1 # Lookahead time horizon
+lambda = 1.0 # Control prior precision
+lo = 1.0 # Chance region lower bound
+hi = Inf # Chance region upper bound
+epsilon = 0.01 # Allowed chance violation
+atol = 0.01 # Convergence tolerance for chance constraints
+n_its = 10;  # Number of inference iterations
(execute, observe) = initializeWorld() # Let there be a world
+(compute, act) = initializeAgent() # Let there be an agent
+
+a = Vector{Float64}(undef, N) # Actions
+x = Vector{Float64}(undef, N) # States
+for t = 1:N
+    a[t] = act()
+           execute(t, a[t])
+    x[t] = observe()
+           compute(x[t])
+end

Results

Results show that the agent does not allow the wind to push it all the way to the ground.

p1 = plot(1:N, wind.(1:N), color="blue", label="Wind", ylabel="Velocity", lw=2)
+plot!(p1, 1:N, a, color="red", label="Control", lw=2)
+p2 = plot(1:N, x, color="black", lw=2, label="Agent", ylabel="Elevation")
+plot(p1, p2, layout=(2,1))

diff --git a/dev/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html b/dev/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html new file mode 100644 index 000000000..68b3cedf2 --- /dev/null +++ b/dev/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html @@ -0,0 +1,143 @@ + +Conjugate-Computational Variational Message Passing (CVI) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Conjugate-Computational Variational Message Passing (CVI)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions

In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.

This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.

An example: nonlinear dynamical system

A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position $z_t$ at time $t$. Instead they have access to the observed squared distance $y_t$ between the object and some reference point $s$. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:

# data generating process
+nr_observations = 50
+reference_point = 53
+hidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)
+measurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);
# plot hidden location and reference frame
+p1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label="hidden location")
+hline!([reference_point], linewidth=3, label="reference point")
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot measurements
+p2 = scatter(1:nr_observations, measurements, linewidth=3, label="measurements")
+xlabel!("time [sec]"), ylabel!("squared distance [cm2]")
+
+plot(p1, p2, size=(1200, 500))

The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model

\[\begin{aligned} + p(\tau) & = \Gamma(\tau \mid \alpha_{\tau}, \beta_{\tau}),\\ + p(\gamma) & = \Gamma(\gamma \mid \alpha_{\gamma}, \beta_{\gamma}),\\ + p(z_t \mid z_{t - 1}, \tau) & = \mathcal{N}(z_t \mid z_{t - 1} + 1, \tau^{-1}),\\ + p(y_t \mid z_t, \gamma) & = \mathcal{N}(y_t \mid (z_t - s)^2, \gamma^{-1}), +\end{aligned}\]

where the researchers put priors on the process and measurement noise parameters, $\tau$ and $\gamma$, respectively. They do this, because they do not know the accuracy of their devices.

The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:

function compute_squared_distance(z)
+    (z - reference_point)^2
+end;
@model function measurement_model(nr_observations)
+
+    # allocate random variables and observations
+    z = randomvar(nr_observations)
+    y = datavar(Float64, nr_observations)
+
+    # set priors on precision parameters
+    τ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    γ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    
+    # specify estimate of initial location
+    z[1] ~ Normal(mean = 0, precision = τ)
+    y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)
+
+    # loop over observations
+    for t in 2:nr_observations
+
+        # specify state transition model
+        z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)
+
+        # specify non-linear observation model
+        y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)
+        
+    end
+
+end

But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).

The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:

@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)
+    compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)
+end;

In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:

@meta function model_meta(...)
+    f() -> CVI(args...)
+end

See ?CVI for more information about the args....

In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.

In the above example, we will assume the following posterior factorization:

@constraints function measurement_constraints()
+    q(z, τ, γ) = q(z)q(τ)q(γ)
+end;

This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as 

@constraints function posterior_constraints() begin
+    q(z, γ) = q(z)q(γ) # CVI
+    q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node
+end

Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.

results = infer(
+    model = measurement_model(nr_observations),
+    data = (y = measurements,),
+    iterations = 5,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = measurement_constraints(),
+    meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),
+    initmessages = (z = NormalMeanVariance(0, 5),),
+    initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),
+)
Inference results:
+  Posteriors       | available for (z)
+  Free Energy:     | Real[1241.91, 429.933, 376.869, 365.774, 362.879]
# plot estimates for location
+p1 = plot(collect(1:nr_observations), hidden_location, label = "hidden location", legend=:topleft, linewidth=3, color = :red)
+plot!(map(mean, results.posteriors[:z]), label = "estimated location (±2σ)", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot Bethe free energy
+p2 = plot(results.free_energy, linewidth=3, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size = (1200, 500))

Requirements

There are several main requirements for the CVI procedure to satisfy:

  1. The out interface of the non-linearity must be independently factorized with respect to other variables in the model.
  2. The messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.

In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as

@model function model(...)
+    ...
+    y ~ f(x1, x2, ..., xN)
+    ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity
+    ... 
+end
+
+@constraints function constraints_meta() begin
+    q(y, z1, ..., zn) = q(y)q(z1,...,zM)
+    ...
+end;
+
+@meta function model_meta(...)
+    f() -> CVI(rng, nr_samples, nr_iterations, optimizer))
+end

Note that not all exponential family distributions are implemented.

Extensions

Using a custom optimizer

CVI only supports Optimisers optimizers out of the box.

Below an explanation on how to extend to it to a custom optimizer.

Suppose we have CustomDescent structure which we want to use inside CVI for optimization.

To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).

ReactiveMP.cvi_update! incapsulates the gradient step:

  1. opt is used to select your optimizer structure
  2. λ is the current value
  3. ∇ is a gradient value computed inside CVI.
struct CustomDescent 
+    learning_rate::Float64
+end
+
+# Must return an optimizer and its initial state
+function ReactiveMP.cvi_setup(opt::CustomDescent, q)
+     return (opt, nothing)
+end
+
+# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)
+function ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)
+    opt, _ = opt_and_state
+    λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))
+    copyto!(new_λ, λ̂)
+    return opt_and_state, new_λ
+end

Let's try to apply it to a model: $\begin{aligned} p(x) & = \mathcal{N}(0, 1),\\ + p(y_{i}\mid x) & = \mathcal{N}(y_i \mid x^2, 1),\\ +\end{aligned}$

Let's generate some synthetic data for the model

# generate data
+y = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)
+histogram(y)

Again we can create the corresponding model as:

# specify non-linearity
+f(x) = x ^ 2
+
+# specify model
+@model function normal_square_model(nr_observations)
+
+    # allocate observations
+    y = datavar(Float64, nr_observations)
+
+    # describe prior on latent state
+    x ~ NormalMeanPrecision(0, 100)
+
+    # transform latent state
+    mean ~ f(x)
+
+    # observation model
+    y .~ NormalMeanVariance(mean, 1)
+
+end
+
+# specify meta
+@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)
+    f() ->  CVI(rng, nr_samples, nr_iterations, optimizer)
+end
normal_square_meta (generic function with 1 method)

We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:

Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.

res = infer(
+    model = normal_square_model(1000),
+    data = (y = y,),
+    iterations = 10,
+    free_energy = true,
+    initmessages = (x = NormalMeanVariance(0, 100),),
+    meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))
+)
+
+mean(res.posteriors[:x][end])
-18.998075156688632

The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working!

Note: $x^2$ can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.

diff --git a/dev/examples/advanced_examples/GP Regression by SSM/index.html b/dev/examples/advanced_examples/GP Regression by SSM/index.html new file mode 100644 index 000000000..c1e071601 --- /dev/null +++ b/dev/examples/advanced_examples/GP Regression by SSM/index.html @@ -0,0 +1,99 @@ + +Solve GP regression by SDE · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Solve GP regression by SDE

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this notebook, we solve a GP regression problem by using "Stochastic Differential Equation" (SDE). This method is well described in the dissertation "Stochastic differential equation methods for spatio-temporal Gaussian process regression." by Arno Solin and "Sequential Inference for Latent Temporal Gaussian Process Models" by Jouni Hartikainen. The idea of the method is as follows.

Suppose a function $f(x)$ follows a zero-mean Gaussian Process $\begin{aligned} f(x) \sim \mathcal{GP}(0, k(x,x')). \end{aligned}$

When the dimensionality of $x$ is 1, we can consider $f(x)$ as a stochastic process over time, i.e. $f(t)$. For a certain classses of covariance functions, $f(t)$ is a solution to an $m$-th order linear stochastic differential equation (SDE) $\begin{aligned} a_0 f(t) + a_1 \frac{d f(t)}{dt} + \dots + a_m \frac{d^m f(t)}{dt^m} = w(t) \end{aligned}$

where $w(t)$ is a zero-mean white noise process with spectral density $Q_c$. If we define a vector-valued function $\mathbf{f}(t) = (f(t),\, d/dt f(t),\dots,\, d^{m-1}/dt^{m-1}f(t))$, then we can rewrite the above SDE under the companion form

\[\begin{aligned} +\frac{d \mathbf{f}(t)}{dt} = \mathbf{F}\, \mathbf{f}(t) + \mathbf{L} w(t) \quad (1) +\end{aligned}\]

where $\mathbf{F}$ and $\mathbf{L}$ are defined based on the choice of covariance functions. From (1), we have the following state-space model: $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \quad(2a) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}) \quad(2b). \\ +\end{aligned}$

where $\mathbf{A}_k = \exp{(\mathbf{F}\,\Delta t_k)}$, with $\Delta t_k = t_{k+1} - t_k$, is called the discrete-time state transition matrix, and $\mathbf{Q}_k$ the process noise covariance matrix. For the computation of $\mathbf{Q}_k$, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state $f_0 \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_0)$. For stationary covariance function, the SDE has a stationary state $f_\infty \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_\infty)$, where $\mathbf{P}_\infty$ is the solution to $\begin{aligned} \frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0 \quad (\mathrm{Lyapunov \, equation}). \end{aligned}$

With this stationary condition, the process noise covariance $\mathbf{Q}_k$ is computed as follows $\begin{aligned} \mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T \end{aligned}$

For one-dimensional problem the SDE representation of the GP is defined by the matrices $\mathbf{F}, \, \mathbf{L}, \, \mathbf{Q}_c, \, \mathbf{P}_0$ and $\mathbf{H}$. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.

using RxInfer, Random, Distributions, LinearAlgebra, Plots

Create state space model for GP regression

Here we create a state-space model $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}), \\ +\end{aligned}$ where $y_k$ is the noisy observation of the function $f$ at time $t_k$, and $\sigma^2_{noise}$ is the noise variance and assumed to be known.

@model function gp_regression(n, P∞, A, Q, H, σ²_noise)
+    f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)
+    f = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+    
+    f_prev = f_0
+
+    for i=1:n
+        f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])
+        y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)
+        f_prev = f[i]
+    end
+    return f, y
+end

Generate data

Random.seed!(10)
+n = 100
+σ²_noise = 0.04;
+t = collect(range(-2, 2, length=n)); #timeline
+f_true = sinc.(t); # true process
+f_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process
+
+pos = sort(randperm(75)[1:2:75]); 
+t_obser = t[pos]; # time where we observe data
+
+y_data = Array{Union{Float64,Missing}}(missing, n)
+for i in pos 
+    y_data[i] = f_noisy[i]
+end
+
+θ = [1., 1.]; # store [l, σ²]
+Δt = [t[1]]; # time difference
+append!(Δt, t[2:end] - t[1:end-1]);

Let's visualize our data

plot(t, f_true, label="True process f(t)")
+scatter!(t_obser, y_data[pos], label = "Noisy observations")
+xlabel!("t")
+ylabel!("f(t)")

Covariance function: Matern-3/2

The Matern is a stationary covariance function and defined as follows $\begin{aligned} k(\tau) = \sigma^2 \frac{2^{1-\nu}}{\Gamma(\nu)} \left(\frac{\sqrt{2\nu}\tau}{l} \right)^\nu K_\nu\left(\frac{\sqrt{2\nu}\tau}{l} \right) \end{aligned}$ where $\begin{aligned} \sigma^2: \text{the magnitude scale hyperparameter}\\ +l: \text{the characteristic length-scale}\\ +\nu: \text{the smoothness hyperparameter}\\ +K_\nu(.): \text{the modified Bessel function of the second kind}. \end{aligned}$ When we say the Matern-3/2, we mean $\nu=3/2$. The matrices for the state space model are computed as follows $\begin{aligned} \mathbf{F} = \begin{pmatrix} 0 & 1\\ +-\lambda^2 & -2\lambda \end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} 0 \\ 1 \end{pmatrix}, \quad \quad \mathbf{P}_\infty = \begin{pmatrix} \sigma^2 & 0 \\ 0 & \lambda^2\sigma^2 \end{pmatrix} ,\quad \quad \mathbf{H} = \begin{pmatrix} 1 & 0 \end{pmatrix}, \quad \quad Q_c = 4\lambda^3\sigma^2 \end{aligned}$ where $\lambda = \frac{\sqrt{3}}{l} $. From these matrices, we can define $\mathbf{A}_k$ and $\mathbf{Q}_k$.

λ = sqrt(3)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 1.];
+H = [1., 0.];
+F = [0. 1.; -λ^2 -2λ]
+P∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_32 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Covariance function: Matern-5/2

Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:

\[\begin{aligned} +\mathbf{F} = \begin{pmatrix} +0 & 1 & 0\\ +0 & 0 & 1 \\ +-\lambda^3 & -3\lambda^2 & -3\lambda +\end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} +0 \\ 0 \\ 1 +\end{pmatrix}, \quad \quad \mathbf{H} = \begin{pmatrix} +1 & 0 & 0 +\end{pmatrix}, \quad \quad Q_c = \frac{16}{3} \sigma^2 \lambda^5, +\end{aligned}\]

where $\lambda = \sqrt{5} / l$. To find $\mathbf{P}_\infty$, we solve the Lyapunov equation

\[\begin{aligned} +\frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0, +\end{aligned}\]

of which the solution is

\[\begin{aligned} +vec(\mathbf{P}_\infty) = (\mathbf{I} \otimes \mathbf{F} + \mathbf{F}\otimes\mathbf{I})^{-1}\, vec(-\mathbf{L}Q_c\mathbf{L}^T) +\end{aligned}\]

where $vec(.)$ is the vectorization operator and $\otimes$ denotes the Kronecker product. Now we can find $\mathbf{A}_k$ and $\mathbf{Q}_k$

\[\begin{aligned} +\mathbf{A}_k = \exp{(\mathbf{F}\Delta t_k)} +\end{aligned}\]

\[\begin{aligned} +\mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T +\end{aligned}\]

λ = sqrt(5)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 0., 1.];
+H = [1., 0., 0.];
+F = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]
+Qc = 16/3 * θ[2] * λ^5;
+
+I = diageye(3) ; 
+vec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); 
+P∞ = reshape(vec_P,3,3);
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_52 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Result

slicedim(dim) = (a) -> map(e -> e[dim], a)
+
+plot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M32", title = "Matern-3/2", legend =false, lw = 2)
+plot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M52",legend = :bottomleft, title = "GPRegression by SSM", lw = 2)
+plot!(t, f_true,label="true process", lw = 2)
+scatter!(t_obser, f_noisy[pos], label="Observations")
+xlabel!("t")
+ylabel!("f(t)")

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.

diff --git a/dev/examples/advanced_examples/Global Parameter Optimisation/index.html b/dev/examples/advanced_examples/Global Parameter Optimisation/index.html new file mode 100644 index 000000000..6a20914df --- /dev/null +++ b/dev/examples/advanced_examples/Global Parameter Optimisation/index.html @@ -0,0 +1,497 @@ + +Global Parameter Optimisation · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Global Parameter Optimisation

This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.

By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Univariate State Space Model

Let us try use the following simple state space model:

\[\begin{aligned} + {x}_t &= {x}_{t-1} + c \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, p \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Our goal is to optimize parameters $c$ and ${m_{{x}_0}}$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)
+    
+    x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n)
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ x_prev + c
+        y[i] ~ NormalMeanVariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+
+    return x, y
+end
rng = MersenneTwister(42)
+
+P      = 1.0
+n      = 250
+c_real = -5.0
+data   = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);
# c[1] is C
+# c[2] is μ0
+function f(c)
+    x0_prior = NormalMeanVariance(c[2], 100.0)
+    result = infer(
+        model = smoothing(n, x0_prior, c[1], P), 
+        data  = (y = data,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
using Optim
res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     3.651509e+02     1.001412e+03
+ * time: 0.023710012435913086
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     3.645772e+02
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.18e-06 ≰ 0.0e+00
+    |x - x'|/|x'|          = 2.30e-07 ≰ 0.0e+00
+    |f(x) - f(x')|         = 9.13e-07 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00
+    |g(x)|                 = 2.56e-06 ≤ 1.0e-03
+
+ * Work counters
+    Seconds run:   6  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    67
+    ∇f(x) calls:   67
res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)
2-element Vector{Float64}:
+  1.0007749243942134
+ -5.14368311177876
println("Real value vs Optimized")
+println("Real:      ", [ 1.0, c_real ])
+println("Optimized: ", res.minimizer)
Real value vs Optimized
+Real:      [1.0, -5.0]
+Optimized: [1.0007749243942134, -5.14368311177876]

Multivariate state space model

Let us consider the multivariate state space model:

\[\begin{aligned} + \mathbf{x}_t &\sim \mathcal{N}\left(\mathbf{Ax}_{t-1}, \mathbf{Q} \right) \\ + \mathbf{y}_t &\sim \mathcal{N}\left(\mathbf{x}_{t}, \mathbf{P} \right) +\end{aligned}\]

with prior

\[\begin{aligned} +\mathbf{x}_0 \sim \mathcal{N}(\mathbf{m_{{x}_0}}, \mathbf{V_{{x}_0}})\ +\end{aligned}\]

and transition matrix

\[\begin{aligned} +\mathbf{A} = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} +\end{aligned}\]

Covariance matrices $\mathbf{V_{{x}_0}}$, $\mathbf{P}$ and $\mathbf{Q}$ are known. Our goal is to optimize parameters $\mathbf{m_{{x}_0}}$ and $\theta$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)
+    
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    
+    x_prev = x_prior
+    
+    A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)
+        y[i] ~ MvNormalMeanCovariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+    
+end
# Generate data
+function generate_rotate_ssm_data()
+    rng = MersenneTwister(1234)
+
+    θ = π / 8
+    A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+    Q = Matrix(Diagonal(1.0 * ones(2)))
+    P = Matrix(Diagonal(1.0 * ones(2)))
+
+    n = 300
+
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(x[i], Q))
+        
+        x_prev = x[i]
+    end
+
+    return θ, A, Q, P, n, x, y
+end
generate_rotate_ssm_data (generic function with 1 method)
θ, A, Q, P, n, x, y = generate_rotate_ssm_data();
px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+
+plot(px, size = (1200, 450))

function f(θ)
+    x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))
+    result = infer(
+        model = rotate_ssm(n, θ[1], x0, Q, P), 
+        data  = (y = y,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     2.192003e+04     9.032537e+04
+ * time: 7.295608520507812e-5
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.161372e+03
+
+ * Found with
+    Algorithm:     L-BFGS
+
+ * Convergence measures
+    |x - x'|               = 5.09e-09 ≰ 0.0e+00
+    |x - x'|/|x'|          = 4.48e-10 ≰ 0.0e+00
+    |f(x) - f(x')|         = 0.00e+00 ≤ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14
+    |g(x)|                 = 5.63e-07 ≰ 1.0e-12
+
+ * Work counters
+    Seconds run:   20  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    58
+    ∇f(x) calls:   58
println("Real value vs Optimized")
+println("Real:      ", θ)
+println("Optimized: ", res.minimizer[1])
+
+@show sin(θ), sin(res.minimizer[1])
+@show cos(θ), cos(res.minimizer[1])
Real value vs Optimized
+Real:      0.39269908169872414
+Optimized: 0.3929332481380117
+(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)
+(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)
+(0.9238795325112867, 0.9237898955654058)
x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))
+
+result = infer(
+    model = rotate_ssm(n, res.minimizer[1], x0, Q, P), 
+    data  = (y = y,), 
+    free_energy = true
+)
+
+xmarginals = result.posteriors[:x]
+
+px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "inf₁")
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "inf₂")
+
+plot(px, size = (1200, 450))

Learning Kalman filter with LSTM driven dynamic

In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example.

Our objective is to compute the marginal posterior distribution of the latent (hidden) state $x_k$ at each time step $k$, considering the history of measurements up to that time step:

\[ +p(x_k | y_{1:k}). +$$ + +The above expression represents the probability distribution of the latent state $x_k$ given the measurements $y_{1:k}$ up to time step $k$. + +```julia +using RxInfer, BenchmarkTools, Flux, ReverseDiff, Random, Plots, LinearAlgebra, ProgressMeter, JLD, StableRNGs +``` + + + +### Generate data + +```julia +# Lorenz system equations to be used to generate dataset +Base.@kwdef mutable struct Lorenz + dt::Float64 + σ::Float64 + ρ::Float64 + β::Float64 + x::Float64 + y::Float64 + z::Float64 +end + +function step!(l::Lorenz) + dx = l.σ * (l.y - l.x); l.x += l.dt * dx + dy = l.x * (l.ρ - l.z) - l.y; l.y += l.dt * dy + dz = l.x * l.y - l.β * l.z; l.z += l.dt * dz +end +; +``` + + +```julia +# Dataset +rng = StableRNG(999) + +ordered_dataset = [] +ordered_parameters = [] +for σ = 11:15 + for ρ = 23:27 + for β_nom = 6:9 + attractor = Lorenz(0.02, σ, ρ, β_nom/3.0, 1, 1, 1) + noise_free_data = [[1.0, 1.0, 1.0]] + for i=1:99 + step!(attractor) + push!(noise_free_data, [attractor.x, attractor.y, attractor.z]) + end + push!(ordered_dataset, noise_free_data) + push!(ordered_parameters, [σ, ρ, β_nom/3.0]) + end + end +end + +new_order = collect(1:100) +shuffle!(rng,new_order) + +dataset = [] # noisy dataset +noise_free_dataset = [] # noise free dataset +lorenz_parameters = [] + +for i in new_order + local data = [] + push!(noise_free_dataset, ordered_dataset[i]) + push!(lorenz_parameters, ordered_parameters[i]) + for nfd in ordered_dataset[i] + push!(data,nfd+randn(rng,3)) + end + push!(dataset, data) +end + +trainset = dataset[1:60] +validset = dataset[61:80] +testset = dataset[81:end] + +noise_free_trainset = noise_free_dataset[1:60] +noise_free_validset = noise_free_dataset[61:80] +noise_free_testset = noise_free_dataset[81:end] +; +``` + + + +### Data visualization + +```julia +one_nonoise=noise_free_trainset[1] +one=trainset[1] +gx, gy, gz = zeros(100), zeros(100), zeros(100) +rx, ry, rz = zeros(100), zeros(100), zeros(100) +for i=1:100 + rx[i], ry[i], rz[i] = one[i][1], one[i][2], one[i][3] + gx[i], gy[i], gz[i] = one_nonoise[i][1], one_nonoise[i][2], one_nonoise[i][3] +end +p1=plot(rx,ry,label="Noise observations") +p1=plot!(gx,gy,label="True state") +xlabel!("x") +ylabel!("y") +p2=plot(rx,rz,label="Noise observations") +p2=plot!(gx,gz,label="True state") +xlabel!("x") +ylabel!("z") +p3=plot(ry,rz,label="Noise observations") +p3=plot!(gy,gz,label="True state") +xlabel!("y") +ylabel!("z") +plot(p1, p2, p3, size = (800, 200),layout=(1,3)) +``` + +![](../../assets/examples/Global Parameter Optimisation_22_1.png) + + +### Inference + + +We use the following state-space model representation: + +$$\begin{aligned} +x_k \sim p(x_k | x_{k-1}) \\ +y_k \sim p(y_k | x_k). +\end{aligned}\]

where $x_k \sim p(x_k | x_{k-1})$ represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system.

\[\begin{aligned} +A_{k-1}=NN(y_{k-1}) \\ +p(x_k | x_{k-1})=\mathcal{N}(x_k | A_{k-1}x_{k-1}, Q) \\ +p(y_k | x_k)=\mathcal{N}(y_k | Bx_k, R) +\end{aligned}\]

where $NN$ is the neural network. The input is the observation $y_{k-1}$, and output is the trasition matrix $A_{k-1}$. $B$ denote distortion or measurment matrix. $Q$ and $R$ are covariance matrices. Note that the hidden state $x_k$ comprises three coordinates, i.e. $x_k = (rx_k, ry_k, rz_k)$

By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.

# Neural Network model
+mutable struct NN
+    InputLayer
+    OutputLater
+    g
+    params
+    function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+        InputLayer = Dense(W1, b1, relu)
+        Lstm = LSTM(W2_1,W2_2,b2,s2_1)
+        OutputLayer = Dense(W3, b3)
+        g = Chain(InputLayer, OutputLayer);
+        new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))
+    end
+end

Model specification

Note that we treat the trasition matrix $A_{k-1}$ as time-varying.

#State Space Model
+@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior_mean = zeros(3)
+    x_prior_cov  = Matrix(Diagonal(ones(3)))
+    
+    x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)
+    y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }
+    
+    for i in 2:n
+        x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }
+        y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }
+    end
+    
+    return x, y
+end

We set distortion matrix $B$ and the covariance matrices $Q$ and $R$ as identity matrix.

Q = Matrix(Diagonal(ones(3)))*2
+B = Matrix(Diagonal(ones(3)))
+R = Matrix(Diagonal(ones(3)))
+;

We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix $A$ output by the neural network. And the $A$ is treated as a datavar in the inference function.

function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    n = length(data)
+    neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])
+    return As
+end
get_matrix_AS (generic function with 1 method)

The weights of neural network $NN$ are initialized as follows:

# Initial model parameters
+W1, b1 = randn(5, 3)./100, randn(5)./100
+W2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)
+W3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100
+;

Before network training, we show the inference results for the hidden states:

# Performance on an instance from the testset before training
+index = 1
+data=testset[index]
+n=length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300))

Training network

In this part, we use the Free Energy as the objective function to optimize the weights of network.

# free energy objective to be optimized during training
+function fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    fe_ = 0
+    for train_instance in trainset
+        result = infer(
+            model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+            data  = (y = train_instance, ), 
+            returnvars = (x = KeepLast(), ),
+            free_energy = true
+        )
+        fe_ += result.free_energy[end]
+    end
+    return fe_
+end
fe_tot_est (generic function with 1 method)

Training

# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights
+# Uncomment the following code to train the network manually
+# opt = Flux.Optimise.RMSProp(0.006, 0.95)
+# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+# @showprogress for epoch in 1:800
+#     grads = ReverseDiff.gradient(fe_tot_est, params);
+#     for i=1:length(params)
+#         Flux.Optimise.update!(opt,params[i],grads[i])
+#     end
+# end

Test

Import the weights of neural network that we have trained.

W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load("../data/nn_prediction/weights.jld")["data"];
# Performance on an instance from the testset after training
+index = 1
+data = testset[index]
+n = length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+
+gx, gy, gz = zeros(100), zeros(100), zeros(100)
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+plot(p1, p2, p3, size = (1000, 300))

Prediction

In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill $k$ and estimate the future state at time $k+1$, $k+2$, $\dots$,$k+T$.

We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.

\[\begin{aligned} +A_{k}=NN(x_{k}) \\ +p(x_{k+1} | x_{k})=\mathcal{N}(x_{k+1} | A_{k}x_{k}, Q) \\ +\end{aligned}\]

#Define the prediction function
+multiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))
+sumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)
+
+function runForward(A,B,Q,R,mh_old,Vh_old)
+    mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)
+    mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)
+end
+
+function g_predict(mh_old,Vh_old,Q)
+    neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)
+    # Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])
+    As = As[1]
+    return runForward(As,B,Q,R,mh_old,Vh_old), As
+end
g_predict (generic function with 1 method)

After $k=75$, the observations are not available, and we predict the future state from $k=76$ to the end

tt = 75
+mh = mean(x_est[tt])
+Vh = cov(x_est[tt])
+mo_list, Vo_list, A_list = [], [], [] 
+inv_Q = inv(Q)
+for t=1:100-tt
+    (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)
+    push!(mo_list, mo)
+    push!(Vo_list, Vh)
+    push!(A_list, A_t)
+    global mh = mo
+    global Vh = Vo
+end
# Prediction visualization
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+for i=1:tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+for i=tt+1:100
+    ii=i-tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]
+end
+p1 = plot(rx,label="Ground truth rx")
+p1 = plot!(rx_est_m,label="Inffered state rx",ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Ground truth ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index][1:tt], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Ground truth rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)

diff --git a/dev/examples/advanced_examples/Infinite Data Stream/index.html b/dev/examples/advanced_examples/Infinite Data Stream/index.html new file mode 100644 index 000000000..beb18a5cd --- /dev/null +++ b/dev/examples/advanced_examples/Infinite Data Stream/index.html @@ -0,0 +1,169 @@ + +Infinite Data Stream · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Infinite Data Stream

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:

using RxInfer, Plots, Random, StableRNGs

For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:

mutable struct Environment
+    rng                   :: AbstractRNG
+    current_state         :: Float64
+    observation_precision :: Float64
+    history               :: Vector{Float64}
+    observations          :: Vector{Float64}
+    
+    Environment(current_state, observation_precision; seed = 123) = begin 
+         return new(StableRNG(seed), current_state, observation_precision, [], [])
+    end
+end
+
+function getnext!(environment::Environment)
+    environment.current_state = environment.current_state + 1.0
+    nextstate  = 10sin(0.1 * environment.current_state)
+    observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))
+    push!(environment.history, nextstate)
+    push!(environment.observations, observation)
+    return observation
+end
+
+function gethistory(environment::Environment)
+    return environment.history
+end
+
+function getobservations(environment::Environment)
+    return environment.observations
+end
getobservations (generic function with 1 method)

Model specification

We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:

@model function kalman_filter()
+    
+    # Prior for the previous state
+    x_prev_mean = datavar(Float64)
+    x_prev_var  = datavar(Float64)
+    
+    x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)
+    
+    # Prior for the observation noise
+    τ_shape = datavar(Float64)
+    τ_rate  = datavar(Float64)
+    
+    τ ~ Gamma(shape = τ_shape, rate = τ_rate)
+    
+    # Random walk with fixed precision
+    x_current ~ Normal(mean = x_prev, precision = 1.0)
+    
+    # Noisy observation
+    y = datavar(Float64)
+    y ~ Normal(mean = x_current, precision = τ)
+    
+end
+
+# We assume the following factorisation between variables 
+# in the variational distribution
+@constraints function filter_constraints()
+    q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)
+end
filter_constraints (generic function with 1 method)

Prepare environment

initial_state         = 0.0
+observation_precision = 0.1
0.1

After we have created the environment we can observe how our signal behaves:

testenvironment = Environment(initial_state, observation_precision);
+
+animation = @animate for i in 1:100
+    getnext!(testenvironment)
+    
+    history = gethistory(testenvironment)
+    observations = getobservations(testenvironment)
+    
+    p = plot(size = (1000, 300))
+    
+    p = plot!(p, 1:i, history[1:i], label = "Hidden signal")
+    p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = "Observation")
+end
+
+gif(animation, "../pics/infinite-data-stream.gif", fps = 24, show_msg = false);

Filtering on static dataset

RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:

n                  = 300
+static_environment = Environment(initial_state, observation_precision);
+
+for i in 1:n
+    getnext!(static_environment)
+end
+
+static_history      = gethistory(static_environment)
+static_observations = getobservations(static_environment);
+static_datastream   = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
function run_static(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        keephistory   = 10_000,
+        historyvars   = (x_current = KeepLast(), τ = KeepLast()),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        free_energy   = true,
+        autostart     = true,
+    )
+    
+    return engine
+end
run_static (generic function with 1 method)
result = run_static(static_environment, static_datastream);
static_inference = @animate for i in 1:n
+    estimated = result.history[:x_current]
+    p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = "Estimation")
+    p = plot!(static_history[1:i], label = "Real states")    
+    p = scatter!(static_observations[1:i], ms = 2, label = "Observations")
+    p = plot(p, size = (1000, 300), legend = :bottomright)
+end
+
+gif(static_inference, "../pics/infinite-data-stream-inference.gif", fps = 24, show_msg = false);

plot(result.free_energy_history, label = "Bethe Free Energy (averaged)")

Filtering on realtime dataset

Next lets create a "real" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:

function run_and_plot(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    posteriors = []
+    
+    plotfn = (q_current) -> begin 
+        IJulia.clear_output(true)
+        
+        push!(posteriors, q_current)
+
+        p = plot(mean.(posteriors), ribbon = var.(posteriors), label = "Estimation")
+        p = plot!(gethistory(environment), label = "Real states")    
+        p = scatter!(getobservations(environment), ms = 2, label = "Observations")
+        p = plot(p, size = (1000, 300), legend = :bottomright)
+
+        display(p)
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        autostart     = false,
+    )
+    
+    qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)
+    
+    RxInfer.start(engine)
+    
+    return engine
+end
run_and_plot (generic function with 1 method)
# This example runs in our documentation pipeline, which does not support "real-time" execution context
+# We skip this code if run not in Jupyter notebook (see below an example with gif)
+engine = nothing 
+if isdefined(Main, :IJulia)
+    timegen      = 41 # 41 ms
+    environment  = Environment(initial_state, observation_precision);
+    observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations
+    datastream   = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
+    engine = run_and_plot(environment, datastream)
+end;

The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:

if !isnothing(engine) && isdefined(Main, :IJulia)
+    RxInfer.stop(engine)
+    IJulia.clear_output(true)
+end;
diff --git a/dev/examples/advanced_examples/Nonlinear Sensor Fusion/index.html b/dev/examples/advanced_examples/Nonlinear Sensor Fusion/index.html new file mode 100644 index 000000000..7e9c99dea --- /dev/null +++ b/dev/examples/advanced_examples/Nonlinear Sensor Fusion/index.html @@ -0,0 +1,140 @@ + +Nonlinear Sensor Fusion · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Nonlinear Sensor Fusion

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers
+using DataFrames, DelimitedFiles, StableRNGs

In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.

A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.

To illustrate these noisy measurements, the engineers decided to plot them:

# fetch measurements
+beacon_locations = readdlm("../data/sensor_fusion/beacons.txt")
+distances = readdlm("../data/sensor_fusion/distances.txt")
+position = readdlm("../data/sensor_fusion/position.txt")
+nr_observations = size(distances, 1);
# plot beacon and actual location of WALL-E
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+xlabel!("longitude [m]"), ylabel!("latitude [m]")
+
+# plot noisy distance measurements
+p2 = plot(distances, legend=:topleft, linewidth=3, label=["distance to beacon 1" "distance to beacon 2" "distance to beacon 3"])
+xlabel!("time [sec]"), ylabel!("distance [m]")
+
+plot(p1, p2, size=(1200, 500))

In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time $t$, denoted by $z_t$, follows a 2-dimensional normal random walk:

\[\begin{aligned} + & p(z_t \mid z_{t - 1}) = \mathcal{N}(z_t \mid z_{t-1},~\mathrm{I}_{2}),\\ +\end{aligned}\]

where $\mathrm{I}_2$ denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements $y_t$ as a noisy set of the distances between WALL-E and the beacons, specified by $s_i$:

\[\begin{aligned} + & p(y_t \mid z_t) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~\mathrm{I}_{3}\! \right . \right)\!. +\end{aligned}\]

The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:

# function to compute distance to beacons
+function compute_distances(z)    
+    distance1 = norm(z - beacon_locations[1,:])
+    distance2 = norm(z - beacon_locations[2,:])
+    distance3 = norm(z - beacon_locations[3,:])
+    distances = [distance1, distance2, distance3]
+end;
@model function random_walk_model(nr_observations)
+    
+    # specify precision matrices
+    W = diageye(2)
+    R = diageye(3)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], W)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;

Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.

Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:

    compute_distances(z) -> CVI(..., Val(false), ...)

This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.

@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)
+    compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)
+end;

NOTE: You can try out different meta for approximating the nonlinearity, e.g.

@meta function random_walk_linear_meta()
+    compute_distances(z) -> Linearization()
+end;
@meta function random_walk_unscented_meta()
+    compute_distances(z) -> Unscented()
+end;
results_fast = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),
+);
results_accuracy = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1000, 100, StableRNG(42)),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),
+);

After running this fast inference procedure, the engineers plot the results and evaluate the performance:

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_fast.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Fast (1 sample, 3 iterations)"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot beacon and actual and estimated location of WALL-E (accurate inference)
+p2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_accuracy.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Accurate (1000 samples, 100 iterations)"); p2.series_list[end][:label] = "estimated location ±2σ"
+
+plot(p1, p2, size=(1200, 500))

The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, $Q$ and $R$ respectively. They did this by adding Wishart priors to those matrices:

\[\begin{aligned} + & p(Q) = \mathcal{W}(Q \mid 3, \mathrm{I}_2), \\ + & p(R) = \mathcal{W}(R \mid 4, \mathrm{I}_3), \\ + & p(z_t \mid z_{t - 1}, Q) = \mathcal{N}(z_t \mid z_{t-1}, Q^{-1}),\\ + & p(y_t \mid z_t, R) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~R^{-1}\! \right . \right)\!. +\end{aligned}\]

@model function random_walk_model_wishart(nr_observations)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # set priors on precision matrices
+    Q ~ Wishart(3, diageye(2))
+    R ~ Wishart(4, diageye(3))
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], Q)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;
meta = @meta begin 
+    compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)
+end;

Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:

constraints = @constraints begin
+    q(z, Q, R) = q(z)q(Q)q(R)
+end;

The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.

results_wishart = infer(
+    model = random_walk_model_wishart(nr_observations),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = constraints,
+    meta = meta,
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),
+    initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))
+);

They plot the new estimates and the performance over time, and luckily WALL-E is found!

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_wishart.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot bethe free energy performance
+p2 = plot(results_wishart.free_energy, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size=(1200, 500))

diff --git a/dev/examples/advanced_examples/overview/index.html b/dev/examples/advanced_examples/overview/index.html new file mode 100644 index 000000000..490a6f731 --- /dev/null +++ b/dev/examples/advanced_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Advanced examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Advanced examples contain more complex inference problems.

  • Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.
  • Advanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.
  • Assessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.
  • Chance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.
  • Conjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.
  • Global Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.
  • Solve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.
  • Infinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.
  • Nonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors
diff --git a/dev/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html b/dev/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html new file mode 100644 index 000000000..c9771c06e --- /dev/null +++ b/dev/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html @@ -0,0 +1,550 @@ + +Bayesian Linear Regression Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Bayesian Linear Regression Tutorial

This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM

Part 1. Bayesian Linear Regression

John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

He records the speed and fuel consumption for the urban road which is the xdata and ydata.

function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = infer(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (a, b)
+  Free Energy:     | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184
+.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821
+, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]

He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a\mid y)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0,Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b)", c=1, legend = :topleft)
+prb = vline!(prb, [ 25 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b\mid y)", c=2, legend = :topleft)
+psb = vline!(psb, [ 25 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

a = results.posteriors[:a]
+b = results.posteriors[:b]
+
+println("Real a: ", 0.5, " | Estimated a: ", mean_var(a), " | Error: ", abs(mean(a) - 0.5))
+println("Real b: ", 25.0, " | Estimated b: ", mean_var(b), " | Error: ", abs(mean(b) - 25.0))
Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err
+or: 0.001490188462705988
+Real b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error
+: 0.18735789804394898

Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:

# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Univariate regression with unknown noise

Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. $\begin{aligned} p(y_n \mid a, b, s) &= \mathcal{N}(y_n \mid ax_n + b, s)\\ +p(s) &= \mathcal{IG}(s\mid\alpha, \theta)\\ +p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ +p(b) &= \mathcal{N}(b \mid m_b, v_b) \end{aligned}$

@model function linear_regression_unknown_noise(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    s ~ InverseGamma(1.0, 1.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = s)
+end
x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)
+
+scatter(x_data_un, y_data_un, title = "Dateset with unknown noise (mountain road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results_unknown_noise = infer(
+    model           = linear_regression_unknown_noise(length(x_data_un)), 
+    data            = (y = y_data_un, x = x_data_un), 
+    initmessages    = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars      = (a = KeepLast(), b = KeepLast(), s = KeepLast()), 
+    iterations      = 20,
+    constraints     = MeanField(),
+    initmarginals   = (s = vague(InverseGamma), ),
+    free_energy     = true
+)
Inference results:
+  Posteriors       | available for (a, b, s)
+  Free Energy:     | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125
+.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56
+, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]

Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:

plot(results_unknown_noise.free_energy, title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Below he visualizes the obtained posterior distributions for parameters:

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(a)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0, Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(b)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 25.0 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(b)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 25.0 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L"Prior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(s)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 200 ], label=L"True $s$", c = 3)
+psb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L"Posterior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(s)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 200 ], label=L"True $s$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$s$", ylabel=L"$p(s)$", ylims=[0, Inf])

He sees that in the presence of more noise the inference result is more uncertain about the actual values for $a$ and $b$ parameters.

John samples $a$ and $b$ and plot many possible regression lines on the same plot:

as = rand(results_unknown_noise.posteriors[:a], 100)
+bs = rand(results_unknown_noise.posteriors[:b], 100)
+p = scatter(x_data_un, y_data_un, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)
+end
+
+plot(p, size = (900, 400))

From this plot John can see that many lines do fit the data well and there is no definite "best" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.

Multivariate linear regression

In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.

@model function linear_regression_multivariate(dim, nr_samples)
+    a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))
+    b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))
+    W ~ InverseWishart(dim + 2, 100 * diageye(dim))
+
+    # Here is a small trick to make the example work
+    # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`
+    x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)
+    y = datavar(Vector{Float64}, nr_samples)
+    z = randomvar(nr_samples)
+
+    z .~ x .* a .+ b
+    y .~ MvNormal(mean = z, covariance = W)
+
+end

After received all the measurement records, he plots the measurements and performance index:

dim_mv = 6
+nr_samples_mv = 50
+rng_mv = StableRNG(42)
+a_mv = randn(rng_mv, dim_mv)
+b_mv = 10 * randn(rng_mv, dim_mv)
+v_mv = 100 * rand(rng_mv, dim_mv)
+
+x_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));
p = plot(title = "Multivariate linear regression", legend = :topleft)
+
+plt = palette(:tab10)
+
+data_set_label = [""]
+
+for k in 1:dim_mv
+    global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = "Measurement #$k", ms = 2, color = plt[k])
+end
+xlabel!(L"$x$")
+ylabel!(L"$y$")
+p

Before this data can be used to perform inference, John needs to change its format slightly.

x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)
+y_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);
results_mv = infer(
+    model           = linear_regression_multivariate(dim_mv, nr_samples_mv),
+    data            = (y = y_data_mv_processed, x = x_data_mv_processed),
+    initmarginals   = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),
+    initmessages    = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),
+    returnvars      = (a = KeepLast(), b = KeepLast(), W = KeepLast()),
+    free_energy     = true,
+    iterations      = 50,
+    constraints     = MeanField()
+)
Inference results:
+  Posteriors       | available for (a, b, W)
+  Free Energy:     | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7
+22, 712.341, 700.865, 690.782, 682.505  …  664.434, 664.434, 664.434, 664.4
+34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]

Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.

p = plot(title = "Multivariate linear regression", legend = :topleft, xlabel=L"$x$", ylabel=L"$y$")
+
+# how many lines to plot
+r = 50
+
+i_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))
+i_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))
+
+plt = palette(:tab10)
+
+for k in 1:dim_mv
+    x_mv_k = x_data_mv[k]
+    y_mv_k = y_data_mv[k]
+
+    for i in 1:r
+        global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])
+    end
+
+    global p = scatter!(p, x_mv_k, y_mv_k, label = "Measurement #$k", ms = 2, color = plt[k])
+end
+
+# truncate the init step
+f = plot(results_mv.free_energy[2:end], title ="Bethe free energy convergence", label = nothing, xlabel = "Iteration", ylabel = "Bethe free energy [nats]") 
+
+plot(p, f, size = (1000, 400))

He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.

i_a_mv = results_mv.posteriors[:a]
+
+ps_a = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $a_{%$k}$", xlabel=L"$a_{%$k}$", ylabel=L"$p(a_{%$k})$", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])
+
+    local m_a_mv_k = mean(i_a_mv)[k]
+    local v_a_mv_k = std(i_a_mv)[k, k]
+    
+    _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(a_{%$k})$", c=2,)
+    _p = vline!(_p, [ a_mv[k] ], label=L"True $a_{%$k}$", c = 3)
+           
+    push!(ps_a, _p)
+end
+
+plot(ps_a...)

i_b_mv = results_mv.posteriors[:b]
+
+ps_b = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $b_{%$k}$", xlabel=L"$b_{%$k}$", ylabel=L"$p(b_{%$k})$", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])
+    local m_b_mv_k = mean(i_b_mv)[k]
+    local v_b_mv_k = std(i_b_mv)[k, k]
+
+    _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(b_{%$k})$", c=2,)
+    _p = vline!(_p, [ b_mv[k] ], label=L"Real $b_{%$k}$", c = 3)
+           
+    push!(ps_b, _p)
+end
+
+plot(ps_b...)

He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.

scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L"True $s_d$")
+scatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L"$\mathrm{E}[s_d] \pm \sigma$")
+plot!(; xlabel=L"Dimension $d$", ylabel="Variance", title="Estimated variance of the noise")

Part 2. Hierarchical Bayesian Linear Regression

Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro.

The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.

Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].

The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.

# https://www.machinelearningplus.com/linear-regression-in-julia/
+# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb

Understanding the Task

Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.

In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).

Now, let's explore the data and delve deeper into the problem involved.

dataset = CSV.read("../data/hbr/osic_pulmonary_fibrosis.csv", DataFrame);
describe(dataset)
7×7 DataFrame
+ Row │ variable       mean     min                        median   max     
+    ⋯
+     │ Symbol         Union…   Any                        Union…   Any     
+    ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ Patient                 ID00007637202177411956430           ID004266
+372 ⋯
+   2 │ Weeks          31.8618  -5                         28.0     133
+   3 │ FVC            2690.48  827                        2641.0   6399
+   4 │ Percent        77.6727  28.8776                    75.6769  153.145
+   5 │ Age            67.1885  49                         68.0     88      
+    ⋯
+   6 │ Sex                     Female                              Male
+   7 │ SmokingStatus           Currently smokes                    Never sm
+oke
+                                                               3 columns om
+itted
first(dataset, 5)
5×7 DataFrame
+ Row │ Patient                    Weeks  FVC    Percent  Age    Sex      Sm
+oki ⋯
+     │ String31                   Int64  Int64  Float64  Int64  String7  St
+rin ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ ID00007637202177411956430     -4   2315  58.2536     79  Male     Ex
+-sm ⋯
+   2 │ ID00007637202177411956430      5   2214  55.7121     79  Male     Ex
+-sm
+   3 │ ID00007637202177411956430      7   2061  51.8621     79  Male     Ex
+-sm
+   4 │ ID00007637202177411956430      9   2144  53.9507     79  Male     Ex
+-sm
+   5 │ ID00007637202177411956430     11   2069  52.0634     79  Male     Ex
+-sm ⋯
+                                                                1 column om
+itted

The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.

Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:

patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)
patientinfo (generic function with 1 method)
function patientchart(dataset, patient_id; line_kws = true)
+    info = patientinfo(dataset, patient_id)
+    x = info[!, "Weeks"]
+    y = info[!, "FVC"]
+
+    p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)
+    p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = "Weeks", ylabel = "FVC")
+    
+    if line_kws
+        # Use the `GLM.jl` package to estimate linear regression
+        linearFormulae = @formula(FVC ~ Weeks)
+        linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))
+        linearPredicted = predict(linearRegressor)
+        p = plot!(p, x, linearPredicted, color = :red, lw = 3)
+    end
+
+    return p
+end
patientchart (generic function with 1 method)
p1 = patientchart(dataset, "ID00007637202177411956430")
+p2 = patientchart(dataset, "ID00009637202177434476278")
+p3 = patientchart(dataset, "ID00010637202177584971671")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.

Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:

The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].

Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling

In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the "pooled model." On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the "unpooled model," where each patient has completely separate regression lines.

In this analysis, we will adopt a middle ground approach known as "Partial pooling." Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:

Mathematically, the model is described by the following equations:

\[\begin{equation} + \begin{aligned} + \mu_\alpha &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 250000.0) \\ + \sigma_\alpha &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mu_\beta &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 9.0) \\ + \sigma_\beta &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 1.36) \\ + \alpha_i &\sim \mathcal{N}(\mathrm{mean} = \mu_\alpha, \mathrm{precision} = \sigma_\alpha) \\ + \beta &\sim \mathcal{N}(\mathrm{mean} = \mu_\beta, \mathrm{precision} = \sigma_\beta) \\ + \sigma &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mathrm{FVC}_{ij} &\sim \mathcal{N}(\mathrm{mean} = \alpha_i + t \beta_i, \mathrm{precision} = \sigma) + \end{aligned} +\end{equation}\]

where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!

Implementing this model in RxInfer is pretty straightforward:

@model function partially_pooled(patient_codes, weeks)
+    μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β ~ Normal(mean = 0.0, var = 9.0)      # Prior for the mean of β (slope)
+    σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)
+    σ_β ~ Gamma(shape = 1.75, scale = 1.36)  # Prior for the precision of β (slope)
+
+    n_codes = length(patient_codes)            # Total number of data points
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    α = randomvar(n_patients)                # Individual intercepts for each patient
+    β = randomvar(n_patients)                # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution
+        β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54)   # Prior for the standard deviation of the error term
+    
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes) # Observed FVC measurements
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+end

Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.

@constraints function partially_pooled_constraints()
+    # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent
+    q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)
+    # Assume that `μ_α`, `σ_α`, `α` are jointly independent
+    q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)
+    # Assume that `μ_β`, `σ_β`, `β` are jointly independent
+    q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)
+    # Assume that `FVC_est`, `σ` are jointly independent
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_constraints (generic function with 1 method)

These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!

Inference in the model

A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.

Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.

patient_ids          = dataset[!, "Patient"] # get the column of all patients
+patient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));
+patient_code_column  = map(patient -> patient_code_encoder[patient], patient_ids)
+
+dataset[!, :PatientCode] = patient_code_column
+
+first(patient_code_encoder, 5)
5-element Vector{Pair{InlineStrings.String31, Int64}}:
+ "ID00197637202246865691526" => 85
+ "ID00388637202301028491611" => 160
+ "ID00341637202287410878488" => 142
+ "ID00020637202178344345685" => 9
+ "ID00305637202281772703145" => 127
function partially_pooled_inference(dataset)
+
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+
+    results = infer(
+        model = partially_pooled(patient_codes, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+            σ = vague(Gamma),
+            σ_α = vague(Gamma),
+            σ_β = vague(Gamma),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100
+    )
+    
+end
partially_pooled_inference (generic function with 1 method)

We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.

In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. 

partially_pooled_inference_results = partially_pooled_inference(dataset)
Inference results:
+  Posteriors       | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)

Checking the model

Inspecting the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)
+    local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))
+end

Looks like our model learned personalized alphas and betas for each patient!

Visualizing FVC decline curves for some patients

Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.

function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)
+    info            = patientinfo(dataset, patient_id)
+    patient_code_id = encoder[patient_id]
+
+    patient_α = results.posteriors[:α][patient_code_id]
+    patient_β = results.posteriors[:β][patient_code_id]
+
+    estimated_σ = inv(mean(results.posteriors[:σ]))
+    
+    predict_weeks = range(-12, 134)
+
+    predicted = map(predict_weeks) do week
+        pm = mean(patient_α) + mean(patient_β) * week
+        pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ
+        return pm, sqrt(pv)
+    end
+    
+    p = patientchart(dataset, patient_id; kwargs...)
+    
+    return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)
+end
patientchart_bayesian (generic function with 1 method)
p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430")
+p2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278")
+p3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

The results match our expectations perfectly! Let's highlight the observations:

  • The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.

  • The model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.

  • Additionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.

Computing the modified Laplace Log Likelihood and RMSE

As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.

To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:

\[\begin{equation} + \begin{aligned} + \sigma_{\mathrm{clipped}} &= \max(\sigma, 70) \\ + \delta &= \min(\vert \mathrm{FVC}_{\mathrm{true}} - \mathrm{FVC}_{\mathrm{pred}}\vert, 1000) \\ + \mathrm{metric} &= -\frac{\sqrt{2}\delta}{\sigma_{\mathrm{clipped}}} - \mathrm{ln}(\sqrt{2}\sigma_{\mathrm{clipped}}) \\ + \end{aligned} +\end{equation}\]

To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.

function FVC_predict(results)
+    return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s
+        return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)
+    end
+end
FVC_predict (generic function with 1 method)
function compute_rmse(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    return mean((dataset[!, "FVC"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)
+end
+
+function compute_laplace_log_likelihood(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    sigma_c = std.(FVC_predicted)
+    sigma_c[sigma_c .< 70] .= 70
+    delta = abs.(mean.(FVC_predicted) .- dataset[!, "FVC"])
+    delta[delta .> 1000] .= 1000
+    return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))
+end
compute_laplace_log_likelihood (generic function with 1 method)
println("RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))")
RMSE: 124.0313266260767
+Laplace Log Likelihood: -6.15689374755478

What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!

Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.

Add layer to model hierarchy: Smoking Status

We can enhance the model by incorporating the column "SmokingStatus" as a pooling level, where model parameters will be partially pooled within the groups "Never smoked," "Ex-smoker," and "Currently smokes." To achieve this, we need to:

Encode the "SmokingStatus" column. Map the patient encoding to the corresponding "SmokingStatus" encodings. Refine and retrain the model with the additional hierarchical structure.

combine(groupby(dataset, "SmokingStatus"), nrow)
3×2 DataFrame
+ Row │ SmokingStatus     nrow
+     │ String31          Int64
+─────┼─────────────────────────
+   1 │ Ex-smoker          1038
+   2 │ Never smoked        429
+   3 │ Currently smokes     82
smoking_id_mapping   = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, "SmokingStatus"]))))
+smoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id
+    smoking_status = first(unique(patientinfo(dataset, patient_id)[!, "SmokingStatus"]))
+    return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]
+end)
+
+smoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));
@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)
+    μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)
+    σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+    σ_β_global ~ Gamma(shape = 1.75, scale = 1.36)  # Corresponds to half-normal with scale 3.0
+
+    n_codes = length(patient_codes) # Total number of data points
+    n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern
+    μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern
+    
+    for i in 1:n_smoking_statuses
+        μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)
+        μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)
+    end
+    
+    α = randomvar(n_patients) # Individual intercepts for each patient
+    β = randomvar(n_patients) # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)
+        β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes)
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+    
+end
+
+@constraints function partially_pooled_with_smooking_constraints()
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)
+    q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)
+    q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)
+    q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_with_smooking_constraints (generic function with 1 method)
function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+    
+    return infer(
+        model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_with_smooking_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            σ = Gamma(1.75, 45.54),
+            σ_α_global = Gamma(1.75, 45.54),
+            σ_β_global = Gamma(1.75, 1.36),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100,
+    )
+end
partially_pooled_with_smoking (generic function with 2 methods)
partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);

Inspect the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)
+    local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)
+    local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])
+    local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α_global)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β_global)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    local p5 = plot(title = "q(μ_α_smoking_status)...", legend = false)
+    local p6 = plot(title = "q(μ_β_smoking_status)...", legend = false)
+    
+    foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) 
+    foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)
+    
+    plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))
+end

Interpret smoking status model parameters

The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.

smoking_id_mapping
Dict{InlineStrings.String31, Int64} with 3 entries:
+  "Currently smokes" => 3
+  "Ex-smoker"        => 1
+  "Never smoked"     => 2
posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]
+
+println("Trend for")
+foreach(pairs(smoking_id_mapping)) do (key, id)
+    println("  $key: $(mean(posteriors_μ_β_smoking_status[id]))")
+end
Trend for
+  Currently smokes: 1.8157457671008241
+  Ex-smoker: -4.56516461765951
+  Never smoked: -4.446729680170274

Let's look at these curves for individual patients to help interpret these model results.

# Never smoked
+p1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430") 
+# Ex-smoker
+p2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278") 
+# Currently smokes
+p3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184") 
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

Review patients that currently smoke

When plotting each patient with the smoking status "Currently smokes," we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.

Depending on the purpose of the model, we can proceed in different ways:

  • If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.

  • However, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the "Currently smokes" group's parameters closer to the global parameters, or even consider merging the group with "Ex-smokers." Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.

let 
+    local plots = []
+
+    for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==("Currently smokes"), dataset)[!, "Patient"]))
+        push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))
+    end
+
+    plot(plots..., size = (1200, 1200))
+end

Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level

We calculate the metrics for the updated model and compare to the original model.

println("RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))")
RMSE: 124.7845980866563
+Laplace Log Likelihood: -6.165346437287973

Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.

References

[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541

[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.

diff --git a/dev/examples/basic_examples/Coin Toss Model/index.html b/dev/examples/basic_examples/Coin Toss Model/index.html new file mode 100644 index 000000000..62237bcc3 --- /dev/null +++ b/dev/examples/basic_examples/Coin Toss Model/index.html @@ -0,0 +1,42 @@ + +Coin toss model (Beta-Bernoulli) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Coin toss model (Beta-Bernoulli)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example, we are going to perform an exact inference for a coin toss model that can be represented as:

\[\begin{aligned} +p(\theta) &= \mathrm{Beta}(\theta|a, b),\\ +p(y_i|\theta) &= \mathrm{Ber}(y_i|\theta),\\ +\end{aligned}\]

where $y_i \in \{0, 1\}$ is a binary observation induced by Bernoulli likelihood while $\theta$ is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of $\theta$.

We start with importing all needed packages:

using RxInfer, Random

Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:

rng = MersenneTwister(42)
+n = 500
+θ_real = 0.75
+distribution = Bernoulli(θ_real)
+
+dataset = float.(rand(rng, Bernoulli(θ_real), n));
# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(4.0, 8.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+end
result = infer(
+    model = coin_model(length(dataset)), 
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
θestimated = result.posteriors[:θ]
Beta{Float64}(α=365.0, β=147.0)
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+plot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+vline!([θ_real], label="Real θ")

diff --git a/dev/examples/basic_examples/Hidden Markov Model/index.html b/dev/examples/basic_examples/Hidden Markov Model/index.html new file mode 100644 index 000000000..9f534b00b --- /dev/null +++ b/dev/examples/basic_examples/Hidden Markov Model/index.html @@ -0,0 +1,132 @@ + +How to train your Hidden Markov Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

How to train your Hidden Markov Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate()
+;

In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment.

First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time $t$, let's call the estimate of the Roomba's position $s_t$.

However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call $A$.

Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.

At time $t$, we will call our observations $x_t$ and encode the mapping from the Roomba's position to the observations in a matrix we call $B$. $B$ also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:

\[\begin{aligned} + s_t & \sim \mathcal{C}at(A s_{t-1}),\\ + x_t & \sim \mathcal{C}at(B s_t).\\ +\end{aligned}\]

This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices $A$ and $B$ so we can use them to track the whereabouts of our little cleaning agent.

using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots

In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).

To generate our observation data, we'll follow these steps:

  1. Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.
  2. Determine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.
  3. Determine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.
  4. Repeat steps 2-3 for as many samples as we want.

The following code implements this process and generates our observation data:

"""
+    rand_vec(rng, distribution::Categorical)
+
+This function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.
+"""
+function rand_vec(rng, distribution::Categorical) 
+    k = ncategories(distribution)
+    s = zeros(k)
+    drawn_category = rand(rng, distribution)
+    s[drawn_category] = 1.0
+    return s
+end
+
+function generate_data(n_samples; seed = 42)
+    
+    rng = MersenneTwister(seed)
+    
+    # Transition probabilities 
+    state_transition_matrix = [0.9 0.0 0.1;
+                                                        0.0 0.9 0.1; 
+                                                        0.05 0.05 0.9] 
+    # Observation noise
+    observation_distribution_matrix = [0.9 0.05 0.05;
+                                                                         0.05 0.9 0.05;
+                                                                         0.05 0.05 0.9] 
+    # Initial state
+    s_initial = [1.0, 0.0, 0.0] 
+    
+    states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states
+    observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations
+    
+    s_prev = s_initial
+    
+    for t = 1:n_samples
+        s_probvec = state_transition_matrix * s_prev
+        states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))
+        obs_probvec = observation_distribution_matrix * states[t]
+        observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))
+        s_prev = states[t]
+    end
+    
+    return observations, states
+end
generate_data (generic function with 1 method)

We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.

# Test data
+N = 100
+x_data, s_data = generate_data(N);
+
+scatter(argmax.(s_data), leg=false, xlabel="Time",yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]))

Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the $A$ and $B$ matrices we can use MatrixDirichlet priors. For the $A$-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on $A$ with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on $B$. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.

Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!

# Model specification
+@model function hidden_markov_model(n)
+    
+    A ~ MatrixDirichlet(ones(3,3))
+    B ~ MatrixDirichlet([ 10.0 1.0 1.0; 
+                                            1.0 10.0 1.0; 
+                                            1.0 1.0 10.0 ])
+    
+    s_0 ~ Categorical(fill(1.0 / 3.0, 3))
+    
+    s = randomvar(n)
+    x = datavar(Vector{Float64}, n)
+    
+    s_prev = s_0
+    
+    for t in 1:n
+        s[t] ~ Transition(s_prev, A) 
+        x[t] ~ Transition(s[t], B)
+        s_prev = s[t]
+    end
+    
+end
+
+# Constraints specification
+@constraints function hidden_markov_model_constraints()
+    q(s_0, s, A, B) = q(s_0, s)q(A)q(B)
+end
hidden_markov_model_constraints (generic function with 1 method)

Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?

We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.

Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!

imodel = hidden_markov_model(N)
+idata = (x = x_data,)
+
+imarginals = (
+    A = vague(MatrixDirichlet, 3, 3), 
+    B = vague(MatrixDirichlet, 3, 3), 
+    s = vague(Categorical, 3)
+)
+
+ireturnvars = (
+    A = KeepLast(),
+    B = KeepLast(),
+    s = KeepLast()
+)
+
+result = infer(
+    model         = imodel, 
+    data          = idata,
+    constraints   = hidden_markov_model_constraints(),
+    initmarginals = imarginals, 
+    returnvars    = ireturnvars, 
+    iterations    = 20, 
+    free_energy   = true
+);

That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over $A$) and about the uncertainty in the roombas observations (A good posterior over $B$). Let's see if it worked

println("Posterior Marginal for A:")
+mean(result.posteriors[:A])
Posterior Marginal for A:
+3×3 Matrix{Float64}:
+ 0.871955   0.0290008  0.0572283
+ 0.0349989  0.817591   0.135675
+ 0.0930457  0.153408   0.807097
println("Posterior Marginal for B:")
+mean(result.posteriors[:B])
Posterior Marginal for B:
+3×3 Matrix{Float64}:
+ 0.949636   0.0974741  0.0518997
+ 0.0244903  0.833632   0.0277884
+ 0.0258734  0.0688939  0.920312

Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. 

p1 = scatter(argmax.(s_data), 
+                        title="Inference results", 
+                        label = "Real", 
+                        ms = 6, 
+                        legend=:right,
+                        xlabel="Time" ,
+                        yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]),
+                        size=(900,550)
+                        )
+
+p1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),
+                        label = "Inferred",
+                        ms = 3
+                        )
+
+p2 = plot(result.free_energy, 
+                    label="Free energy",
+                    xlabel="Iteration Number"
+                    )
+
+plot(p1, p2, layout = @layout([ a; b ]))

Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.

diff --git a/dev/examples/basic_examples/Kalman filtering and smoothing/index.html b/dev/examples/basic_examples/Kalman filtering and smoothing/index.html new file mode 100644 index 000000000..6dd69a656 --- /dev/null +++ b/dev/examples/basic_examples/Kalman filtering and smoothing/index.html @@ -0,0 +1,412 @@ + +Kalman filtering and smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Kalman filtering and smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.

We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.

We then solve an identification problem which does not have an analytical solution.

Utimately, we show how RxInfer.jl can deal with missing observations.

Gaussian Linear Dynamical System

LGSSM can be described with the following equations:

\[\begin{aligned} + p(x_i|x_{i - 1}) & = \mathcal{N}(x_i|A * x_{i - 1}, \mathcal{P}),\\ + p(y_i|x_i) & = \mathcal{N}(y_i|B * x_i, \mathcal{Q}), +\end{aligned}\]

where $x_i$ are hidden states, $y_i$ are noisy observations, $A$, $B$ are state transition and observational matrices, $\mathcal{P}$ and $\mathcal{Q}$ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, A, B, Q, P)
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(B * x[i], P))
+        x_prev = x[i]
+    end
+    
+    return x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 1234
+
+rng = MersenneTwister(1234)
+
+# We will model 2-dimensional observations with rotation matrix `A`
+# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`
+# are known and fixed for all time-steps
+θ = π / 35
+A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+B = diageye(2)
+Q = diageye(2)
+P = 25.0 .* diageye(2)
+
+# Number of observations
+n = 300;
x, y = generate_data(rng, A, B, Q, P);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.

px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+px = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)
+
+plot(px)

To create a model we use GraphPPL package and @model macro:

@model function rotate_ssm(n, x0, A, B, Q, P)
+    
+    # We create constvar references for better efficiency
+    cA = constvar(A)
+    cB = constvar(B)
+    cQ = constvar(Q)
+    cP = constvar(P)
+    
+    # `x` is a sequence of hidden states
+    x = randomvar(n)
+    # `y` is a sequence of "clamped" observations
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    x_prev = x_prior
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)
+        y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)
+        x_prev = x[i]
+    end
+
+end

To run inference we also specify prior for out first hidden state:

x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));
# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. 
+# infer(..., options = (limit_stack_depth = 500, ))`
+result = infer(
+    model = rotate_ssm(length(y), x0, A, B, Q, P), 
+    data = (y = y,),
+    free_energy = true
+);
+
+xmarginals  = result.posteriors[:x]
+logevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence
px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :teal)
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :violet)
+
+plot(px)

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:

logevidence
1-element Vector{Float64}:
+ -1882.2434870099778

We may be also interested in performance of our resulting Belief Propagation algorithm:

@benchmark infer(
+    model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), 
+    data = (y = $y,)
+)
BenchmarkTools.Trial: 140 samples with 1 evaluation.
+ Range (min … max):  28.850 ms … 94.284 ms  ┊ GC (min … max): 0.00% … 32.97
+%
+ Time  (median):     33.721 ms              ┊ GC (median):    0.00%
+ Time  (mean ± σ):   35.765 ms ±  6.834 ms  ┊ GC (mean ± σ):  5.28% ±  9.06
+%
+
+         ▁▁▁▅▆█▅ ▁                                             
+  ▄▃▃▁▃▇▇█████████▇▄▃▅▁▁▁▁▁▁▁▁▄▁▃▃▄▃▆▆▁▃▁▄▁▄▁▄▁▁▁▃▁▁▁▁▁▁▁▃▁▃▃ ▃
+  28.8 ms         Histogram: frequency by time        52.3 ms <
+
+ Memory estimate: 9.73 MiB, allocs estimate: 226250.

System Identification Problem

In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:

using RxInfer, Distributions, StableRNGs, Plots
function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)
+
+    rng = StableRNG(seed)
+
+    real_x = Vector{Float64}(undef, n)
+    real_w = Vector{Float64}(undef, n)
+    real_y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))
+        real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))
+        real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))
+
+        x_i_min = real_x[i]
+        w_i_min = real_w[i]
+    end
+    
+    return real_x, real_w, real_y
+end
generate_data (generic function with 2 methods)

The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.

Combination 1: y = x + w

In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:

n = 250
+real_x, real_w, real_y = generate_data(+, n);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, real_x, label = "x")
+pl = plot!(pl, real_w, label = "w")
+
+pr = plot(title = "Combined y = x + w")
+pr = scatter!(pr, real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:

@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x = randomvar(n)
+    w = randomvar(n)
+    s = randomvar(n)
+    y = datavar(Float64, n)
+    
+    x_i_min = x0
+    w_i_min = w0
+    
+    for i in 1:n
+        x[i] ~ Normal(mean = x_i_min, precision = τ_x)
+        w[i] ~ Normal(mean = w_i_min, precision = τ_w)
+        s[i] ~ f(x[i], w[i])
+        y[i] ~ Normal(mean = s[i], precision = τ_y)
+        
+        x_i_min = x[i]
+        w_i_min = w[i]
+    end
+    
+end

RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:

constraints = @constraints begin 
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y
+)
+Options:
+  warn = true

The next step is to assign priors, initialise needed messages and marginals and call the inference function:

m_x_0, τ_x_0 = -20.0, 1.0
+m_w_0, τ_w_0 = 20.0, 1.0
+
+# We set relatively strong priors for random walk noise components
+# and sort of vague prior for the noise of the observations
+a_x, b_x = 0.01, 0.01var(real_x)
+a_w, b_w = 0.01, 0.01var(real_w)
+a_y, b_y = 1.0, 1.0
+
+# We set relatively strong priors for messages
+xinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))
+winit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))
+
+imessages = (x = xinit, w = winit)
+imarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))
+
+result = infer(
+    model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),
+    data  = (y = real_y,), 
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = imessages, 
+    initmarginals = imarginals, 
+    iterations = 50
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)

Let's examine our inference results:

τ_x_marginals = result.posteriors[:τ_x]
+τ_w_marginals = result.posteriors[:τ_w]
+τ_y_marginals = result.posteriors[:τ_y]
+
+smarginals = result.posteriors[:s]
+xmarginals = result.posteriors[:x]
+wmarginals = result.posteriors[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.

Combination 2: y = min(x, w)

In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:

# Smoothed version of `min` without zero-ed derivatives
+function smooth_min(x, y)    
+    if x < y
+        return x + 1e-4 * y
+    else
+        return y + 1e-4 * x
+    end
+end
smooth_min (generic function with 1 method)

RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:

min_meta = @meta begin 
+    # In this example we are going to use a simple `Linearization` method
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true
n = 200
+min_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, min_real_x, label = "x")
+pl = plot!(pl, min_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, min_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

min_m_x_0, min_τ_x_0 = -1.0, 1.0
+min_m_w_0, min_τ_w_0 = 1.0, 1.0
+
+min_a_x, min_b_x = 1.0, 1.0
+min_a_w, min_b_w = 1.0, 1.0
+min_a_y, min_b_y = 1.0, 1.0
+
+min_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))
+min_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))
+
+min_result = infer(
+    model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),
+    data  = (y = min_real_y,), 
+    meta = min_meta,
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = min_imessages, 
+    initmarginals = min_imarginals, 
+    iterations = 100
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)
min_τ_x_marginals = min_result.posteriors[:τ_x]
+min_τ_w_marginals = min_result.posteriors[:τ_w]
+min_τ_y_marginals = min_result.posteriors[:τ_y]
+
+min_smarginals = min_result.posteriors[:s]
+min_xmarginals = min_result.posteriors[:x]
+min_wmarginals = min_result.posteriors[:w]
+
+px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, min_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, min_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, min_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks).

Online (filtering) identification: y = min(x, w)

Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:

@model function rx_identification(f)
+    
+    # We are going to continuosly update our priors
+    # based on new posteriors
+    m_x_0 = datavar(Float64) 
+    τ_x_0 = datavar(Float64)
+    m_w_0 = datavar(Float64) 
+    τ_w_0 = datavar(Float64)
+    a_x   = datavar(Float64) 
+    b_x   = datavar(Float64)
+    a_y   = datavar(Float64) 
+    b_y   = datavar(Float64)
+    a_w   =  datavar(Float64) 
+    b_w   = datavar(Float64)
+    s     = randomvar()
+    y     = datavar(Float64)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x ~ Normal(mean = x0, precision = τ_x)
+    w ~ Normal(mean = w0, precision = τ_w)
+
+    s ~ f(x, w)
+    y ~ Normal(mean = s, precision = τ_y)
+    
+end

We impose structured mean-field assumption for this model as well:

rx_constraints = @constraints begin 
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ
+_y)
+Options:
+  warn = true

Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:

autoupdates = @autoupdates begin 
+    m_x_0, τ_x_0 = mean_precision(q(x))
+    m_w_0, τ_w_0 = mean_precision(q(w))
+    a_x = shape(q(τ_x)) 
+    b_x = rate(q(τ_x))
+    a_y = shape(q(τ_y))
+    b_y = rate(q(τ_y))
+    a_w = shape(q(τ_w)) 
+    b_w = rate(q(τ_w))
+end
(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_
+x = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_
+y)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))

As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):

rx_meta = @meta begin 
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true

Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:

n = 300
+rx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, rx_real_x, label = "x")
+pl = plot!(pl, rx_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

engine = infer(
+    model         = rx_identification(smooth_min),
+    constraints   = rx_constraints,
+    data          = (y = rx_real_y,),
+    autoupdates   = autoupdates,
+    meta          = rx_meta,
+    returnvars    = (:x, :w, :τ_x, :τ_w, :τ_y, :s),
+    keephistory   = 1000,
+    historyvars   =  KeepLast(),
+    initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),
+    iterations    = 10,
+    free_energy = true, 
+    free_energy_diagnostics = nothing,
+    autostart     = true,
+)
RxInferenceEngine:
+  Posteriors stream    | enabled for (w, s, τ_x, τ_w, τ_y, x)
+  Free Energy stream   | enabled
+  Posteriors history   | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)
+  Free Energy history  | available
+  Enabled events       | [  ]
rx_smarginals = engine.history[:s]
+rx_xmarginals = engine.history[:x]
+rx_wmarginals = engine.history[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, rx_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = "Estimated X")
+
+px1 = plot!(px1, rx_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = "Estimated W")
+
+px2 = scatter!(px2, rx_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the "disabled" state, does not infer anything and simply increases its variance (which is expected for the random walk).

Handling Missing Data

An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.

Let us assume that the following model generates the data

\[\begin{aligned} + {x}_t &\sim \mathcal{N}\left({x}_{t-1}, 1.0\right) \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, P \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation $\hat{y}_t \in \mathrm{R}$ we sometimes will catch missing observations.

using RxInfer, Plots
@model function smoothing(n, x0)
+    
+    P ~ Gamma(shape = 0.001, scale = 0.001)
+    x_prior ~ Normal(mean = mean(x0), var = var(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ Normal(mean = x_prev, precision = 1.0)
+        y[i] ~ Normal(mean = x[i], precision = P)
+        
+        x_prev = x[i]
+    end
+
+end

We need to manually extend the set of rules to support ::Missing values

P = 1.0
+n = 250
+
+real_signal     = map(e -> sin(0.05 * e), collect(1:n))
+noisy_data      = real_signal + rand(Normal(0.0, sqrt(P)), n);
+missing_indices = 100:125
+missing_data    = similar(noisy_data, Union{Float64, Missing}, )
+
+copyto!(missing_data, noisy_data)
+
+for index in missing_indices
+    missing_data[index] = missing
+end
constraints = @constraints begin
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+Options:
+  warn = true
x0_prior = NormalMeanVariance(0.0, 1000.0)
+
+result = infer(
+    model = smoothing(n, x0_prior), 
+    data  = (y = missing_data,), 
+    constraints = constraints,
+    initmarginals = (P = Gamma(0.001, 0.001), ),
+    returnvars = (x = KeepLast(),),
+    iterations = 20
+);
plot(real_signal, label = "Noisy signal", legend = :bottomright)
+scatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = "Missing region")
+plot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = "Estimated hidden state")

diff --git a/dev/examples/basic_examples/Predicting Bike Rental Demand/index.html b/dev/examples/basic_examples/Predicting Bike Rental Demand/index.html new file mode 100644 index 000000000..3c99b5c1c --- /dev/null +++ b/dev/examples/basic_examples/Predicting Bike Rental Demand/index.html @@ -0,0 +1,193 @@ + +Predicting Bike Rental Demand · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Predicting Bike Rental Demand

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer

Preamble: Enabling Predictions

RxInfer.jl facilitates predictions in two primary ways.

  1. Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.
  2. Explicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.

Example

Consider the following model:

@model function example_model()
+    y = datavar(Float64) where {allow_missing = true}
+
+    h ~ NormalMeanPrecision(0, 1.0)
+    x ~ NormalMeanPrecision(h, 1.0)
+    y ~ NormalMeanPrecision(x, 10.0)
+end
# Implicit Prediction
+result = infer(model = example_model(), data = (y = missing,))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)
# Explicit Prediction
+result = infer(model = example_model(), predictvars = (y = KeepLast(),))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)

Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.

using CSV, DataFrames, Plots

Objective

This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.

Dataset Source

Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.

# Load the data
+df = CSV.read("../data/bike_count/modified_bicycle.csv", DataFrame)
+df[1:10, :]
10×6 DataFrame
+ Row │ datetime            temp     atemp    humidity  windspeed  count
+     │ String31            Float64  Float64  Float64   Float64    Int64
+─────┼──────────────────────────────────────────────────────────────────
+   1 │ 2011-01-01 0:00:00     9.84   14.395      81.0     0.0        16
+   2 │ 2011-01-01 1:00:00     9.02   13.635      80.0     0.0        40
+   3 │ 2011-01-01 2:00:00     9.02   13.635      80.0     0.0        32
+   4 │ 2011-01-01 3:00:00     9.84   14.395      75.0     0.0        13
+   5 │ 2011-01-01 4:00:00     9.84   14.395      75.0     0.0         1
+   6 │ 2011-01-01 5:00:00     9.84   12.88       75.0     6.0032      1
+   7 │ 2011-01-01 6:00:00     9.02   13.635      80.0     0.0         2
+   8 │ 2011-01-01 7:00:00     8.2    12.88       86.0     0.0         3
+   9 │ 2011-01-01 8:00:00     9.84   14.395      75.0     0.0         8
+  10 │ 2011-01-01 9:00:00    13.12   17.425      76.0     0.0        14
# we reserve few samples for prediction
+n_future = 24
+
+X = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]
+y = Union{Float64, Missing}[df[:, "count"]...][1:end-n_future]
+
+state_dim = length(X[1]); # dimensionality of feature space

Generative Model with Priors

We present a generative model that delineates the latent dynamics of feature evolution, represented by $\mathbf{h}_t$, and their link to the bike rental counts, $\mathbf{y}_t$.

Equations and Priors

  1. Feature Dynamics with Prior:

    • Prior: $\mathbf{a} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Dynamics: $\mathbf{h}_t \sim \mathcal{N}(\mathbf{A h}_{t-1}, \mathbf{Q})$

    • \[\mathbf{A}\]

      is the transition matrix, reshaped from the prior vector $\mathbf{a}$, and $\mathbf{Q}$ represents process noise.

  2. Noisy Observations:

    • \[\mathbf{x}_t \sim \mathcal{N}(\mathbf{h}_t, \mathbf{P})\]

    • Represents the observed noisy state of the features.

  3. Count Prediction with Prior:

    • Prior: $\boldsymbol{\theta} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Prediction: $y_t \sim \mathcal{N}(\text{softplus}(\boldsymbol{\theta}^\top\mathbf{h}_t), \sigma^2)$
    • Models the bike rental count as influenced by a non-linear transformation of the hidden state.

Interpretation

  • This framework aims to simultaneously infer the transition matrix $\mathbf{A}$ and the regression parameters $\boldsymbol{\theta}$, providing a comprehensive view of the feature space dynamics and the count prediction.
  • By employing Gaussian priors on both $\mathbf{a}$ and $\boldsymbol{\theta}$, we incorporate beliefs about their distributions.
  • The inference process aims to discover these underlying dynamics, enabling predictions of both features $\mathbf{x}_t$ and counts $y_t$.
# We augument the dataset with missing entries for 24 hours ahead
+append!(X, repeat([missing], n_future))
+append!(y, repeat([missing], n_future));
# Function to perform the state transition in the model.
+# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.
+function transition(a, x)
+    nm, n = length(a), length(x)
+    m = nm ÷ n  # Calculate the number of rows for reshaping 'a' into a matrix
+    A = reshape(a, (m, n))  
+    return A * x
+end
transition (generic function with 1 method)
# The dotsoftplus function combines a dot product and softplus transformation.
+# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,
+# especially if the data suggests other forms of relationships or distributions.
+function dotsoftplus(a, x)
+    log(1 + exp(dot(a, x)))
+end
dotsoftplus (generic function with 1 method)
# model definction
+@model function bicycle_ssm(n, h0, θ0, a0, Q, P)
+
+    # `h` is a sequence of hidden states
+    h = randomvar(n)
+
+    # `x` is a sequence of observed states (features)
+    x = datavar(Vector{Float64}, n) where {allow_missing = true}
+    # `y` is a sequence of "count" bicycles
+    y = datavar(Float64, n) where {allow_missing = true}
+
+    a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))
+
+    θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))
+
+    h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))
+    h_prev = h_prior
+    
+    for i in 1:n
+        
+        h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)
+        
+        x[i] ~ MvNormal(μ=h[i], Σ=P)
+        
+        y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)
+        
+        h_prev = h[i]
+    end
+
+end
# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.
+# However, alternative methods like Unscented or CVI approximations can also be considered.
+transition_meta = @meta begin 
+    transition() -> Linearization()
+    dotsoftplus() -> Linearization()
+end
Meta specification:
+  transition() -> Linearization()
+  dotsoftplus() -> Linearization()
+Options:
+  warn = true
# We define rather uninformative priors 
+prior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))
+prior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))
+prior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))
MvNormalMeanCovariance(
+μ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0
+.0, 0.0]
+Σ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … 
+0.0 1.0]
+)
# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages
+imessages = ( h = prior_h, a = prior_a, θ = prior_θ,)
+
+bicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))
+
+result = infer(
+    model = bicycle_model,
+    data  = (y = y, x=X), 
+    options = (limit_stack_depth = 500, ), 
+    returnvars = KeepLast(),
+    initmessages = imessages,
+    meta = transition_meta,
+    iterations = 20,
+    showprogress=true,
+)
Inference results:
+  Posteriors       | available for (a, h, h_prior, θ)
+  Predictions      | available for (y, x)
# For a sake of this example, we extract only predictions
+mean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])
+mean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])
+
+mean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)
+mean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)
+mean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)
+mean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);
slice = (300, length(y))
+data = df[:, "count"][length(y)-n_future:length(y)]
+
+p = scatter(y, 
+            color=:darkblue, 
+            markerstrokewidth=0,
+            label="Observed Count", 
+            alpha=0.6)
+
+# Plotting the mean prediction with variance ribbon
+plot!(mean_y, ribbon=sqrt.(cov_y), 
+      color=:orange, 
+      fillalpha=0.3,
+      label="Predicted Mean ± Std Dev")
+
+# Adding a vertical line to indicate the start of the future prediction
+vline!([length(y)-n_future], 
+       label="Prediction Start", 
+       linestyle=:dash, 
+       linecolor=:green)
+
+# Future (unobserved) data
+plot!(length(y)-n_future:length(y), data, label="Future Count")
+
+# Adjusting the limits
+xlims!(slice)
+
+# Enhancing the plot with titles and labels
+title!("Bike Rental Demand Prediction")
+xlabel!("Time")
+ylabel!("Bike Count")
+
+# Adjust the legend
+legend=:topright
+
+# Show the final plot
+display(p)

using Plots
+
+# Define a color palette
+palette = cgrad(:viridis)
+
+# Plot the hidden states with observations
+p1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label="Hidden State 1", legend=:topleft)
+plot!(df[!, :temp], color=:grey, label="Temperature")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Temperature vs Hidden State 1")
+
+p2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label="Hidden State 2", legend=:topleft)
+plot!(df[!, :atemp], color=:grey, label="Feels-Like Temp")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="")
+xlabel!("Time")
+ylabel!("Value")
+title!("Feels-Like Temp vs Hidden State 2")
+
+p3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label="Hidden State 3", legend=:topleft)
+plot!(df[!, :humidity], color=:grey, label="Humidity")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Humidity vs Hidden State 3")
+
+p4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label="Hidden State 4", legend=:topleft)
+plot!(df[!, :windspeed], color=:grey, label="Windspeed")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Windspeed vs Hidden State 4")
+
+for p in [p1, p2, p3, p4]
+    xlims!(p, first(slice), last(slice))
+end
+
+plot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))

Conclusion

While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.

The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.

diff --git a/dev/examples/basic_examples/overview/index.html b/dev/examples/basic_examples/overview/index.html new file mode 100644 index 000000000..aa7a2c447 --- /dev/null +++ b/dev/examples/basic_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Basic examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Basic examples contain "Hello World!" of Bayesian inference in RxInfer.

  • Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.
  • Bayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.
  • Kalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations
  • Predicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.
  • How to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.
diff --git a/dev/examples/overview/index.html b/dev/examples/overview/index.html new file mode 100644 index 000000000..f1fba6328 --- /dev/null +++ b/dev/examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Examples overview

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

  • Basic examples: Basic examples contain "Hello World!" of Bayesian inference in RxInfer.
  • Advanced examples: Advanced examples contain more complex inference problems.
  • Problem specific: Problem specific examples contain specialized models and inference for various domains.
diff --git a/dev/examples/problem_specific/Autoregressive Models/index.html b/dev/examples/problem_specific/Autoregressive Models/index.html new file mode 100644 index 000000000..616053f61 --- /dev/null +++ b/dev/examples/problem_specific/Autoregressive Models/index.html @@ -0,0 +1,311 @@ + +Autoregressive Models · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Autoregressive Models

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:

\[\begin{aligned} +p(\gamma) &= \mathrm{Gamma}(\gamma|a, b),\\ +p(\mathbf{\theta}) &= \mathcal{N}(\mathbf{\theta}|\mathbf{\mu}, \Sigma),\\ +p(x_t|\mathbf{x}_{t-1:t-k}) &= \mathcal{N}(x_t|\mathbf{\theta}^{T}\mathbf{x}_{t-1:t-k}, \gamma^{-1}),\\ +p(y_t|x_t) &= \mathcal{N}(y_t|x_t, \tau^{-1}), +\end{aligned}\]

where $x_t$ is a current state of our system, $\mathbf{x}_{t-1:t-k}$ is a sequence of $k$ previous states, $k$ is an order of autoregression process, $\mathbf{\theta}$ is a vector of transition coefficients, $\gamma$ is a precision of state transition process, $y_k$ is a noisy observation of $x_k$ with precision $\tau$.

For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.

We start with importing all needed packages:

using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters

Let's generate some synthetic dataset, we use a predefined sets of coeffcients for $k$ = 1, 3 and 5 respectively:

# The following coefficients correspond to stable poles
+coefs_ar_1 = [-0.27002517200218096]
+coefs_ar_2 = [0.4511170798064709, -0.05740081602446657]
+coefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];
function generate_ar_data(rng, n, θ, γ, τ)
+    order        = length(θ)
+    states       = Vector{Vector{Float64}}(undef, n + 3order)
+    observations = Vector{Float64}(undef, n + 3order)
+    
+    γ_std = sqrt(inv(γ))
+    τ_std = sqrt(inv(τ))
+    
+    states[1] = randn(rng, order)
+    
+    for i in 2:(n + 3order)
+        states[i]       = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])
+        observations[i] = rand(rng, Normal(states[i][1], τ_std))
+    end
+    
+    return states[1+3order:end], observations[1+3order:end]
+end
generate_ar_data (generic function with 1 method)
# Seed for reproducibility
+seed = 123
+rng  = MersenneTwister(seed)
+
+# Number of observations in synthetic dataset
+n = 500
+
+# AR process parameters
+real_γ = 1.0
+real_τ = 0.5
+real_θ = coefs_ar_5
+
+states, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);

Let's plot our synthetic dataset:

plot(first.(states), label = "Hidden states")
+scatter!(observations, label = "Observations")

Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order $k$ > 1 and for Univariate AR (reduces to simple State-Space-Model) with order $k$ = 1.

@model function lar_model(T::Type, n, order, c, τ)
+    
+     
+    # We create a sequence of random variables for hidden states
+    x = randomvar(n)
+    # As well a sequence of observartions
+    y = datavar(Float64, n)
+    
+    ct = constvar(c)
+    # We assume observation noise to be known
+    cτ = constvar(τ)
+    
+    γ  = randomvar()
+    θ  = randomvar()
+    x0 = randomvar()
+    
+    # Prior for first state
+    if T === Multivariate
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+        x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+    else
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ Normal(μ = 0.0, γ = 1.0)
+        x0 ~ Normal(μ = 0.0, γ = 1.0)
+    end
+    
+    x_prev = x0
+    
+    for i in 1:n
+        
+        x[i] ~ AR(x_prev, θ, γ) 
+        
+        if T === Multivariate
+            y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)
+        else
+            y[i] ~ Normal(μ = ct * x[i], γ = cτ)
+        end
+        
+        x_prev = x[i]
+    end
+
+end
@constraints function ar_constraints() 
+    q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)
+end
ar_constraints (generic function with 1 method)
@meta function ar_meta(artype, order, stype)
+    AR() -> ARMeta(artype, order, stype)
+end
ar_meta (generic function with 1 method)
morder  = 5
+martype = Multivariate
+mc      = ReactiveMP.ar_unit(martype, morder)
+mconstraints = ar_constraints()
+mmeta        = ar_meta(martype, morder, ARsafe())
+
+moptions = (limit_stack_depth = 100, )
+
+mmodel         = lar_model(martype, length(observations), morder, mc, real_τ)
+mdata          = (y = observations, )
+minitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))
+mreturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+# First execution is slow due to Julia's initial compilation 
+# Subsequent runs will be faster (benchmarks are below)
+mresult = infer(
+    model = mmodel, 
+    data  = mdata,
+    constraints   = mconstraints,
+    meta          = mmeta,
+    options       = moptions,
+    initmarginals = minitmarginals,
+    returnvars    = mreturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
@unpack x, γ, θ = mresult.posteriors
Dict{Symbol, Vector} with 3 entries:
+  :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)
+, Ga…
+  :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…
+  :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…

We will use different initial marginals depending on type of our AR process

p1 = plot(first.(states), label="Hidden state")
+p1 = scatter!(p1, observations, label="Observations")
+p1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label="Inferred states", legend = :bottomright)
+
+p2 = plot(mean.(γ), ribbon = std.(γ), label = "Inferred transition precision", legend = :topright)
+p2 = plot!([ real_γ ], seriestype = :hline, label = "Real transition precision")
+
+p3 = plot(mresult.free_energy, label = "Bethe Free Energy")
+
+plot(p1, p2, p3, layout = @layout([ a; b c ]))

Let's also plot a subrange of our results:

subrange = div(n,5):(div(n, 5) + div(n, 5))
+
+plot(subrange, first.(states)[subrange], label="Hidden state")
+scatter!(subrange, observations[subrange], label="Observations")
+plot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label="Inferred states", legend = :bottomright)

It is also interesting to see where our AR coefficients converge to:

let
+    pθ = plot()
+
+    θms = mean.(θ)
+    θvs = var.(θ)
+    
+    l = length(θms)
+
+    edim(e) = (a) -> map(r -> r[e], a)
+
+    for i in 1:length(first(θms))
+        pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = "Estimated θ[$i]")
+    end
+    
+    for i in 1:length(real_θ)
+        pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = "Real θ[$i]")
+    end
+    
+    plot(pθ, legend = :outertopright, size = (800, 300))
+end

println("$(length(real_θ))-order AR inference Bethe Free Energy: ", last(mresult.free_energy))
5-order AR inference Bethe Free Energy: 1024.0775661298358

We can also run a 1-order AR inference on 5-order AR data:

uorder  = 1
+uartype = Univariate
+uc      = ReactiveMP.ar_unit(uartype, uorder)
+uconstraints = ar_constraints()
+umeta        = ar_meta(uartype, uorder, ARsafe())
+
+uoptions = (limit_stack_depth = 100, )
+
+umodel         = lar_model(uartype, length(observations), uorder, uc, real_τ)
+udata          = (y = observations, )
+uinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))
+ureturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+uresult = infer(
+    model = umodel, 
+    data  = udata,
+    meta  = umeta,
+    constraints   = uconstraints,
+    initmarginals = uinitmarginals,
+    returnvars    = ureturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
println("1-order AR inference Bethe Free Energy: ", last(uresult.free_energy))
1-order AR inference Bethe Free Energy: 1025.8792949319954
if uresult.free_energy[end] > mresult.free_energy[end]
+    println("We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.")
+else
+    error("AR-1 performs better than AR-5...") 
+end
We can see that, according to final Bethe Free Energy value, in this exampl
+e 5-order AR process can describe data better than 1-order AR.

Autoregressive Moving Average Model

Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:

\[\begin{aligned} +e_t \sim \mathcal{N}(0, \gamma^{-1}) \quad +\theta &\sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \quad +\eta \sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \\ +\mathbf{h}_0 &\sim \mathcal{MN}\left(\begin{bmatrix} +e_{-1} \\ +e_{-2} +\end{bmatrix}, \mathbf{I}\right) \\ +\mathbf{h}_t &= \mathbf{S}\mathbf{h}_{t-1} + \mathbf{c} e_{t-1} \\ +\mathbf{x}_t &= \boldsymbol{\theta}^\top\mathbf{x}_{t-1} + \boldsymbol{\eta}^\top\mathbf{h}_{t} + e_t +\end{aligned}\]

where shift matrix $\mathbf{S}$ is

\[\begin{aligned} +\mathbf{S} = \begin{pmatrix} +0 & 0 \\ +1 & 0 +\end{pmatrix} +\end{aligned}\]

and unit vector $\mathbf{c}$:

\[\begin{aligned} +\mathbf{c}=[1, 0] +\end{aligned}\]

when MA order is $2$

In this way, $\mathbf{h}_t$ containing errors $e_t$ can be viewed as hidden state.

In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., $\boldsymbol{\eta}^\top\mathbf{h}_{t}$, (2) induced by errors $e_t$ that prevents analytical update of precision parameter $\gamma$ (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.

# Load packages
+using RxInfer, LinearAlgebra, CSV, DataFrames, Plots
# Define shift function
+function shift(dim)
+    S = Matrix{Float64}(I, dim, dim)
+    for i in dim:-1:2
+           S[i,:] = S[i-1, :]
+    end
+    S[1, :] = zeros(dim)
+    return S
+end
shift (generic function with 1 method)
@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)
+        
+    c = zeros(p); c[1] = 1.0; # AR
+    b = zeros(q); b[1] = 1.0; # MA
+    S = shift(q); # MA
+    
+    # initialize variables
+    h  = randomvar(n-1)
+    e  = randomvar(n)
+    z  = randomvar(n)
+    
+    x  = datavar(Float64, n) where { allow_missing = true }
+    
+    # priors
+    γ  ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))
+    η  ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))
+    θ  ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))
+    τ  ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))
+    
+    # initial
+    h_0  ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))
+    z[1] ~ AR(h_0, η, τ)
+    e[1] ~ Normal(mean = 0.0, precision = γ)
+
+    x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]
+    
+    h_prev = h_0
+    for t in 1:n-1
+        
+        e[t+1] ~ Normal(mean = 0.0, precision = γ)
+        h[t]   ~ S*h_prev + b*e[t]
+        z[t+1] ~ AR(h[t], η, τ)
+        x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]
+        h_prev = h[t]
+    end
+end

To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle

x_df = CSV.read("../data/arma/aal_stock.csv", DataFrame)
1259×7 DataFrame
+  Row │ date        open     high     low      close    volume    Name
+      │ Date        Float64  Float64  Float64  Float64  Int64     String3
+──────┼───────────────────────────────────────────────────────────────────
+    1 │ 2013-02-08    15.07    15.12   14.63     14.75   8407500  AAL
+    2 │ 2013-02-11    14.89    15.01   14.26     14.46   8882000  AAL
+    3 │ 2013-02-12    14.45    14.51   14.1      14.27   8126000  AAL
+    4 │ 2013-02-13    14.3     14.94   14.25     14.66  10259500  AAL
+    5 │ 2013-02-14    14.94    14.96   13.16     13.99  31879900  AAL
+    6 │ 2013-02-15    13.93    14.61   13.93     14.5   15628000  AAL
+    7 │ 2013-02-19    14.33    14.56   14.08     14.26  11354400  AAL
+    8 │ 2013-02-20    14.17    14.26   13.15     13.33  14725200  AAL
+  ⋮   │     ⋮          ⋮        ⋮        ⋮        ⋮        ⋮         ⋮
+ 1253 │ 2018-01-30    52.45    53.05   52.36     52.59   4741808  AAL
+ 1254 │ 2018-01-31    53.08    54.71   53.0      54.32   5962937  AAL
+ 1255 │ 2018-02-01    54.0     54.64   53.59     53.88   3623078  AAL
+ 1256 │ 2018-02-02    53.49    53.99   52.03     52.1    5109361  AAL
+ 1257 │ 2018-02-05    51.99    52.39   49.75     49.76   6878284  AAL
+ 1258 │ 2018-02-06    49.32    51.5    48.79     51.18   6782480  AAL
+ 1259 │ 2018-02-07    50.91    51.98   50.89     51.4    4845831  AAL
+                                                         1244 rows omitted
# we will use "close" column
+x_data = filter(!ismissing, x_df[:, 5]);
# Plot data
+plot(x_data, xlabel="day", ylabel="price", label=false)

p_order = 10 # AR
+q_order = 4 # MA
4
# Training set
+train_size = 1000
+x_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]
+x_train = Float64.(x_data[p_order+1:end])[1:train_size];
# Test set
+x_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]
+x_test = Float64.(x_data[p_order+1:end])[train_size+1:end];

Inference

# Constraints are needed for performing VMP
+arma_constraints = @constraints begin
+    q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)
+end;
# This cell defines prior knowledge for model parameters
+h_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+γ_prior = GammaShapeRate(1e4, 1.0)
+τ_prior = GammaShapeRate(1e2, 1.0)
+η_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+θ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));
# Model's graph has structural loops, hence, it requires pre-initialisation
+arma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);
+arma_imessages  = (h_0 = h_prior, h = h_prior);
+arma_meta       = ar_meta(Multivariate, q_order, ARsafe());
result = infer(
+    model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), 
+    data  = (x = x_train, ),
+    initmarginals = arma_imarginals,
+    initmessages  = arma_imessages,
+    constraints   = arma_constraints,
+    meta          = arma_meta,
+    iterations    = 50,
+    options       = (limit_stack_depth = 400, ),
+);
plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = "eₜ")

# extract posteriors
+h_posterior = result.posteriors[:h][end][end]
+γ_posterior = result.posteriors[:γ][end]
+τ_posterior = result.posteriors[:τ][end]
+η_posterior = result.posteriors[:η][end]
+θ_posterior = result.posteriors[:θ][end];

Prediction

Here we are going to use our inference results in order to predict the dataset itself

# The prediction function is aimed at approximating the predictive posterior distribution
+# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)
+function prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)
+    h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))
+    ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))
+    c = zeros(p); c[1] = 1.0
+    b = zeros(q); b[1] = 1.0
+    ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)
+    θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))
+    ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)
+    e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))
+    ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out)  
+    @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out)  
+end
prediction (generic function with 1 method)
predictions = []
+for x_prev in x_prev_test
+    push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))
+    # after every new prediction we can actually "retrain" the model to use the power of Bayesian approach
+    # we will skip this part at this notebook
+end
plot(x_test, label="test data", legend=:topleft)
+plot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label="predicted", xlabel="day", ylabel="price")

diff --git a/dev/examples/problem_specific/Gamma Mixture/index.html b/dev/examples/problem_specific/Gamma Mixture/index.html new file mode 100644 index 000000000..83c33dcb1 --- /dev/null +++ b/dev/examples/problem_specific/Gamma Mixture/index.html @@ -0,0 +1,129 @@ + +Gamma Mixture Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gamma Mixture Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.

Load packages

using RxInfer, Random, StatsPlots
# create custom structure for model parameters for simplicity
+struct GammaMixtureModelParameters
+    nmixtures   # number of mixtures
+    priors_as   # tuple of priors for variable a
+    priors_bs   # tuple of priors for variable b
+    prior_s     # prior of variable s
+end

Model specification

@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)
+
+    # fetch information from struct
+    nmixtures = parameters.nmixtures
+    priors_as = parameters.priors_as
+    priors_bs = parameters.priors_bs
+    prior_s   = parameters.prior_s
+
+    # set prior on global selection variable
+    s ~ Dirichlet(probvec(prior_s))
+
+    # allocate vectors of random variables
+    as = randomvar(nmixtures)
+    bs = randomvar(nmixtures)
+
+    # set priors on variables of mixtures
+    for i in 1:nmixtures
+        as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))
+        bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))
+    end
+
+    # introduce random variables for local selection variables and data
+    z = randomvar(nobservations)
+    y = datavar(Float64, nobservations)
+
+    # convert vector to tuples for proper functioning of GammaMixture node
+    tas = tuple(as...)
+    tbs = tuple(bs...)
+
+    # specify local selection variable and data generating process
+    for i in 1:nobservations
+        z[i] ~ Categorical(s)
+        y[i] ~ GammaMixture(z[i], tas, tbs)
+    end
+    
+end
constraints = @constraints begin 
+
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+
+    q(as) = q(as[begin])..q(as[end])
+    q(bs) = q(bs[begin])..q(bs[end])
+    
+    q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])
+end
Constraints:
+  marginals form:
+    q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+    q(as) = q(as[(begin)..(end)])
+    q(bs) = q(bs[(begin)..(end)])
+Options:
+  warn = true
# specify seed and number of data points
+rng = MersenneTwister(43)
+n_samples = 2500
+
+# specify parameters of mixture model that generates the data
+# Note that mixture components have exactly the same means
+mixtures  = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]
+nmixtures = length(mixtures)
+mixing    = rand(rng, nmixtures)
+mixing    = mixing ./ sum(mixing)
+mixture   = MixtureModel(mixtures, mixing)
+
+# generate data set
+dataset = rand(rng, mixture, n_samples);
# specify priors of probabilistic model
+# NOTE: As the means of the mixtures "collide", we specify informative prior for selector variable
+nmixtures = 2
+gpriors = GammaMixtureModelParameters(
+    nmixtures,                                                    # number of mixtures
+    [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ],                         # priors on variables a
+    [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ],      # priors on variables b
+    Dirichlet(1e3*mixing)                                         # prior on variable s
+)
+
+gmodel         = gamma_mixture_model(length(dataset), gpriors)
+gdata          = (y = dataset, )
+ginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))
+greturnvars    = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())
+
+goptions = (
+     
+    default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently
+)
+
+gresult = infer(
+    model         = gmodel, 
+    data          = gdata,
+    constraints   = constraints,
+    options       = (limit_stack_depth = 100,),
+    initmarginals = ginitmarginals,
+    returnvars    = greturnvars,
+    free_energy   = true,
+    iterations    = 250, 
+    showprogress  = true
+);
# extract inferred parameters
+_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])
+_dists   = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))
+_mixing = mean(gresult.posteriors[:s])
+
+# create model from inferred parameters
+_mixture   = MixtureModel(_dists, _mixing);
# report on outcome of inference
+println("Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))")
+println("Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))")
+println("========")
+println("Generated mixing: $(mixing)")
+println("Inferred mixing: $(_mixing)")
Generated means: 0.3333333333333333 and 0.33333333333333337
+Inferred means: 0.33822470398804994 and 0.33305534672666653
+========
+Generated mixing: [0.18923488676601088, 0.8107651132339891]
+Inferred mixing: [0.11395888467453213, 0.8860411153254679]
# plot results
+p1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p1 = plot!(mixture, label=false, title="Generated mixtures", linewidth=3.0)
+
+p2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p2 = plot!(_mixture, label=false, title="Inferred mixtures", linewidth=3.0)
+
+# evaluate the convergence of the algorithm by monitoring the BFE
+p3 = plot(gresult.free_energy, label=false, xlabel="iterations", title="Bethe FE")
+
+plot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))

diff --git a/dev/examples/problem_specific/Gaussian Mixture/index.html b/dev/examples/problem_specific/Gaussian Mixture/index.html new file mode 100644 index 000000000..bc8fe4567 --- /dev/null +++ b/dev/examples/problem_specific/Gaussian Mixture/index.html @@ -0,0 +1,170 @@ + +Gaussian Mixture · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gaussian Mixture

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.

Load packages

using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings

Univariate Gaussian Mixture Model

Consider the data set of length $N$ observed below.

function generate_univariate_data(nr_samples; rng = MersenneTwister(123))
+
+    # data generating parameters
+    class        = [1/3, 2/3]
+    mean1, mean2 = -10, 10
+    precision    = 1.777
+
+    # generate data
+    z = rand(rng, Categorical(class), nr_samples)
+    y = zeros(nr_samples)
+    for k in 1:nr_samples
+        y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))
+    end
+
+    return y
+
+end;
data_univariate = generate_univariate_data(100)
+histogram(data_univariate, bins=50, label="data", normed=true)
+xlims!(minimum(data_univariate), maximum(data_univariate))
+ylims!(0, Inf)
+ylabel!("relative occurrence [%]")
+xlabel!("y")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, w, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(w_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Beta}(s \mid \alpha_s, \beta_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \sigma_k^2) \\ p(w_{k}) &= \Gamma(w_k \mid \alpha_k, \beta_k) \\ + p(z_n \mid s) &= \mathrm{Ber}(z_n \mid s) \\ + p(y_n \mid m, w, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, w_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $w = \{ w_1, w_2, \ldots, w_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

Here we implement the following model with uninformative values for the hyperparameters as

@model function univariate_gaussian_mixture_model(nr_samples)
+    
+    s ~ Beta(1.0, 1.0)
+    
+    m1 ~ Normal(mean = -2.0, var = 1e3)
+    w1 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    m2 ~ Normal(mean = 2.0, var = 1e3)
+    w2 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    z = randomvar(nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    for n in 1:nr_samples
+        z[n] ~ Bernoulli(s)
+        y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, w \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, w \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(w_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Beta}(s \mid \hat{\alpha}_s, \hat{\beta}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\sigma}^2_k) \\ + q(w_k) &= \Gamma (w_k \mid \hat{\alpha}_k, \hat{\beta}_k) \\ + q(z_n) &= \mathrm{Ber}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

results_univariate = infer(
+    model = univariate_gaussian_mixture_model(length(data_univariate)), 
+    constraints = MeanField(),
+    data  = (y = data_univariate,), 
+    initmarginals = (
+        s  = vague(Beta), 
+        m1 = NormalMeanVariance(-2.0, 1e3), 
+        m2 = NormalMeanVariance(2.0, 1e3), 
+        w1 = vague(GammaShapeRate), 
+        w2 = vague(GammaShapeRate)
+    ), 
+    iterations  = 10, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m2, m1, s, w2, w1, z)
+  Free Energy:     | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.
+277, 135.277, 135.277, 135.277, 135.277]

Results

Below the inference results can be seen as a function of the iterations

mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L"posterior $m_1$")
+mp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L"posterior $m_2$")
+mp = plot!(mp, [ -10 ], seriestype = :hline, label = L"true $m_1$")
+mp = plot!(mp, [ 10 ], seriestype = :hline, label = L"true $m_2$")
+
+wp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L"posterior $w_1$", legend = :bottomright, ylim = (-1, 3))
+wp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L"posterior $w_2$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_1$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_2$")
+
+swp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L"posterior $s$")
+swp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L"true $s$")
+
+fep = plot(results_univariate.free_energy, label = "Free Energy", legend = :topright)
+
+plot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))
+xlabel!("iteration")

Multivariate Gaussian Mixture Model

The above example can also be extended to the multivariate case. Consider the data set below

function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))
+
+    L         = 50.0
+    nr_mixtures = 6
+
+    probvec = normalize!(ones(nr_mixtures), 1)
+
+    switch = Categorical(probvec)
+
+    gaussians = map(1:nr_mixtures) do index
+        angle      = 2π / nr_mixtures * (index - 1)
+        basis_v    = L * [ 1.0, 0.0 ]
+        R          = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]
+        mean       = R * basis_v 
+        covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))
+        return MvNormal(mean, covariance)
+    end
+
+    z = rand(rng, switch, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+
+    for n in 1:nr_samples
+        y[n] = rand(rng, gaussians[z[n]])
+    end
+
+    return y
+
+end;
data_multivariate = generate_multivariate_data(500)
+
+sdim(n) = (a) -> map(d -> d[n], a) # helper function
+scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)
+xlabel!(L"y_1")
+ylabel!(L"y_2")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, W, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(W_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Dir}(s \mid \alpha_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \Sigma_k) \\ p(W_{k}) &= \mathcal{W}(W_k \mid V_k, \nu_k) \\ + p(z_n \mid s) &= \mathrm{Cat}(z_n \mid s) \\ + p(y_n \mid m, W, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, W_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $W = \{ W_1, W_2, \ldots, W_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)
+    
+    z = randomvar(nr_samples)
+    m = randomvar(nr_mixtures)
+    w = randomvar(nr_mixtures)
+    y = datavar(Vector{Float64}, nr_samples)
+    
+    for k in 1:nr_mixtures        
+        m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])
+        w[k] ~ Wishart(3, 1e2*diagm(ones(2)))
+    end
+    
+    s ~ Dirichlet(ones(nr_mixtures))
+    
+    means = tuple(m...)
+    precs = tuple(w...)
+    
+    for n in 1:nr_samples
+        z[n] ~ Categorical(s) 
+        y[n] ~ NormalMixture(z[n], means, precs)
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, W \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, W \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(W_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Dir}(s \mid \hat{\alpha}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\Sigma}_k) \\ + q(w_k) &= \mathcal{W}(W_k \mid \hat{V}_k, \hat{\nu}_k) \\ + q(z_n) &= \mathrm{Cat}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

rng = MersenneTwister(121)
+m = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]
+results_multivariate = infer(
+    model = multivariate_gaussian_mixture_model(
+        6, 
+        length(data_multivariate), 
+        m,
+        [diagm(1e2 * ones(2)) for k in 1:6]
+    ), 
+    data  = (y = data_multivariate,), 
+    constraints   = MeanField(),
+    initmarginals = (
+        s = vague(Dirichlet, 6), 
+        m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], 
+        w = Wishart(3, diagm(1e2 * ones(2)))
+    ), 
+    iterations  = 50, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m, w, s, z)
+  Free Energy:     | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49  …  3894.49, 3894.49, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]

Results

Below the inference results can be seen

p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title="Data", xlims=(-75, 75), ylims=(-75, 75))
+p_result = plot(xlims = (-75, 75), ylims = (-75, 75), title="Inference result", legend=false, colorbar = false)
+for (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])
+    gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))
+    global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title="Inference result", legend=false, levels = 7, colorbar = false)
+end
+p_fe = plot(results_multivariate.free_energy, label = "Free Energy")
+
+plot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))

diff --git a/dev/examples/problem_specific/Hierarchical Gaussian Filter/index.html b/dev/examples/problem_specific/Hierarchical Gaussian Filter/index.html new file mode 100644 index 000000000..6ab9ea3be --- /dev/null +++ b/dev/examples/problem_specific/Hierarchical Gaussian Filter/index.html @@ -0,0 +1,145 @@ + +Hierarchical Gaussian Filter · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Hierarchical Gaussian Filter

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).

Simple HGF model can be defined as:

\[\begin{aligned} + x^{(j)}_k & \sim \, \mathcal{N}(x^{(j)}_{k - 1}, f_k(x^{(j - 1)}_k)) \\ + y_k & \sim \, \mathcal{N}(x^{(j)}_k, \tau_k) +\end{aligned}\]

where $j$ is an index of layer in hierarchy, $k$ is a time step and $f_k$ is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with $f_k = \exp(\kappa x + \omega)$ variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:

\[\begin{aligned} + z_k & \sim \, \mathcal{N}(z_{k - 1}, \mathcal{\tau_z}) \\ + x_k & \sim \, \mathcal{N}(x_{k - 1}, \exp(\kappa z_k + \omega)) \\ + y_k & \sim \, \mathcal{N}(x_k, \mathcal{\tau_y}) +\end{aligned}\]

In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.

For simplicity we will consider $\tau_z$, $\tau_y$, $\kappa$ and $\omega$ known and fixed, but there are no principled limitations to make them random variables too.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, k, w, zv, yv)
+    z_prev = 0.0
+    x_prev = 0.0
+
+    z = Vector{Float64}(undef, n)
+    v = Vector{Float64}(undef, n)
+    x = Vector{Float64}(undef, n)
+    y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        z[i] = rand(rng, Normal(z_prev, sqrt(zv)))
+        v[i] = exp(k * z[i] + w)
+        x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))
+        y[i] = rand(rng, Normal(x[i], sqrt(yv)))
+
+        z_prev = z[i]
+        x_prev = x[i]
+    end 
+    
+    return z, x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 42
+
+rng = MersenneTwister(seed)
+
+# Parameters of HGF process
+real_k = 1.0
+real_w = 0.0
+z_variance = abs2(0.2)
+y_variance = abs2(0.1)
+
+# Number of observations
+n = 300
+
+z, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.

let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    scatter!(px, 1:n, y, label = "y_i", color = :red, ms = 2, alpha = 0.2)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

To create a model we use the @model macro:

# We create a single-time step of corresponding state-space process to
+# perform online learning (filtering)
+@model function hgf(real_k, real_w, z_variance, y_variance)
+    
+    # Priors from previous time step for `z`
+    zt_min_mean = datavar(Float64)
+    zt_min_var  = datavar(Float64)
+    
+    # Priors from previous time step for `x`
+    xt_min_mean = datavar(Float64)
+    xt_min_var  = datavar(Float64)
+
+    zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)
+    xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)
+
+    # Higher layer is modelled as a random walk 
+    zt ~ NormalMeanVariance(zt_min, z_variance)
+    
+    # Lower layer is modelled with `GCV` node
+    gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)
+    
+    # Noisy observations 
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(xt, y_variance)
+    
+    return gcvnode
+end
+
+@constraints function hgfconstraints() 
+    q(xt, zt, xt_min) = q(xt, xt_min)q(zt)
+end
+
+@meta function hgfmeta()
+    # Lets use 31 approximation points in the Gauss Hermite cubature approximation method
+    GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) 
+end
hgfmeta (generic function with 1 method)
function run_inference(data, real_k, real_w, z_variance, y_variance)
+
+    autoupdates   = @autoupdates begin
+        zt_min_mean, zt_min_var = mean_var(q(zt))
+        xt_min_mean, xt_min_var = mean_var(q(xt))
+    end
+
+    return infer(
+        model         = hgf(real_k, real_w, z_variance, y_variance),
+        constraints   = hgfconstraints(),
+        meta          = hgfmeta(),
+        data          = (y = data, ),
+        autoupdates   = autoupdates,
+        keephistory   = length(data),
+        historyvars    = (
+            xt = KeepLast(),
+            zt = KeepLast()
+        ),
+        initmarginals = (
+            zt = NormalMeanVariance(0.0, 5.0),
+            xt = NormalMeanVariance(0.0, 5.0),
+        ), 
+        iterations    = 5,
+        free_energy   = true,
+        autostart     = true,
+        callbacks     = (
+            after_model_creation = (model, returnval) -> begin 
+                gcvnode = returnval
+                setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))
+            end,
+        )
+    )
+end
run_inference (generic function with 1 method)
result = run_inference(y, real_k, real_w, z_variance, y_variance);
+
+mz = result.history[:zt];
+mx = result.history[:xt];
let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = "estimated z_i", color = :teal)
+    
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = "estimated x_i", color = :violet)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:

plot(result.free_energy_history, label = "Bethe Free Energy")

As we can see BetheFreeEnergy converges nicely to a stable point.

At final, lets check the overall performance of our resulting Variational Message Passing algorithm:

@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)
BenchmarkTools.Trial: 44 samples with 1 evaluation.
+ Range (min … max):   90.900 ms … 158.543 ms  ┊ GC (min … max): 0.00% … 0.0
+0%
+ Time  (median):     111.841 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   115.239 ms ±  12.876 ms  ┊ GC (mean ± σ):  1.41% ± 2.9
+5%
+
+                    ██                                           
+  ▄▁▁▁▁▁▁▁▁▁▄▁▇▆▆▆▇▄██▄▁▁▁▄▄▄▆▄▁▁▄▁▁▁▁▁▄▁▁▁▁▁▁▄▁▁▄▁▁▁▁▁▁▁▁▄▁▁▁▄ ▁
+  90.9 ms          Histogram: frequency by time          159 ms <
+
+ Memory estimate: 18.78 MiB, allocs estimate: 456888.
diff --git a/dev/examples/problem_specific/Invertible Neural Network Tutorial/index.html b/dev/examples/problem_specific/Invertible Neural Network Tutorial/index.html new file mode 100644 index 000000000..619afd590 --- /dev/null +++ b/dev/examples/problem_specific/Invertible Neural Network Tutorial/index.html @@ -0,0 +1,293 @@ + +Invertible neural networks: a tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Invertible neural networks: a tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Table of contents

  1. Introduction
  2. Model specification
  3. Model compilation
  4. Probabilistic inference
  5. Parameter estimation

Introduction

Load required packages

Before we can start, we need to import some packages:

using RxInfer
+using Random
+using StableRNGs
+
+using ReactiveMP        # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality
+using LinearAlgebra     # only used for some matrix specifics
+using Plots             # only used for visualisation
+using Distributions     # only used for sampling from multivariate distributions
+using Optim             # only used for parameter optimisation

Model specification

Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as 

model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Alternatively, the input_dim can also be passed as an InputLayer layer as 

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

In the above AdditiveCouplingLayer layers the input ${\bf{x}} = [x_1, x_2, \ldots, x_N]$ is partitioned into chunks of unit length. These partitions are additively coupled to an output ${\bf{y}} = [y_1, y_2, \ldots, y_N]$ as

\[\begin{aligned} + y_1 &= x_1 \\ + y_2 &= x_2 + f_1(x_1) \\ + \vdots \\ + y_N &= x_N + f_{N-1}(x_{N-1}) +\end{aligned}\]

Importantly, this structure can easily be converted as

\[\begin{aligned} + x_1 &= y_1 \\ + x_2 &= y_2 - f_1(x_1) \\ + \vdots \\ + x_N &= y_N - f_{N-1}(x_{N-1}) +\end{aligned}\]

\[f_n\]

is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.

A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false),
+        PermutationLayer(PermutationMatrix(2)),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Model compilation

In the current models, the layers are setup to work with the passed input dimension. This means that the function $f_n$ is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get

model
FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P
+lanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa
+yerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou
+plingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar
+FlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad
+ditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive
+MP.PlanarFlowEmpty{1}(),), 1)))

The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):

  • FlowModel - specifies that we are dealing with a flow model.
  • 3 - Number of layers.
  • Tuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.
  • Tuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions $f_n$.
  • PermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].

From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as

compiled_model = compile(model)
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(-0.5530639593835304, -0.2163616
+102550308, 1.2521116434309154),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.34763211887023543, -0.9116171319236555, -0.0789378301
+24018),), 1)))

Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.

compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361
+28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323
+52386),), 1)))

Probabilistic inference

We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.

function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)
+
+    rng = StableRNG(seed)
+    
+    # specify latent sampling distribution
+    dist = MvNormal([1.5, 0.5], I)
+
+    # sample from the latent distribution
+    x = rand(rng, dist, nr_samples)
+
+    # transform data
+    y = zeros(Float64, size(x))
+    for k = 1:nr_samples
+        y[:,k] .= ReactiveMP.forward(model, x[:,k])
+    end
+
+    # return data
+    return y, x
+
+end;
# generate data
+y, x = generate_data(1000, compiled_model)
+
+# plot generated data
+p1 = scatter(x[1,:], x[2,:], alpha=0.3, title="Original data", size=(800,400))
+p2 = scatter(y[1,:], y[2,:], alpha=0.3, title="Transformed data", size=(800,400))
+plot(p1, p2, legend = false)

The probabilistic model for doing inference can be described as 

@model function invertible_neural_network(nr_samples::Int64)
+    
+    # initialize variables
+    z_μ   = randomvar()
+    z_Λ   = randomvar()
+    x     = randomvar(nr_samples)
+    y_lat = randomvar(nr_samples)
+    y     = datavar(Vector{Float64}, nr_samples)
+
+    # specify prior
+    z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))
+    z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)
+
+        # specify transformed latent value
+        y_lat[k] ~ Flow(x[k])
+
+        # specify observations
+        y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))
+
+    end
+
+    # return variables
+    return z_μ, z_Λ, x, y_lat, y
+
+end;

Here the model is passed inside a meta data object of the flow node. Inference then resorts to

observations = [y[:,k] for k=1:size(y,2)]
+
+fmodel         = invertible_neural_network(length(observations))
+data          = (y = observations, )
+initmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))
+returnvars    = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())
+
+constraints = @constraints begin
+    q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)
+end
+
+@meta function fmeta(model)
+    compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
+    Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). 
+                                               # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))
+end
+
+# First execution is slow due to Julia's initial compilation 
+result = infer(
+    model = fmodel, 
+    data  = data,
+    constraints   = constraints,
+    meta          = fmeta(model),
+    initmarginals = initmarginals,
+    returnvars    = returnvars,
+    free_energy   = true,
+    iterations    = 10, 
+    showprogress  = false
+)
Inference results:
+  Posteriors       | available for (z_μ, z_Λ, y_lat, x)
+  Free Energy:     | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357
+0.6, 23570.6, 23570.6, 23570.6, 23570.6]
fe_flow = result.free_energy
+zμ_flow = result.posteriors[:z_μ]
+zΛ_flow = result.posteriors[:z_Λ]
+x_flow  = result.posteriors[:x]
+y_flow  = result.posteriors[:y_lat];

As we can see, the variational free energy decreases inside of our model.

plot(1:10, fe_flow/size(y,2), xlabel="iteration", ylabel="normalized variational free energy [nats/sample]", legend=false)

If we plot a random noisy observation and its approximated transformed uncertainty we obtain:

# pick a random observation
+id = rand(StableRNG(321), 1:size(y,2))
+rand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))
+warped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');
+
+p1 = scatter(x[1,:], x[2,:], alpha=0.1, title="Latent distribution", size=(1200,500), label="generated data")
+contour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)
+scatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color="red", markershape=:x, markersize=5, label="inferred mean")
+contour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors="red", levels=1, linewidth=2, colorbar=false)
+scatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color="red", label="transformed noisy observation")
+p2 = scatter(y[1,:], y[2,:], alpha=0.1, label="generated data")
+scatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color="red", marker=:x, label="inferred mean")
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors="red", levels=1, linewidth=2, label="random noisy observation", colorba=false)
+scatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color="red", label="random noisy observation")
+plot(p1, p2, legend = true)

Parameter estimation

The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+
+    # sample weights
+    w = rand(rng, nr_samples, 2)
+
+    # sample appraisal
+    y = zeros(Float64, nr_samples)
+    for k = 1:nr_samples
+        y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)
+    end
+
+    # return data
+    return y, w
+
+end;
data_y, data_x = generate_data(50);
+scatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel="w1", ylabel="w2", colorbar=false, legend=false)

We will then specify a possible model as

# specify flow model
+model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

The corresponding probabilistic model for the binary classification task can be created as

@model function invertible_neural_network_classifier(nr_samples::Int64)
+    
+    # initialize variables
+    x_lat  = randomvar(nr_samples)
+    y_lat1 = randomvar(nr_samples)
+    y_lat2 = randomvar(nr_samples)
+    y      = datavar(Float64, nr_samples)
+    x      = datavar(Vector{Float64}, nr_samples)
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))
+
+        # specify transformed latent value
+        y_lat1[k] ~ Flow(x_lat[k])
+        y_lat2[k] ~ dot(y_lat1[k], [1, 1])
+
+        # specify observations
+        y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }
+
+    end
+
+    # return variables
+    return x_lat, x, y_lat1, y_lat2, y
+
+end;
fcmodel       = invertible_neural_network_classifier(length(data_y))
+data          = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )
+
+@meta function fmeta(model, params)
+    compiled_model = compile(model, params)
+    Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)
+end
fmeta (generic function with 2 methods)

Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as

For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.

function f(params)
+    Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure
+    result = infer(
+        model                   = fcmodel, 
+        data                    = data,
+        meta                    = fmeta(model, params),
+        free_energy             = true,
+        free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure
+        iterations              = 10, 
+        showprogress            = false
+    );
+    
+    result.free_energy[end]
+end;

Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:

res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)
  • uses finitediff and is slower/less accurate.

or

# create gradient function
+g = (x) -> ForwardDiff.gradient(f, x);
+
+# specify initial params
+params = randn(nr_params(model))
+
+# create custom optimizer (here Adam)
+optimizer = Adam(params; λ=1e-1)
+
+# allocate space for gradient
+∇ = zeros(nr_params(model))
+
+# perform optimization
+for it = 1:10000
+
+    # backward pass
+    ∇ .= ForwardDiff.gradient(f, optimizer.x)
+
+    # gradient update
+    ReactiveMP.update!(optimizer, ∇)
+
+end
+
res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)
Iter     Function value   Gradient norm 
+     0     5.888958e+02     8.943663e+02
+ * time: 0.015251874923706055
+   100     1.059826e+01     4.120090e+00
+ * time: 11.705296039581299
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.010332e+01
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.21e-03 ≰ 0.0e+00
+    |x - x'|/|x'|          = 5.80e-04 ≰ 0.0e+00
+    |f(x) - f(x')|         = 6.28e-03 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03
+    |g(x)|                 = 2.07e+00 ≰ 1.0e-08
+
+ * Work counters
+    Seconds run:   13  (vs limit Inf)
+    Iterations:    113
+    f(x) calls:    301
+    ∇f(x) calls:   301

optimization results are then given as

params = Optim.minimizer(res)
+inferred_model = compile(model, params)
+trans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'
+trans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])
+trans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title="original data")
+p2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title="|> warp")
+p3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title="|> dot")
+plot(p1, p2, p3, layout=(1,3), legend=false)

using StatsFuns: normcdf
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title="original labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title="predicted labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title="Classification map", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+plot(p1, p2, p3, layout=(1,3), legend=false)

diff --git a/dev/examples/problem_specific/Probit Model (EP)/index.html b/dev/examples/problem_specific/Probit Model (EP)/index.html new file mode 100644 index 000000000..0d003118c --- /dev/null +++ b/dev/examples/problem_specific/Probit Model (EP)/index.html @@ -0,0 +1,76 @@ + +Probit Model (EP) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Probit Model (EP)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable $x_t$ with the discrete variable $y_t$. The model is defined as:

\[\begin{aligned} + u &= 0.1 \\ + x_0 &\sim \mathcal{N}(0, 100) \\ + x_t &\sim \mathcal{N}(x_{t-1}+ u, 0.01) \\ + y_t &\sim \mathrm{Ber}(\Phi(x_t)) +\end{aligned}\]

Import packages

using RxInfer, StableRNGs, Random, Plots
+using StatsFuns: normcdf

Data generation

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+    
+    # hyper parameters
+    u = 0.1
+
+    # allocate space for data
+    data_x = zeros(nr_samples + 1)
+    data_y = zeros(nr_samples)
+    
+    # initialize data
+    data_x[1] = -2
+    
+    # generate data
+    for k = 2:nr_samples + 1
+        
+        # calculate new x
+        data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)
+        
+        # calculate y
+        data_y[k-1] = normcdf(data_x[k]) > rand(rng)
+        
+    end
+    
+    # return data
+    return data_x, data_y
+    
+end;
n = 40
40
data_x, data_y = generate_data(n);
p = plot(xlabel = "t", ylabel = "x, y")
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x")

Model specification

@model function probit_model(nr_samples::Int64)
+    
+    # allocate space for variables
+    x = randomvar(nr_samples + 1)
+    y = datavar(Float64, nr_samples)
+    
+    # specify uninformative prior
+    x[1] ~ Normal(mean = 0.0, precision = 0.01)
+    
+    # create model 
+    for k = 2:nr_samples + 1
+        x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)
+        y[k - 1] ~ Probit(x[k]) where {
+            # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge
+            # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations
+            pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) 
+        }
+    end
+    
+end;

Inference

result = infer(
+    model = probit_model(length(data_y)), 
+    data  = (y = data_y, ), 
+    iterations = 5, 
+    returnvars = (x = KeepLast(),),
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (x)
+  Free Energy:     | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]

Results

mx = result.posteriors[:x]
+
+p = plot(xlabel = "t", ylabel = "x, y", legend = :bottomright)
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x", lw = 2)
+p = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label="x (inferred mean)")
+
+f = plot(xlabel = "t", ylabel = "BFE")
+f = plot!(result.free_energy, label = "Bethe Free Energy")
+
+plot(p, f, size = (800, 400))

diff --git a/dev/examples/problem_specific/RTS vs BIFM Smoothing/index.html b/dev/examples/problem_specific/RTS vs BIFM Smoothing/index.html new file mode 100644 index 000000000..bcc06157d --- /dev/null +++ b/dev/examples/problem_specific/RTS vs BIFM Smoothing/index.html @@ -0,0 +1,242 @@ + +RTS vs BIFM Smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

RTS vs BIFM Smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

___Credits to Martin de Quincey___

This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:

  1. F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762
  2. H. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.

We perform Kalman smoothing in the linear state space model, represented by:

\[\begin{aligned} + Z_{k+1} &= A Z_k + B U_k \\ + Y_k &= C Z_k + W_k +\end{aligned}\]

with observations $Y_k$, latent states $Z_k$ and inputs $U_k$. $W_k$ is the observation noise. $A \in \mathrm{R}^{n \times n}$, $B \in \mathrm{R}^{n \times m}$ and $C \in \mathrm{R}^{d \times n}$ are the transition matrices in the model. Here $n$, $m$ and $d$ denote the dimensionality of the latent, input and output dimension, respectively.

The corresponding probabilistic model can be represented as

\[\begin{aligned} + p(y,\ z,\ u) + &= p(z_0) \prod_{k=1}^N p(y_k \mid z_k)\ p(z_k\mid z_{k-1},\ u_{k-1})\ p(u_{k-1}) \\ + &= \mathcal{N}(z_0 \mid \mu_{z_0}, \Sigma_{z_0}) \left( \prod_{k=1}^N \mathcal{N}(y_k \mid C z_k,\ \Sigma_W)\ \delta(z_k - (Az_{k-1} + Bu_{k-1})) \mathcal{N}(u_{k-1} \mid \mu_{i_{k-1}},\ \Sigma_{u_{k-1}}) \right) +\end{aligned}\]

Import packages

using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs

Data generation

function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)
+    
+    # define noise levels
+    input_noise  = 500.0
+    output_noise = 50.0
+
+    # create random generator for reproducibility
+    rng = MersenneTwister(seed)
+
+    # generate matrices, input statistics and noise matrices
+    A      = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat))                                            # size (dim_lat x dim_lat)
+    B      = rand(dim_lat, dim_in)                                                                              # size (dim_lat x dim_in)
+    C      = rand(dim_out, dim_lat)                                                                             # size (dim_out x dim_lat)
+    μu     = rand(dim_in) .* collect(1:dim_in)                                                                  # size (dim_in x 1)
+    Σu     = input_noise  .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in))))      # size (dim_in x dim_in)
+    Σy     = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out))))   # size (dim_out x dim_out)
+    Wu     = inv(Σu)
+    Wy     = inv(Σy)
+    
+    # return parameters
+    return A, B, C, μu, Σu, Σy, Wu, Wy
+
+end;
function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)
+        
+    # create random data generator
+    rng = StableRNG(seed)
+    
+    # preallocate space for variables
+    z = Vector{Vector{Float64}}(undef, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+    u = rand(rng, MvNormal(μu, Σu), nr_samples)'
+    
+    # set initial value of latent states
+    z_prev = zeros(size(A,1))
+    
+    # generate data
+    for i in 1:nr_samples
+
+        # generate new latent state
+        z[i] = A * z_prev + B * u[i,:]
+
+        # generate new observation
+        y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))
+        
+        # generate new observation
+        z_prev .= z[i]
+        
+    end
+    
+    # return generated data
+    return z, y, u
+    
+end
generate_data (generic function with 1 method)
# specify settings
+nr_samples = 200
+dim_out = 3
+dim_in = 3
+dim_lat = 25
+
+# generate parameters
+A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);
+            
+# generate data
+data_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);
+
+# visualise data
+p = Plots.plot(xlabel = "sample", ylabel = "observations")
+# plot each dimension independently
+for i in 1:dim_out
+    Plots.scatter!(p, getindex.(data_y, i), label = "y_$i", alpha = 0.5, ms = 2)
+end
+p

Model specification

@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+    
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    dim_out = size(C, 1)
+    
+    # initialize variables
+    z = randomvar(nr_samples)                 # hidden states (random variable)
+    u = randomvar(nr_samples)                 # inputs (random variable)
+    y = datavar(Vector{Float64}, nr_samples)  # outputs (observed variables)
+    
+    # set initial hidden state
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    
+    # update last/previous hidden state
+    z_prev = z_prior
+
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i] ~ MvNormalMeanPrecision(μu, Wu)
+        
+        # specify updated hidden state
+        z[i] ~ A * z_prev + B * u[i]
+        
+        # specify observation
+        y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+end
@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    
+    # initialize variables
+    z  = randomvar(nr_samples)                  # latent states
+    yt = randomvar(nr_samples)                  # latent observations
+    y  = datavar(Vector{Float64}, nr_samples)   # actual observations
+    u  = randomvar(nr_samples)                  # inputs
+    
+    # set priors
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    z_tmp   ~ BIFMHelper(z_prior) where { q = MeanField() }
+    
+    # update last/previous hidden state
+    z_prev = z_tmp
+    
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i]   ~ MvNormalMeanPrecision(μu, Wu)
+
+        # specify observation
+        yt[i]  ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }
+        y[i]   ~ MvNormalMeanPrecision(yt[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+    # set final value
+    z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))
+    
+end

Probabilistic inference

function inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+    
+    # In this task the inference is unstable and can diverge
+    meta = @meta begin 
+        *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)
+    end
+    
+    result = infer(
+        model      = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast()),
+        meta = meta
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_RTS (generic function with 1 method)
function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)
+    result = infer(
+        model      = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast())
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_BIFM (generic function with 1 method)

Experiments for 200 observations

z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+z_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);
ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state z")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state z")
+
+mz_RTS = mean.(z_RTS)
+mz_BIFM = mean.(z_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:5
+    Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state u")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state u")
+
+rdata_u = collect(eachrow(data_u))
+mu_RTS = mean.(u_RTS)
+mu_BIFM = mean.(u_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:1
+    Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

Benchmark

# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation
+# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`
+run_benchmark = false
+
+if run_benchmark
+    trials_range = 30
+    trials_n = 500
+    trials_RTS  = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+    trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+
+
+    @showprogress for k = 1 : trials_range
+
+        # generate parameters
+        local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);
+                    
+        # generate data|
+        local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);
+
+        # run inference
+        trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+        trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+
+    end
+
+    m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9
+    q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9
+    m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9
+    q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;
+
+    p = Plots.plot(ylabel = "duration [sec]", xlabel = "latent state dimension", title = "Benchmark", yscale = :log)
+    p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = "blue", label = "mean (RTS)")
+    p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = "orange", label = "mean (BIFM)")
+    Plots.savefig(p, "../pics/rts_bifm_benchmark.png")
+    p
+end

diff --git a/dev/examples/problem_specific/Simple Nonlinear Node/index.html b/dev/examples/problem_specific/Simple Nonlinear Node/index.html new file mode 100644 index 000000000..486c49571 --- /dev/null +++ b/dev/examples/problem_specific/Simple Nonlinear Node/index.html @@ -0,0 +1,67 @@ + +Simple Nonlinear Node · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Simple Nonlinear Node

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, StableRNGs

Here is an example of creating custom node with nonlinear function approximation with samplelist.

Custom node creation

struct NonlinearNode end # Dummy structure just to make Julia happy
+
+struct NonlinearMeta{R, F}
+    rng      :: R
+    fn       :: F   # Nonlinear function, we assume 1 float input - 1 float output
+    nsamples :: Int # Number of samples used in approximation
+end
@node NonlinearNode Deterministic [ out, in ]

We need to define two Sum-product message computation rules for our new custom node

  • Rule for outbound message on out edge given inbound message on in edge
  • Rule for outbound message on in edge given inbound message on out edge
  • Both rules accept optional meta object
# Rule for outbound message on `out` edge given inbound message on `in` edge
+@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin 
+    samples = rand(meta.rng, m_in, meta.nsamples)
+    return SampleList(map(meta.fn, samples))
+end
# Rule for outbound message on `in` edge given inbound message on `out` edge
+@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin     
+    return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))
+end

Model specification

After we have defined our custom node with custom rules we may proceed with a model specification:

\[\begin{aligned} +p(\theta) &= \mathcal{N}(\theta|\mu_{\theta}, \sigma_{\theta}),\\ +p(m) &= \mathcal{N}(\theta|\mu_{m}, \sigma_{m}),\\ +p(w) &= f(\theta),\\ +p(y_i|m, w) &= \mathcal{N}(y_i|m, w), +\end{aligned}\]

Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable $\theta$ through a non-linear transformation $f$ to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of $\theta$. 

@model function nonlinear_estimation(n)
+    
+    θ ~ Normal(mean = 0.0, variance = 100.0)
+    m ~ Normal(mean = 0.0, variance = 1.0)
+    
+    w ~ NonlinearNode(θ)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = m, precision = w)
+    end
+    
+end
@constraints function nconstsraints(nsamples)
+    q(θ) :: SampleList(nsamples, LeftProposal())
+    q(w) :: SampleList(nsamples, RightProposal())
+    
+    q(θ, w, m) = q(θ)q(m)q(w)
+end
nconstsraints (generic function with 1 method)
@meta function nmeta(fn, nsamples)
+    NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)
+end
nmeta (generic function with 1 method)

Here we generate some data

nonlinear_fn(x) = abs(exp(x) * sin(x))
nonlinear_fn (generic function with 1 method)
seed = 123
+rng  = StableRNG(seed)
+
+niters   = 15 # Number of VMP iterations
+nsamples = 5_000 # Number of samples in approximation
+
+n = 500 # Number of IID samples
+μ = -10.0
+θ = -1.0
+w = nonlinear_fn(θ)
+
+data = rand(rng, NormalMeanPrecision(μ, w), n);
result = infer(
+    model = nonlinear_estimation(n),
+    meta =  nmeta(nonlinear_fn, nsamples),
+    constraints = nconstsraints(nsamples),
+    data = (y = data, ), 
+    initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),
+    returnvars = (θ = KeepLast(), ),
+    iterations = niters,  
+    showprogress = true
+)
Inference results:
+  Posteriors       | available for (θ)
θposterior = result.posteriors[:θ]
SampleList(Univariate, 5000)
using Plots, StatsPlots
+
+estimated = Normal(mean_std(θposterior)...)
+
+plot(estimated, title="Posterior for θ", label = "Estimated", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))
+vline!([ θ ], label = "Real value of θ")

diff --git a/dev/examples/problem_specific/Universal Mixtures/index.html b/dev/examples/problem_specific/Universal Mixtures/index.html new file mode 100644 index 000000000..053850d32 --- /dev/null +++ b/dev/examples/problem_specific/Universal Mixtures/index.html @@ -0,0 +1,94 @@ + +Universal Mixtures · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Universal Mixtures

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Distributions, Random, Plots

John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment

\[p(y_i \mid \theta) = \mathrm{Ber}(y_i \mid \theta),\]

where $y_i \in \{0,1\}$ are the outcomes of the coin tosses, i.e. heads or tails, and where $\theta$ is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter $\theta$, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of $\theta\in[0,1]$ they come up with the prior beliefs:

\[p(\theta \mid \text{John}) = \mathrm{Beta}(\theta \mid 7, 2)\]

\[p(\theta \mid \text{Jane}) = \mathrm{Beta}(\theta \mid 2, 7)\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior beliefs")
+plot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label="P(θ) John", c=1)
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="p(θ) Jane", c=3,)

John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. 

true_coin = Bernoulli(0.25)
+nr_throws = 10
+dataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))
+nr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)
+println("experimental outcome: \n - heads: ", nr_heads, "\n - tails: ", nr_tails);
experimental outcome: 
+ - heads: 3
+ - tails: 7

For computing the posterior beliefs $p(\theta \mid y)$ about the parameter $\theta$, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:

John's model:

\[p(y, \theta \mid \text{John}) = p(\theta \mid \text{John}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_john(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's prior model over θ
+    θ ~ Beta(7.0, 2.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Jane's model:

\[p(y, \theta \mid \text{Jane}) = p(\theta \mid \text{Jane}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_jane(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify Jane's prior model over θ
+    θ ~ Beta(2.0, 7.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy $\mathrm{F}_B$ bounds the model evidence $p(y)$ as

\[\mathrm{F}_B[p,q] \geq - \ln p(y)\]

result_john = infer(
+    model = beta_model_john(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true,
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[8.96366]
result_jane = infer(
+    model = beta_model_jane(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[6.63988]

From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying $\theta$ parameter. They formulate this through the posterior distributions $p(\theta \mid y, \text{John})$ and $p(\theta \mid y, \text{Jane})$:

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior beliefs")
+plot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) John", c=1)
+plot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="p(θ|y) Jane", c=3,)

What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over $\theta$, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as

\[p(y, \theta, c \mid \text{Mary}) = p(c \mid \text{Mary}) \, p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} \prod_{i=1}^N p(y_i \mid \theta),\]

where $c$ describes the probability of John being correct as

\[p(c \mid \text{Mary}) = \mathrm{Ber}(c \mid 0.7)\]

The predictive distribution $p(\theta \mid \text{Mary})$ for $\theta$ (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over $c$ as

\[p(\theta \mid \text{Mary}) = \sum_{c\in\{0,1\}} p(c\mid\text{Mary}) p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} = 0.7 \cdot p(\theta \mid \text{John}) + 0.3 \cdot p(\theta \mid \text{Jane})\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior belief")
+plot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label="P(θ) Mary", c=1)
+plot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label="")
+plot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label="")

She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:

@model function beta_model_mary(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's and Jane's prior models over θ
+    θ_jane ~ Beta(2.0, 7.0)
+    θ_john ~ Beta(7.0, 2.0)
+
+    # specify initial guess as to who is right
+    john_is_right ~ Bernoulli(0.7) 
+
+    # specify mixture prior Distribution
+    θ ~ Mixture(john_is_right, (θ_jane, θ_john))
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

This Mixture node updates the belief over $c$ on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.

result_mary = infer(
+    model = beta_model_mary(nr_throws), 
+    data  = (y = dataset, ),
+    returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),
+    addons = AddonLogScale(),
+    postprocess = UnpackMarginalPostprocess(),
+)
Inference results:
+  Posteriors       | available for (john_is_right, θ_john, θ, θ_jane)

Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over $\theta$ also changed, and as expected the estimate from Jane was more prominent.

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior belief")
+plot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) Mary", c=1)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label="", c=3)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label="", c=3)

diff --git a/dev/examples/problem_specific/overview/index.html b/dev/examples/problem_specific/overview/index.html new file mode 100644 index 000000000..221dec01e --- /dev/null +++ b/dev/examples/problem_specific/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Problem specific

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Problem specific examples contain specialized models and inference for various domains.

diff --git a/dev/index.html b/dev/index.html new file mode 100644 index 000000000..3616f2d4b --- /dev/null +++ b/dev/index.html @@ -0,0 +1,2 @@ + +Home · RxInfer.jl
GitHub

RxInfer

Julia package for automatic Bayesian inference on a factor graph with reactive message passing.

Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.

Package Features

  • User friendly syntax for specification of probabilistic models.
  • Automatic generation of message passing algorithms including
  • Support for hybrid models combining discrete and continuous latent variables.
  • Support for hybrid distinct message passing inference algorithm under a unified paradigm.
  • Factorisation and functional form constraints specification.
  • Evaluation of Bethe free energy as a model performance measure.
  • Schedule-free reactive message passing API.
  • High performance.
  • Scalability for large models with millions of parameters and observations.
  • Inference procedure is differentiable.
  • Easy to extend with custom nodes and message update rules.

Why RxInfer

Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a "variational Free Energy" cost function. For large models, manual derivation of these gradients might not be feasible, while automated "black-box" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.

RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different "what-if" scenarios and enables very efficient inference in specific cases.

Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.

How to get started?

Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.

Table of Contents

References

Ecosystem

The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:

  • ReactiveMP.jl - core package for efficient and scalable for reactive message passing
  • GraphPPL.jl - package for model and constraints specification
  • Rocket.jl - reactive programming tools

Index

diff --git a/dev/library/bethe-free-energy/index.html b/dev/library/bethe-free-energy/index.html new file mode 100644 index 000000000..1ca8be3d9 --- /dev/null +++ b/dev/library/bethe-free-energy/index.html @@ -0,0 +1,2 @@ + +Bethe Free Energy · RxInfer.jl
GitHub

Bethe Free Energy implementation in RxInfer

The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.

Factorized model

Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, $y = (y_1, \dots, y_j, \dots, y_m)\,,$ and variables that can not be observed directly, also known as latent variables, $x = (x_1, \dots, x_i, \dots, x_n)\,.$ We then define a model that factorizes over consituent smaller factors (functions), as $f(y,x) = \prod_a f_a(y_a,x_a)\,.$

Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).

Variational Free Energy

The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, $F[q](\hat{y}) = \mathbb{E}_{q(x)}\left[\log \frac{q(x)}{f(y=\hat{y}, x)} \right]\,.$ A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.

The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.

Variational inference

The goal of variational inference is to find a variational distibution that minimizes the VFE, $q^{*}(x) = \arg\min_{q\in\mathcal{Q}} F[q](\hat{y})\,.$ This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.

For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.

Bethe approximation

Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.

A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, $q(x) \triangleq \frac{\prod_a q_a(x_a)}{\prod_i q_i(x_i)^{d_i - 1}}\,.$ The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.

The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.

The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.

Bethe Free Energy

The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as $F_B[q](\hat{y}) = \sum_a U_a[q_a](\hat{y}_a) - \sum_a H[q_a] + \sum_i (d_i - 1) H[q_i]\,.$ The first term of the BFE specifies an average energy, $U_a[q_a](\hat{y}_a) = -\mathbb{E}_{q_a(x_a)}\left[\log f_a(y_a=\hat{y}_a, x_a)\right]\,,$ which internalizes the factors of the model. The last two terms specify entropies.

Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.

For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.

For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.

Further reading

  • Pearl (1986) on the original foundations of Bayesian networks and belief propagation;
  • Yedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;
  • Dauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);
  • Senoz et al. (2021) on constraint manipulation and message passing on FFGs.
RxInfer.AbstractScoreObjective — Type
AbstractScoreObjective

Abstract type for functional objectives that can be used in the score function.

Note

score is defined in the ReactiveMP package.

source
RxInfer.BetheFreeEnergy — Type
BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)

Creates Bethe Free Energy values stream when passed to the score function.

source
RxInfer.apply_diagnostic_check — Function
apply_diagnostic_check(check, context, stream)

This function applies a check to the stream. Accepts optional context object for custom error messages.

source
diff --git a/dev/library/exported-methods/index.html b/dev/library/exported-methods/index.html new file mode 100644 index 000000000..bf98747c0 --- /dev/null +++ b/dev/library/exported-methods/index.html @@ -0,0 +1,860 @@ + +Exported methods · RxInfer.jl
GitHub

Using methods from RxInfer

In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:

using RxInfer

A nice explanation about how modules/packages work in Julia can be found in the official documentation.

In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:

import RxInfer: mean

One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:

import RxInfer: mean as mean_from_rxinfer
+import Distributions: mean as mean_from_distributions
+
+mean_from_rxinfer === mean_from_distributions
true

Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.

# It is easier to let Julia resolve names automatically
+# Julia will not overwrite `mean` that is coming from both packages
+using RxInfer, Distributions
mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`
0.0
mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`
0.0

List of available methods

Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.

Note

Some exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.

foreach(println, names(RxInfer))
@autoupdates
+@average_energy
+@call_marginalrule
+@call_rule
+@constraints
+@logscale
+@marginalrule
+@meta
+@model
+@node
+@rule
+AND
+AR
+ARMeta
+ARsafe
+ARunsafe
+AbstractActor
+AbstractActorFactory
+AbstractApproximationMethod
+AbstractFormConstraint
+AbstractMStorage
+AbstractMessage
+AbstractMixtureModel
+AbstractMvNormal
+AbstractOperator
+AbstractPipelineStage
+AbstractSubject
+AbstractSubjectFactory
+AbstractSubscribable
+AbstractVariable
+Actor
+ActorProxy
+ActorSourceProxy
+ActorTrait
+Adam
+AdditiveCouplingLayer
+AddonDebug
+AddonLogScale
+AddonMemory
+Arcsine
+ArrayLikeVariate
+ArrayObservable
+AsapScheduler
+AsyncPipelineStage
+AsyncScheduler
+AutoProposal
+AutoVar
+Autoregressive
+AverageEnergy
+BIFM
+BIFMHelper
+BIFMMeta
+BaseActorTrait
+BayesBase
+BehaviorSubject
+BehaviorSubjectFactory
+Bernoulli
+BernoulliLogit
+Beta
+BetaBinomial
+BetaPrime
+BetheFreeEnergy
+BetheFreeEnergyCheckInfs
+BetheFreeEnergyCheckNaNs
+BetheFreeEnergyDefaultChecks
+BetheFreeEnergyDefaultMarginalSkipStrategy
+Binomial
+Biweight
+BufferActor
+CTMeta
+CTransition
+CVI
+CallableTeardownLogic
+Categorical
+Cauchy
+Chernoff
+Chi
+Chisq
+CholeskyVariate
+CircularKeepActor
+ClosedProd
+CompanionMatrix
+CompanionMatrixTransposed
+CompiledFlowModel
+CompletedObservable
+CompletionActor
+CompletionActorTrait
+CompositeFormConstraint
+CompositePipelineStage
+ConnectableObservable
+ConstVariable
+ConstantBaseMeasure
+ConstraintsSpecification
+Contingency
+Continuous
+ContinuousDistribution
+ContinuousMatrixDistribution
+ContinuousMultivariateDistribution
+ContinuousMultivariateLogPdf
+ContinuousTransition
+ContinuousTransitionMeta
+ContinuousUnivariateDistribution
+ContinuousUnivariateLogPdf
+Cosine
+CountingReal
+CustomProdStrategy
+DataVariable
+DefaultConstraints
+DefaultMeta
+DefaultPostprocess
+DeltaFn
+DeltaFnNode
+DeltaMeta
+Deterministic
+DiagNormal
+DiagNormalCanon
+DifferentialEntropy
+Dirac
+Dirichlet
+DirichletMultinomial
+DiscontinuePipelineStage
+Discrete
+DiscreteDistribution
+DiscreteMatrixDistribution
+DiscreteMultivariateDistribution
+DiscreteNonParametric
+DiscreteUniform
+DiscreteUnivariateDistribution
+Distribution
+Distributions
+Domain
+DoubleExponential
+EdgeworthMean
+EdgeworthSum
+EdgeworthZ
+EmptyPipelineStage
+Epanechnikov
+Erlang
+ErrorActor
+ErrorActorTrait
+Estimator
+Exponential
+ExponentialFamily
+ExponentialFamilyDistribution
+ExponentialFamilyDistributionAttributes
+ExtraArgumentInCompleteCall
+FDist
+FactorBoundFreeEnergy
+FactorGraphModel
+FactorNodeCreationOptions
+FactorNodesCollection
+FactorizedJoint
+FastCholesky
+FaultedObservable
+FirstNotFoundException
+FisherNoncentralHypergeometric
+Flow
+FlowMeta
+FlowModel
+FoldLeftProdStrategy
+FoldRightProdStrategy
+FormConstraintCheckEach
+FormConstraintCheckLast
+FormConstraintCheckPickDefault
+ForwardDiffGrad
+Frechet
+FullFactorisation
+FullNormal
+FullNormalCanon
+FunctionActor
+FunctionObservable
+GCV
+GCVMetadata
+Gamma
+GammaDistributionsFamily
+GammaInverse
+GammaMixture
+GammaMixtureNode
+GammaShapeRate
+GammaShapeScale
+GaussHermiteCubature
+GaussLaguerreQuadrature
+GaussianDistributionsFamily
+GaussianMeanPrecision
+GaussianMeanVariance
+GaussianMixture
+GaussianMixtureNode
+GaussianWeighteMeanPrecision
+GeneralizedExtremeValue
+GeneralizedPareto
+GenericProd
+Geometric
+GraphPPL
+Gumbel
+HalfNormal
+Hypergeometric
+IMPLY
+ImportanceSamplingApproximation
+IncludeAll
+InconsistentActorWithSubscribableDataTypesError
+InconsistentSourceActorDataTypesError
+InconsistentSourceOperatorDataTypesError
+InconsistentSubjectDataTypesError
+InferableOperator
+InferableOperatorTrait
+InferenceResult
+InputLayer
+InvalidActorTrait
+InvalidActorTraitUsageError
+InvalidMultipleTeardownLogicTraitUsageError
+InvalidOperatorTrait
+InvalidOperatorTraitUsageError
+InvalidSubjectTrait
+InvalidSubjectTraitUsageError
+InvalidSubscribableTrait
+InvalidSubscribableTraitUsageError
+InvalidTeardownLogic
+InvalidTeardownLogicTraitUsageError
+InverseGamma
+InverseGaussian
+InverseWishart
+IsoNormal
+IsoNormalCanon
+JohnsonSU
+JointGaussian
+JointNormal
+JointOrderStatistics
+KSDist
+KSOneSided
+KeepActor
+KeepEach
+KeepLast
+Kolmogorov
+Kumaraswamy
+LKJ
+LKJCholesky
+LabeledObservable
+LambdaActor
+Laplace
+LaplaceApproximation
+LastNotFoundException
+LazyObservable
+LeftProposal
+LeftTypedOperator
+LeftTypedOperatorTrait
+Levy
+LimitSubscribersGuard
+Lindley
+Linearization
+LinearizedProductOf
+LocationScale
+LogNormal
+LogUniform
+LoggerActor
+LoggerPipelineStage
+Logistic
+LogitNormal
+MAX_PREGENERATED_MSTORAGE_SIZE
+MILLISECONDS_IN_SECOND
+MLEstimator
+Marginal
+Marginalisation
+MatrixBeta
+MatrixDirichlet
+MatrixDistribution
+MatrixFDist
+MatrixNormal
+MatrixReshaped
+MatrixTDist
+Matrixvariate
+MeanField
+MeanParametersSpace
+MeanToNatural
+Message
+MetaSpecification
+MissingCreateActorFactoryImplementationError
+MissingDataArgumentInNextCall
+MissingErrorArgumentInErrorCall
+MissingOnCallImplementationError
+MissingOnCompleteImplementationError
+MissingOnErrorImplementationError
+MissingOnNextImplementationError
+MissingOnScheduledSubscribeImplementationError
+MissingOnSubscribeImplementationError
+MissingOnUnsubscribeImplementationError
+MissingOperatorRightImplementationError
+Mixture
+MixtureDistribution
+MixtureModel
+MixtureNode
+MomentMatching
+Multinomial
+Multivariate
+MultivariateDistribution
+MultivariateGaussianDistributionsFamily
+MultivariateMixture
+MultivariateNormal
+MultivariateNormalDistributionsFamily
+MvGaussianMeanCovariance
+MvGaussianMeanPrecision
+MvGaussianWeightedMeanPrecision
+MvLogNormal
+MvLogitNormal
+MvNormal
+MvNormalCanon
+MvNormalKnownCov
+MvNormalMeanCovariance
+MvNormalMeanPrecision
+MvNormalMeanScalePrecision
+MvNormalWeightedMeanPrecision
+MvNormalWishart
+MvTDist
+NANOSECONDS_IN_MILLISECOND
+NANOSECONDS_IN_SECOND
+NOT
+NaturalParametersSpace
+NaturalToMean
+NegativeBinomial
+NetworkObservable
+NeverObservable
+NextActor
+NextActorTrait
+NonConstantBaseMeasure
+NonMatrixDistribution
+NoncentralBeta
+NoncentralChisq
+NoncentralF
+NoncentralHypergeometric
+NoncentralT
+NoopPostprocess
+Normal
+NormalCanon
+NormalDistributionsFamily
+NormalGamma
+NormalInverseGaussian
+NormalMeanPrecision
+NormalMeanVariance
+NormalMixture
+NormalMixtureNode
+NormalWeightedMeanPrecision
+OR
+OperatorTrait
+OperatorsComposition
+OrderStatistic
+OverrideHandler
+PGeneralizedGaussian
+Pareto
+PendingScheduler
+PendingSubject
+PendingSubjectFactory
+PermutationLayer
+PermutationMatrix
+PlanarFlow
+PointMass
+Poisson
+PoissonBinomial
+PostponeScheduler
+PreserveTypeLeftProd
+PreserveTypeProd
+PreserveTypeRightProd
+Probit
+ProbitMeta
+ProdCVI
+Product
+ProductOf
+ProxyObservable
+PushEach
+PushEachBut
+PushNew
+PushNewBut
+PushStrategy
+QQPair
+RadialFlow
+RandomVariable
+RandomVariableCreationOptions
+Rayleigh
+ReactiveMP
+RealInterval
+RecentSubject
+RecentSubjectFactory
+ReplaySubject
+ReplaySubjectFactory
+Rician
+RightProposal
+RightTypedOperator
+RightTypedOperatorTrait
+Rocket
+RxInfer
+RxInferenceEngine
+RxInferenceEvent
+SampleList
+SampleListMeta
+Sampleable
+ScheduledSubscribable
+ScheduledSubscribableTrait
+Semicircle
+ServerActor
+SimpleSubscribableTrait
+SingleObservable
+Skellam
+SkewNormal
+SkewedExponentialPower
+SkipClamped
+SkipClampedAndInitial
+SkipInitial
+SoftDot
+Soliton
+SourceProxy
+StandardBasisVector
+Stochastic
+StorageActor
+StudentizedRange
+Subject
+SubjectFactory
+SubjectTrait
+Subscribable
+SubscribableTrait
+SubstituteHandler
+SufficientStats
+SymTriangularDist
+SyncActor
+SyncActorTimedOutException
+SyncFileObservable
+TDist
+TapAfterSubscription
+TapAfterUnsubscription
+TapBeforeSubscription
+TapBeforeUnsubscription
+Teardown
+TeardownLogic
+TerminalProdArgument
+TimerObservable
+Transition
+TriangularDist
+Triweight
+Truncated
+TruncatedNormal
+TypedOperator
+TypedOperatorTrait
+UT
+Uniform
+Uninformative
+Univariate
+UnivariateDistribution
+UnivariateGMM
+UnivariateGaussianDistributionsFamily
+UnivariateMixture
+UnivariateNormalDistributionsFamily
+UnpackMarginalPostprocess
+Unscented
+UnscentedTransform
+UnspecifiedConstraints
+UnspecifiedDimension
+UnspecifiedDomain
+UnspecifiedFormConstraint
+UnspecifiedMeta
+UnsubscribableTeardownLogic
+ValidSubjectTrait
+ValueSupport
+VariableBoundEntropy
+VariablesCollection
+VariateForm
+VariationalMessage
+VoidActor
+VoidTeardown
+VoidTeardownLogic
+VonMises
+VonMisesFisher
+WalleniusNoncentralHypergeometric
+Weibull
+Wishart
+WishartDistributionsFamily
+ZeroMeanDiagNormal
+ZeroMeanDiagNormalCanon
+ZeroMeanFullNormal
+ZeroMeanFullNormalCanon
+ZeroMeanIsoNormal
+ZeroMeanIsoNormalCanon
+accumulated
+actor_extract_type
+actor_proxy!
+apply_pipeline_stage
+approximation_name
+approximation_short_name
+as_actor
+as_marginal
+as_message
+as_operator
+as_subject
+as_subscribable
+as_teardown
+as_variable
+async
+basemeasure
+buffer
+call_operator!
+call_operator_composition!
+canonform
+catch_error
+ccdf
+cdf
+censored
+cf
+cgf
+cholinv
+cholinv_logdet
+chollogdet
+cholsqrt
+circularkeep
+circvar
+clamplog
+collectLatest
+combineLatest
+combineLatestUpdates
+compile
+complete!
+completed
+component
+components
+componentwise_logpdf
+componentwise_pdf
+compute_logscale
+concat
+concat_map
+concat_map_to
+concentration
+connect
+connectable
+constrain_form
+constvar
+convert_paramfloattype
+convolve
+cor
+count
+cov
+cquantile
+create_actor
+create_model
+create_subject
+datavar
+debounce_time
+deep_eltype
+default_form_check_strategy
+default_if_empty
+default_prod_constraint
+default_prod_rule
+defer
+degree
+delay
+diageye
+dim
+dimension
+discontinue
+distribution_typewrapper
+dof
+dot
+dtanh
+entropy
+enumerate
+error!
+error_if
+error_if_empty
+error_if_not
+estimate
+exhaust_map
+expected_logdet
+factorisation
+failprob
+fastcholesky
+fastcholesky!
+faulted
+file
+filter
+filter_type
+find
+find_index
+first
+fisherinformation
+fit
+fit_mle
+from
+functional_dependencies
+functionalform
+fuse_supports
+generate
+getapproximation
+getattributes
+getbasemeasure
+getconditioner
+getconst
+getconstant
+getconstraints
+getdata
+getfisherinformation
+getgradlogpartition
+getlayers
+getlogpartition
+getlogscale
+getmapping
+getmarginal
+getmarginals
+getmemory
+getmeta
+getmodel
+getnaturalparameters
+getnode_ids
+getnodes
+getoptions
+getprediction
+getpredictions
+getrandom
+getsufficientstatistics
+getsupport
+getvalues
+getvardict
+getvariables
+ghcubature
+gradlogpartition
+gradlogpdf
+hasconstvar
+hasdatavar
+hasfinitesupport
+hasrandomvar
+huge
+ignore
+infer
+inference
+insupport
+interfaces
+interval
+invcov
+invlogccdf
+invlogcdf
+invscale
+is_clamped
+is_initial
+is_marginalisation
+is_moment_matching
+is_point_mass_form_constraint
+isbasemeasureconstant
+isbounded
+isconnected
+isdeterministic
+isequal_typeof
+isleptokurtic
+islowerbounded
+ismesokurtic
+isplatykurtic
+isprobvec
+isproper
+isstochastic
+isupperbounded
+iterable
+keep
+kldivergence
+kurtosis
+labeled
+lambda
+laplace
+last
+lazy
+limit_subscribers
+localmarginalnames
+localmarginals
+location
+location!
+logccdf
+logcdf
+logdetcov
+logdiffcdf
+logger
+loglikelihood
+logmvbeta
+logpartition
+logpdf
+logpdf!
+logpdf_optimized
+logpdf_sampling_optimized
+lowercase
+make
+make_form_constraint
+make_node
+map
+map_to
+marginalrule
+max
+mean
+mean_cov
+mean_invcov
+mean_precision
+mean_std
+mean_var
+meandir
+meanform
+meanlogx
+median
+merge_map
+merged
+metadata
+mgf
+min
+mirrorlog
+mode
+model_name
+modes
+moment
+multicast
+mvtrigamma
+name
+ncategories
+ncomponents
+network
+never
+next!
+noop
+nr_params
+nsamples
+ntrials
+of
+on_call!
+on_complete!
+on_error!
+on_next!
+on_subscribe!
+on_unsubscribe!
+operator_right
+override
+pairwise
+parallel
+paramfloattype
+params
+params!
+partype
+pdf
+pdf!
+pdfsquaredL2norm
+precision
+probs
+probval
+probvec
+prod
+prod!
+product_distribution
+promote_paramfloattype
+promote_samplefloattype
+promote_sampletype
+promote_variate_type
+proxy
+publish
+publish_behavior
+publish_recent
+publish_replay
+qqbuild
+quantile
+race
+rand
+rand!
+randomvar
+rate
+reduce
+ref_count
+release!
+rerun
+resolve_prod_strategy
+rule
+rxinference
+safe
+sample
+sample!
+samplefloattype
+sampler
+sampletype
+sampling_optimized
+scale
+scale!
+scan
+schedule_on
+scheduled
+score
+sdtype
+server
+set!
+setTimeout
+setmarginal!
+setmarginals!
+setmessage!
+setmessages!
+shape
+share
+share_recent
+share_replay
+skewness
+skip_complete
+skip_error
+skip_next
+skipindex
+softdot
+some
+source_proxy!
+span
+sqmahal
+sqmahal!
+srcubature
+start_with
+std
+stdlogx
+storage
+subscribable_extract_type
+subscribe!
+substitute
+succprob
+sufficientstatistics
+suffstats
+sum
+support
+switch_map
+switch_map_to
+sync
+take
+take_until
+tap
+tap_on_complete
+tap_on_subscribe
+tap_on_unsubscribe
+teardown!
+throwError
+timer
+tiny
+to_array
+truncated
+tuple_with_left
+tuple_with_right
+unsubscribe!
+update!
+uppercase
+vague
+value_support
+var
+variate_form
+varlogx
+void
+voidTeardown
+weightedmean
+weightedmean_cov
+weightedmean_invcov
+weightedmean_precision
+weightedmean_std
+weightedmean_var
+weights
+with_latest
+wsample
+wsample!
+xtlog
+zipped
diff --git a/dev/library/functional-forms/index.html b/dev/library/functional-forms/index.html new file mode 100644 index 000000000..f66fd3f6c --- /dev/null +++ b/dev/library/functional-forms/index.html @@ -0,0 +1,26 @@ + +Built-in functional form constraints · RxInfer.jl
GitHub

Built-in Functional Forms

This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.

Custom functional forms

See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.

UnspecifiedFormConstraint

Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.

@constraints begin 
+    q(x) :: Nothing # This is the default setting
+end

PointMassFormConstraint

The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. 

@constraints begin 
+    q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object
+end
RxInfer.PointMassFormConstraint — Type
PointMassFormConstraint

One of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.

Keyword arguments

  • optimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer
  • starting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point
  • boundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries

Custom optimizer callback interface

# This is an example of the `custom_optimizer` interface
+function custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # should return argmin of the -logpdf(distribution)
+end

Custom starting point callback interface

# This is an example of the `custom_starting_point` interface
+function custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # built-in optimizer expects an array, even for a univariate distribution
+    return [ 0.0 ] 
+end

Custom boundaries callback interface

# This is an example of the `custom_boundaries` interface
+function custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # returns a tuple of `lower` and `upper` boundaries
+    return (-Inf, Inf)
+end

Traits

  • is_point_mass_form_constraint = true
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = PointMass (for use in @constraints macro)
source

SampleListFormConstraint

SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.

@constraints begin 
+    q(x) :: SampleList(1000)
+    # or 
+    q(y) :: SampleList(1000, LeftProposal())
+end
RxInfer.SampleListFormConstraint — Type
SampleListFormConstraint(rng, strategy, method)

One of the form constraint objects. Approximates DistProduct with a SampleList object.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = SampleList (for use in @constraints macro)
source
RxInfer.LeftProposal — Type

Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.

source
RxInfer.RightProposal — Type

Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.

source

FixedMarginalFormConstraint

Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.

@constraints function block_updates(x_posterior = nothing) 
+    # `nothing` returns the computed posterior marginal
+    q(x) :: Marginal(x_posterior)
+end
RxInfer.FixedMarginalFormConstraint — Type
FixedMarginalFormConstraint

One of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = Marginal (for use in @constraints macro)
source

CompositeFormConstraint

It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:

form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()
@constraints begin 
+    q(x) :: SampleList(1000) :: PointMass()
+end
diff --git a/dev/library/model-specification/index.html b/dev/library/model-specification/index.html new file mode 100644 index 000000000..40684c388 --- /dev/null +++ b/dev/library/model-specification/index.html @@ -0,0 +1,4 @@ + +Model specification · RxInfer.jl
GitHub

Model specification in RxInfer

RxInfer.@model — Macro
@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model description
+end

@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.

Supported alias in the model specification

  • a || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).
  • a && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • a -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • ¬a and !a: alias for NOT(a) node (Unicode \neg, operator precedence ||, &&, -> and ! is the same as in Julia).
  • a + b + c: alias for (a + b) + c
  • a * b * c: alias for (a * b) * c
  • Normal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.
  • Normal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.
  • MvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • Gamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.
  • Gamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.
source
RxInfer.ModelGenerator — Type
ModelGenerator

ModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.

See also: infer

source
RxInfer.create_model — Function
create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)

Creates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.

Returns a tuple of 2 values:

    1. an instance of FactorGraphModel
    1. return value from the @model macro function definition
source
RxInfer.ModelInferenceOptions — Type
ModelInferenceOptions(; kwargs...)

Creates model inference options object. The list of available options is present below.

Options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.
  • warn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.

Advanced options

  • pipeline: changes the default pipeline for each factor node in the graph
  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

See also: infer

source
diff --git a/dev/manuals/background/index.html b/dev/manuals/background/index.html new file mode 100644 index 000000000..a2938296f --- /dev/null +++ b/dev/manuals/background/index.html @@ -0,0 +1,2 @@ + +Background: variational inference · RxInfer.jl
GitHub
diff --git a/dev/manuals/comparison/index.html b/dev/manuals/comparison/index.html new file mode 100644 index 000000000..88d9b9487 --- /dev/null +++ b/dev/manuals/comparison/index.html @@ -0,0 +1,28 @@ + +RxInfer.jl vs. Others · RxInfer.jl
GitHub

Comparison to other packages

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.

DISCLAIMER:

  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, and we'll be more than willing to rectify.
  2. The comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.
ToolboxUniversalityEfficiencyExpressivenessDebugging & VisualizationModularityInference EngineLanguageCommunity & Ecosystem
RxInfer.jl~✓✓~✗Message-passingJulia✗
ForneyLab.jl✗~✗~✗Message-passingJulia✗
Infer.net~✓✗✓✗Message-passingC#✗
PGMax✗✓✗✓✗Message-passingPython✗
Turing.jl✓✗✓~✗SamplingJulia✓
PyMC✓✗✓✓✗SamplingPython✓
NumPyro✓✓~✓✗SamplingPython✓
TensorFlow Probability✓✗~✓✗SamplingPython✓
Stan✓✗✓✓✗SamplingStan✓

(Date of creation: 20/10/2023)

Legend

  • ✓ : Full capability or feature is present.
  • ~ : Partial capability or feature is present.
  • ✗ : No capability or feature.

Notes:

  • Universality: Denotes the capability to depict a vast array of probabilistic models.
  • Efficiency: Highlights computational competence. A "–" in this context suggests perceived slowness.
  • Expressiveness: Assesses the ability to concisely formulate intricate probabilistic models.
  • Debugging & Visualization: Evaluates the suite of tools for model debugging and visualization.
  • Modularity: Reflects the potential to create models by integrating smaller models.
  • Inference Engines: Pinpoints the primary inference strategy employed by the toolbox.
  • Language: Identifies the programming language integral to the toolbox.
  • Community & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.

RxInfer.jl breakdown

  • Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.

  • Efficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.

  • Modularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:

@model function inner_inner(τ, y)
+    y ~ Normal(τ[1], τ[2])
+end
+
+@model function inner(θ, α)
+    β ~ Normal(0, 1)
+    α ~ Gamma(β, 1)
+    α ~ inner_inner(τ = θ)
+end
+
+@model function outer()
+    local w
+    for i = 1:5
+        w[i] ~ inner(θ = Gamma(1, 1))
+    end
+    y ~ inner(θ = w[2:3])
+end
  • Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(0.0, 1.0)\\ + w & \sim \mathrm{InverseGamma}(1.0, 1.0)\\ + y & \sim \mathrm{Normal}(x, w) +\end{aligned}\]

The model then is expressed in RxInfer.jl as follows:

using RxInfer
+
+@model function example_model()
+    x ~ Normal(mean=0.0, var=1.0)
+    w ~ InverseGamma(α = 1, θ = 1)
+    y ~ Normal(mean = x, var = w)
+end
  • Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.
diff --git a/dev/manuals/constraints-specification/index.html b/dev/manuals/constraints-specification/index.html new file mode 100644 index 000000000..7ac4db27b --- /dev/null +++ b/dev/manuals/constraints-specification/index.html @@ -0,0 +1,111 @@ + +Constraints specification · RxInfer.jl
GitHub

Constraints Specification

RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.

using RxInfer

General syntax

@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:


+# `functional` style
+@constraints function create_my_constraints(arg1, arg2)
+    ...
+end
+
+# `block` style
+myconstraints = @constraints begin 
+    ...
+end
+

In the first case it returns a function that return constraints upon calling, e.g. 

@constraints function make_constraints(mean_field)
+    q(x) :: PointMass
+
+    if mean_field
+        q(x, y) = q(x)q(y)
+    end
+end
+
+myconstraints = make_constraints(true)
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

and in the second case it evaluates automatically and returns constraints object directly.

myconstraints = @constraints begin
+    q(x) :: PointMass
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

Options specification

@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

myconstraints = @constraints [ warn = false ] begin 
+   ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/constraints specification

Marginal and messages form constraints

To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)

The following constraint:

@constraints begin
+    q(x) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:

\[\mathrm{approximate~} q(x) = \frac{\overrightarrow{\mu}(x)\overleftarrow{\mu}(x)}{\int \overrightarrow{\mu}(x)\overleftarrow{\mu}(x) \mathrm{d}x}\mathrm{~as~PointMass}\]

Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):

@constraints begin
+    q(x) :: PointMass
+    μ(x) :: SampleList(1000)
+    # it is possible to assign different form constraints on the same variable
+    # both for the marginal and for the messages
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+    μ(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) [ prod_constraint = GenericProd() ]
+  factorisation:
+Options:
+  warn = true
+

@constraints macro understands "stacked" form constraints. For example the following form constraint

@constraints begin
+    q(x) :: SampleList(1000) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass.

Note

Not all combinations of "stacked" form constraints are compatible between each other.

You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.

Factorisation constraints on posterior distribution q()

@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:

For example:

@constraints begin
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.

@constraints begin
+    q(x) = q(x[begin])..q(x[end])
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x) = q(x[(begin)..(end)])
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables $x_i$.

Note

@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])

It is possible to write more complex factorisation constraints, for example:

@constraints begin
+    q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x[(begin)..(end)], y[(begin)..(end)])
+Options:
+  warn = true
+

specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is

@constraints function make_constraints(k)
+    q(x) = q(x[begin:k])q(x[k+1:end])
+end
make_constraints (generic function with 1 method)

In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end].

To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+constraints = @constraints begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); constraints = constraints)

Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument.

diff --git a/dev/manuals/custom-node/733394f1.svg b/dev/manuals/custom-node/733394f1.svg new file mode 100644 index 000000000..8ce53ea64 --- /dev/null +++ b/dev/manuals/custom-node/733394f1.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/custom-node/index.html b/dev/manuals/custom-node/index.html new file mode 100644 index 000000000..951f07257 --- /dev/null +++ b/dev/manuals/custom-node/index.html @@ -0,0 +1,86 @@ + +Defining a custom node and rules · RxInfer.jl
GitHub

Creating your own custom nodes

Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.

To create a custom node in RxInfer, 4 steps are required:

  1. Create your custom node in RxInfer using the @node macro.
  2. Define the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.
  3. Specify computations for marginal distributions of the relevant variables with the @marginalrule macro.
  4. Implement the computation of the Free Energy in a node with the @average_energy macro.

Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!

Problem statement

Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin $K=20$ times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment $x_k\in\{0,1\}$ using the Bernoulli distribution as

\[p(x_k \mid \pi) = \mathrm{Ber}(x_k \mid \pi) = \pi^{x_k} (1-\pi)^{1-x_k},\]

where $\pi \in[0,1]$ denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of $\pi$ which she models using the Beta distribution as

\[p(\pi) = \mathrm{Beta}(\pi \mid 4, 8).\]

With this prior belief, the total probabilistic model that she has for this experiment is given by

\[p(x_{1:K}, \pi) = p(\pi) \prod_{k=1}^K p(x_k \mid \pi).\]

Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of $\pi$, $p(\pi \mid x_{1:K})$, denoting how $\pi$ is distributed after we have seen the data.

Step 1: Creating the custom node

Note

In this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.

First things first, let's import RxInfer:

using RxInfer

In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:

  1. The name of the node. (::Type)
  2. Whether the node is Deterministic or Stochastic.
  3. The interfaces of the node and any potential aliases. (::Vector)

For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as

# struct for Bernoulli distribution with success probability π
+struct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution
+    π :: T
+    new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError("π must be between 0 and 1"))
+end
+
+# for simplicity, let's also specify the mean of the distribution
+Distributions.mean(d::MyBernoulli) = d.π

In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.

Note

You can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)

For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of $\pi$, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.

The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.

Concluding, we can create the MyBernoulli factor node as

@node MyBernoulli Stochastic [out, (π, aliases = [p])]

Cool! Step 1 is done, we have created a custom node.

Step 2: Defining rules for our node

In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as $p(\pi\mid x_{1:K})$, we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.

Sum-product message passing update rules

In sum-product message passing we compute outgoing messages to our node as

\[\vec{\mu}(x) \propto \int \mathrm{Ber}(x\mid \pi) \vec{\mu}(\pi) \mathrm{d}x\]

\[\overleftarrow{\mu}(\pi) \propto \sum_{x \in \{0,1\}} \mathrm{Ber}(x\mid \pi) \overleftarrow{\mu}(x)\]

This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.

For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain $\pi = \frac{\alpha}{\alpha + \beta}$, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as

@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))

Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for "the incoming message on interface π". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.

The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):

@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))

Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:

\[\overleftarrow{\mu}(π) \propto \mathrm{Beta}(1 + x, 2 - x)\]

Which gives us the following update rule:

@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin
+    p = mean(m_out)
+    Beta(one(p) + p, 2one(p) - p)
+end

Variational message passing update rules

We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as

\[\vec{\nu}(x) \propto \exp \int q(\pi) \ln \mathrm{Ber}(x\mid \pi) \mathrm{d}x\]

\[\overleftarrow{\nu}(\pi) \propto \exp \sum_{x \in \{0,1\}} q(x) \ln \mathrm{Ber}(x\mid \pi)\]

These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.

#rules towards out
+@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))
+
+@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin
+    rho_1 = mean(log, q_π)          # E[ln(x)]
+    rho_2 = mean(mirrorlog, q_π)    # E[log(1-x)]
+    m = max(rho_1, rho_2)
+    tmp = exp(rho_1 - m)
+    p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))
+    return Bernoulli(p)
+end
+
+#rules towards π
+@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin
+    p = mean(q_out)
+    return Beta(one(p) + p, 2one(p) - p)
+end
Node

Typically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.

In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.

Step 3: Defining joint marginals for our node

The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by

\[F[q,f] = - \sum_{a\in\mathcal{V}} \mathrm{H}[q_a(s_a)] - \sum_{a\in\mathcal{V}}\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)] + \sum_{i\in\mathcal{E}}\mathrm{H}[q_i(s_i)]\]

Here we call $q_a(s_a)$ the joint marginals around a node and $-\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)]$ we term the average energy.

In order to be able to compute the Bethe free energy, we need to first describe how to compute $q_a(s_a)$, defined in our case as

\[q(x_k, \pi) = \vec{\mu}(\pi) \overleftarrow{\mu}(x_k) \mathrm{Ber}(x_k \mid \pi)\]

To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:

@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin
+    r = mean(m_out)
+    p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)
+    return (out = m_out, p = p)
+end

In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as $q(x_k, \pi) = q(x_k)q(\pi)$. These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing $q(\pi)$ we need to compute the product $\vec{\mu}(\pi)\overleftarrow{\mu}(\pi)$. We already know how $\overleftarrow{\mu}(\pi)$ looks like from the previous step, so we can just use the prod function.

Step 4: Defining the average energy for our node

To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as $-\mathrm{E}_{q(x_k, \pi)}[\ln p(x_k \mid \pi)]$, however, because we know that we observe $x_k$ and therefore $q(x_k, \pi)$ factorizes, we can instead compute $\begin{aligned} -\mathrm{E}_{q(x_k)q(\pi)}[\ln p(x_k \mid \pi)] &= -\mathrm{E}_{q(x_k)q(\pi)} [\ln (\pi^{x_k} (1-\pi)^{1 - x_k})] \\ +&= -\mathrm{E}_{q(x_k)q(\pi)} [x_k \ln(\pi) + (1-x_k) \ln(1-\pi)] \\ +&= -\mathrm{E}_{q(x_k)}[x_k] \mathrm{E}_{q(\pi)} [\ln(\pi)] - (1-\mathrm{E}_{q(x_k)}[x_k]) \mathrm{E}_{q(\pi)}[\ln(1-\pi)] \end{aligned}$

Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to $\mathrm{E}_{q(x)}[1-\log{x}]$.

@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)

In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....

Using our node in a model

With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:

using Random
+
+rng = MersenneTwister(42)
+n = 500
+π_real = 0.75
+distribution = Bernoulli(π_real)
+
+dataset = float.(rand(rng, distribution, n))

Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:

@model function coin_model_mybernoulli(n)
+
+    # `datavar` creates data 'inputs' in our model
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    π ~ Beta(4.0, 8.0)
+
+    # We assume that outcome of each coin flip is governed by the MyBernoulli distribution
+    for i in 1:n
+        y[i] ~ MyBernoulli(π)
+    end
+
+end

Finally, we can run inference with this model and the generated dataset:

result_mybernoulli = infer(
+    model = coin_model_mybernoulli(length(dataset)),
+    data  = (y = dataset, ),
+)
Inference results:
+  Posteriors       | available for (π)
+

We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.

using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label="p(π|x)", c=3)
+vline!([π_real], label="Real π")
Example block output

As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.

@model function coin_model(n)
+
+    y = datavar(Float64, n)
+    p ~ Beta(4.0, 8.0)
+
+    for i in 1:n
+        y[i] ~ Bernoulli(p)
+    end
+
+end
+
+result_bernoulli = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, ),
+)
+
+if !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])
+    error("Results are not identical")
+else
+    println("Results are identical 🎉🎉🎉")
+end
Results are identical 🎉🎉🎉

Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.

diff --git a/dev/manuals/debugging/1c90f6bc.svg b/dev/manuals/debugging/1c90f6bc.svg new file mode 100644 index 000000000..11a8c5e53 --- /dev/null +++ b/dev/manuals/debugging/1c90f6bc.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/debugging/94996418.svg b/dev/manuals/debugging/94996418.svg new file mode 100644 index 000000000..1fe59d302 --- /dev/null +++ b/dev/manuals/debugging/94996418.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/debugging/index.html b/dev/manuals/debugging/index.html new file mode 100644 index 000000000..f0fdd115f --- /dev/null +++ b/dev/manuals/debugging/index.html @@ -0,0 +1,60 @@ + +Debugging · RxInfer.jl
GitHub

Debugging

Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. 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

We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a "Memory Addon". Below is an example explaining how you can extract this history and use it to fix a bug.

Consider the coin toss example from earlier in the documentation. We model the binary outcome $x$ (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the $\theta$ parameter, with a known shape 𝑎 and rate 𝑏 parameter.

\[x_i \sim \mathrm{Bernoulli}(\theta)\]

\[\theta \sim \mathrm{Beta}(a, b)\]

where $x_i \in {0, 1}$ are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:

using RxInfer, Random, Plots
+
+n = 4
+θ_real = 0.3
+dataset = convert.(Int64, rand(Bernoulli(θ_real), n))
+
+@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, huge)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+

The model will run without errors. But when we plot the posterior distribution for $\theta$, something's wrong. The posterior seems to be a flat distribution:

rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+    addons = (AddonMemory(),)
+)
Inference results:
+  Posteriors       | available for (θ)
+

Now we have access to the messages that led to the marginal posterior:

Addons_messages

The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:

\[\underbrace{\overrightarrow{\mu}_{θ}(θ)}_{\substack{ \text{outgoing}\\ \text{message}}} = \sum_{x_1,\ldots,x_n} \underbrace{\overrightarrow{\mu}_{X_1}(x_1)\cdots \overrightarrow{\mu}_{X_n}(x_n)}_{\substack{\text{incoming} \\ \text{messages}}} \cdot \underbrace{f(θ,x_1,\ldots,x_n)}_{\substack{\text{node}\\ \text{function}}}\]

Graph

Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of $\theta$ we used in the code block above. So why does the posterior have this rate parameter?

All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.

@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, 100)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+
rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

Now the posterior is visible in the plot.

diff --git a/dev/manuals/delta-node/index.html b/dev/manuals/delta-node/index.html new file mode 100644 index 000000000..ed99c9e87 --- /dev/null +++ b/dev/manuals/delta-node/index.html @@ -0,0 +1,59 @@ + +Delta node · RxInfer.jl
GitHub

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.

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:

  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.
  3. Stacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.

The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:

MethodsGaussian NodesExponential Family NodesStacking Delta Nodes
Linearization✓✗✓
Unscented✓✗✓
CVI✓✓✗

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.

For clarity, consider the following example:

using RxInfer
+
+@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=0.0, var=1.0)
+    y ~ tanh(x)
+    z ~ Normal(mean=y, var=1.0)
+end

To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:

delta_meta = @meta begin
+    tanh() -> Linearization()
+end
Meta specification:
+  tanh() -> Linearization()
+Options:
+  warn = true

or

delta_meta = @meta begin
+    tanh() -> Unscented()
+end
Meta specification:
+  tanh() -> Unscented{Float64, Float64, Float64, Nothing}(0.001, 2.0, 0.0, nothing)
+Options:
+  warn = true

For a deeper understanding of the Unscented method and its parameters, consult the docstrings.

Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:

delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)
+end
Meta specification:
+  tanh() -> DeltaMeta{Linearization, typeof(atanh)}(Linearization(), atanh)
+Options:
+  warn = true

To execute the inference procedure:

infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))
Inference results:
+  Posteriors       | available for (y, x)
+

This methodology is consistent even when the delta node is associated with multiple nodes. For instance:

f(x, g) = x*tanh(g)
f (generic function with 1 method)
@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=1.0, var=1.0)
+    g ~ Normal(mean=1.0, var=1.0)
+    y ~ f(x, g)
+    z ~ Normal(mean=y, var=0.1)
+end

The corresponding meta specification is:

delta_meta = @meta begin
+    f() -> DeltaMeta(method = Linearization())
+end
Meta specification:
+  f() -> DeltaMeta{Linearization, Nothing}(Linearization(), nothing)
+Options:
+  warn = true

or simply

delta_meta = @meta begin
+    f() -> Linearization()
+end
Meta specification:
+  f() -> Linearization()
+Options:
+  warn = true

If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:

delta_meta = @meta begin 
+    f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))
+end

Exponential Family Case

When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:

using RxInfer
+
+@model function delta_node_example1()
+    z = datavar(Float64)
+    x ~ Gamma(shape=1.0, rate=1.0)
+    y ~ tanh(x)
+    z ~ Bernoulli(y)
+end

The corresponding meta specification can be represented as:

using StableRNGs
+using Optimisers
+
+delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))
+end
Meta specification:
+  tanh() -> DeltaMeta{ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}, Nothing}(ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}(StableRNGs.LehmerRNG(state=0x00000000000000000000000000000055), 100, 100, Optimisers.Descent{Float64}(0.01), ForwardDiffGrad{0}(), 1, Val{true}(), true), nothing)
+Options:
+  warn = true

Consult the ProdCVI docstrings for a detailed explanation of these parameters.

diff --git a/dev/manuals/getting-started/9ccff26c.svg b/dev/manuals/getting-started/9ccff26c.svg new file mode 100644 index 000000000..2920da7f2 --- /dev/null +++ b/dev/manuals/getting-started/9ccff26c.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/getting-started/a8a80fa1.svg b/dev/manuals/getting-started/a8a80fa1.svg new file mode 100644 index 000000000..f187c1ee4 --- /dev/null +++ b/dev/manuals/getting-started/a8a80fa1.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/getting-started/index.html b/dev/manuals/getting-started/index.html new file mode 100644 index 000000000..50a0e6af6 --- /dev/null +++ b/dev/manuals/getting-started/index.html @@ -0,0 +1,91 @@ + +Getting started · RxInfer.jl
GitHub

Getting started

RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.

RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.

This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.

Installation

Install RxInfer through the Julia package manager:

] add RxInfer

Importing RxInfer

To add RxInfer package (and all associated packages) into a running Julia session simply run:

using RxInfer

Read more about about using in the Using methods from RxInfer section of the documentation.

Example: Inferring the bias of a coin

The RxInfer approach to solving inference problems consists of three phases:

  1. Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.
  2. Inference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.
  3. Inference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.

Coin flip simulation

Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).

First let's setup our environment by importing all needed packages:

using RxInfer, Distributions, Random

Next, let's define our dataset:

rng = MersenneTwister(42)
+n = 10
+p = 0.75
+distribution = Bernoulli(p)
+
+dataset = float.(rand(rng, Bernoulli(p), n))
10-element Vector{Float64}:
+ 1.0
+ 1.0
+ 1.0
+ 1.0
+ 0.0
+ 0.0
+ 1.0
+ 1.0
+ 0.0
+ 1.0

Model specification

In 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.

Likelihood

We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.

\[y_i \sim \mathrm{Bernoulli}(\theta),\]

where $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]$.

Prior

We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.

\[\theta \sim Beta(a, b),\]

where $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.

Joint probability

The joint probability is given by the multiplication of the likelihood and the prior, i.e.

\[P(y_{1:N}, θ) = P(θ) \prod_{i=1}^N P(y_i | θ).\]

Now let's see how to specify this model using GraphPPL's package syntax.

# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during inference step
+    return y, θ
+end

As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create "clamped" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Inference specification

Automatic inference specification

Once 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 inference function that supports static datasets.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
+
θestimated = result.posteriors[:θ]
Beta{Float64}(α=9.0, β=10.0)
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803

Read more information about the inference function in the Static Inference documentation section.

Manual inference specification

There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:

  1. Return variables of interests from model specification
  2. Subscribe on variables of interests posterior marginal updates
  3. Pass data to the model
  4. Unsubscribe

Here is an example of inference procedure:

function custom_inference(data)
+    n = length(data)
+
+    # `coin_model` function from `@model` macro returns a reference to the model generator object
+    # we need to use the `create_model` function to get actual model object
+    model, (y, θ) = create_model(coin_model(n))
+
+    # Reference for future posterior marginal
+    mθ = nothing
+
+    # `getmarginal` function returns an observable of future posterior marginal updates
+    # We use `Rocket.jl` API to subscribe on this observable
+    # As soon as posterior marginal update is available we just save it in `mθ`
+    subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)
+
+    # `update!` function passes data to our data inputs
+    update!(y, data)
+
+    # It is always a good practice to unsubscribe and to
+    # free computer resources held by the subscription
+    unsubscribe!(subscription)
+
+    # Here we return our resulting posterior marginal
+    return mθ
+end
custom_inference (generic function with 1 method)

Inference execution

Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.

θestimated = custom_inference(dataset)
Marginal(Beta{Float64}(α=9.0, β=10.0))
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title="Prior", fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+p2 = plot(rθ, (x) -> pdf(θestimated, x), title="Posterior", fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+
+plot(p1, p2, layout = @layout([ a; b ]))
Example block output

In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:

dataset_100   = float.(rand(rng, Bernoulli(p), 100))
+dataset_1000  = float.(rand(rng, Bernoulli(p), 1000))
+dataset_10000 = float.(rand(rng, Bernoulli(p), 10000))
θestimated_100   = custom_inference(dataset_100)
+θestimated_1000  = custom_inference(dataset_1000)
+θestimated_10000 = custom_inference(dataset_10000)
p3 = plot(title = "Posterior", legend = :topleft)
+
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_100)", c = 4)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_1000)", c = 5)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_10000)", c = 6)
+
+plot(p1, p3, layout = @layout([ a; b ]))
Example block output

With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.

println("mean: ", mean(θestimated_10000))
+println("std:  ", std(θestimated_10000))
mean: 0.7529223698671196
+std:  0.004310967761308469

Where to go next?

There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.

diff --git a/dev/manuals/inference/infer/index.html b/dev/manuals/inference/infer/index.html new file mode 100644 index 000000000..8097c87e2 --- /dev/null +++ b/dev/manuals/inference/infer/index.html @@ -0,0 +1,120 @@ + +Static vs Streamline inference · RxInfer.jl
GitHub

Automatic Inference Specification

RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors.

It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.

For details on manual inference specification, see the Manual Inference section.

RxInfer.infer — Function
infer(
+    model; 
+    data = nothing,
+    datastream = nothing,
+    autoupdates = nothing,
+    initmarginals = nothing,
+    initmessages = nothing,
+    constraints = nothing,
+    meta = nothing,
+    options = nothing,
+    returnvars = nothing, 
+    predictvars = nothing, 
+    historyvars = nothing,
+    keephistory = nothing,
+    iterations = nothing,
+    free_energy = false,
+    free_energy_diagnostics = BetheFreeEnergyDefaultChecks,
+    showprogress = false,
+    callbacks = nothing,
+    addons = nothing,
+    postprocess = DefaultPostprocess(),
+    warn = true,
+    events = nothing,
+    uselock = false,
+    autostart = true,
+    catch_exception = false
+)

This function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.

Arguments

For more information about some of the arguments, please check below.

  • model: specifies a model generator, required
  • data: NamedTuple or Dict with data, required (or datastream or predictvars)
  • datastream: A stream of NamedTuple with data, required (or data)
  • autoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates
  • initmarginals = nothing: NamedTuple or Dict with initial marginals, optional
  • initmessages = nothing: NamedTuple or Dict with initial messages, optional
  • constraints = nothing: constraints specification object, optional, see @constraints
  • meta = nothing: meta specification object, optional, may be required for some models, see @meta
  • options = nothing: model creation options, optional, see ModelInferenceOptions
  • returnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information
  • predictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)
  • historyvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)
  • keephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)
  • iterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information
  • free_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl
  • free_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.
  • showprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)
  • catch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)
  • callbacks = nothing: inference cycle callbacks, optional, see below for more info
  • addons = nothing: inject and send extra computation information along messages, see below for more info
  • postprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info
  • events = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)
  • uselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)
  • autostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)
  • warn = true: enables/disables warnings

Note on NamedTuples

When passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.

The model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:

@model function coin_toss(some_argument, some_keyword_argument = 3)
+    ...
+end
+
+result = infer(
+    model = coin_toss(some_argument; some_keyword_argument = 3)
+)

Note: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.

  • data

Either data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.

Note: The behavior of the data keyword argument depends on the inference setting (batch or streamline).

The data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.

  • streamline setting

All entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.

  • datastream

The datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.

Note: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.

For specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as

infer(...
+    initmarginals = (
+        # initialize the marginal distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)
+
+This argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.
+
+- ### `initmessages`
+
+For specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as

julia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )

  • options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.

  • pipeline: changes the default pipeline for each factor node in the graph

  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

  • returnvars

returnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.

Batch inference:

  • Accepts a NamedTuple or Dict of return variable specifications.
  • Two specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).
  • When iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).
  • Use iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.

Example:

result = infer(
+    ...,
+    returnvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    )
+)

Shortcut for setting the same option for all variables:

result = infer(
+    ...,
+    returnvars = KeepLast()  # or KeepEach()
+)

Streamline inference:

  • For each symbol in returnvars, infer creates an observable stream of posterior updates.
  • Agents can subscribe to these updates using the Rocket.jl package.

Example:

engine = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    returnvars = (:x, :τ),
+    autostart  = false
+)
  • predictvars

predictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.

Similar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    predictvars = (
+        o = KeepLast(),
+        τ = KeepEach()
+    )
+)

Note: The predictvars argument is exclusive for batch setting.

  • historyvars

historyvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.

historyvars accepts a NamedTuple or Dict or return var specification. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    ),
+    keephistory = 10
+)

It is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.

Example:

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = KeepLast(),
+    keephistory = 10
+)
  • keep_history

Specifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.

  • iterations

Specifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration.

  • free_energy

Streamline inference:

Specifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.

  • When free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.
    • engine.free_energy_history: Averaged BFE history over VMP iterations.
    • engine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.
    • engine.free_energy_raw_history: Raw BFE history.

Batch inference:

Specifies if the infer function should return Bethe Free Energy (BFE) values.

  • Optionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.

  • free_energy_diagnostics

This settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.

  • catch_exception

The catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.

  • callbacks

The inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.

result = infer(
+    ...,
+    callbacks = (
+        on_marginal_update = (model, name, update) -> println("$(name) has been updated: $(update)"),
+        after_inference    = (args...) -> println("Inference has been completed")
+    )
+)

The callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:

  • on_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)
  • before_model_creation: args: ()
  • after_model_creation: args: (model::FactorGraphModel, returnval)
  • before_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • before_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • after_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)
  • after_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)

before_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.

  • addons

The addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.

  • postprocess

The postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.

source
RxInfer.InferenceResult — Type
InferenceResult

This structure is used as a return value from the infer function.

Public Fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.
  • free_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.
  • error: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.

See also: infer

source
RxInfer.start — Function
start(engine::RxInferenceEngine)

Starts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.stop

source
RxInfer.stop — Function
stop(engine::RxInferenceEngine)

Stops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.start

source
RxInfer.@autoupdates — Macro
@autoupdates

Creates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification.

Each line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.

For example:

@autoupdates begin 
+    x = f(q(z))
+end

This structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically.

As an example consider the following model and auto-update specification:

@model function kalman_filter()
+    x_current_mean = datavar(Float64)
+    x_current_var  = datavar(Float64)
+
+    x_current ~ Normal(mean = x_current_mean, var = x_current_var)
+
+    x_next ~ Normal(mean = x_current, var = 1.0)
+
+    y = datavar(Float64)
+    y ~ Normal(mean = x_next, var = 1.0)
+end

This model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:

autoupdates = @autoupdates begin
+    x_current_mean, x_current_var = mean_cov(q(x_next))
+end

This structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.

See also: infer

source
RxInfer.RxInferenceEngine — Type
RxInferenceEngine

The return value of the rxinference function.

Public fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.
  • free_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.
  • history: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.
  • free_energy_history: (optional) Free energy history, average over variational iterations
  • free_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)
  • free_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)
  • events: (optional) A stream of events send by the inference engine. See the events argument for the infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.

Use the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.

See also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop

source
RxInfer.RxInferenceEvent — Type
RxInferenceEvent{T, D}

The RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.

The events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:

using Rocket
+
+struct MyEventListener <: Rocket.Actor{RxInferenceEvent}
+    # ... extra fields
+end
+
+function Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })
+    model, iteration = event
+    println("Iteration $(iteration) has been finished.")
+end
+
+function Rocket.on_error!(listener::MyEventListener, err)
+    # ...
+end
+
+function Rocket.on_complete!(listener::MyEventListener)
+    # ...
+end
+

and later on:

engine = infer(events = Val((:after_iteration, )), ...)
+
+subscription = subscribe!(engine.events, MyEventListener(...))

See also: infer, RxInferenceEngine

source
diff --git a/dev/manuals/inference/manual/16a34680.svg b/dev/manuals/inference/manual/16a34680.svg new file mode 100644 index 000000000..b28f2a8ae --- /dev/null +++ b/dev/manuals/inference/manual/16a34680.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/inference/manual/41ebe24f.svg b/dev/manuals/inference/manual/41ebe24f.svg new file mode 100644 index 000000000..372929fdc --- /dev/null +++ b/dev/manuals/inference/manual/41ebe24f.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/inference/manual/4d1eb092.svg b/dev/manuals/inference/manual/4d1eb092.svg new file mode 100644 index 000000000..70a8896a5 --- /dev/null +++ b/dev/manuals/inference/manual/4d1eb092.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/inference/manual/index.html b/dev/manuals/inference/manual/index.html new file mode 100644 index 000000000..cd5db6b41 --- /dev/null +++ b/dev/manuals/inference/manual/index.html @@ -0,0 +1,103 @@ + +Manual inference specification · RxInfer.jl
GitHub

Manual inference

For advanced use cases it is advised to use manual inference specification.

Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:

  1. Create a model with @model macro and get a references to random variables and data inputs
  2. Subscribe to random variable posterior marginal updates
  3. Subscribe to Bethe Free Energy updates (optional)
  4. Feed model with observations
  5. Unsubscribe from posterior marginal updates (optional)

It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.

Model creation

During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.

using RxInfer, Distributions, Random
+
+@model function my_model()
+    m2 ~ NormalMeanVariance(0.0, 1.0)
+    m1 ~ NormalMeanVariance(m2, 1.0)
+
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(m1, 1.0)
+
+    # Return variables of interests, optional
+    return m1, y
+end

And later on we may create our model with the create_model function and obtain references for variables of interests:

model, (m1, y) = create_model(my_model())

Alternatively, it is possible to query any variable using squared brackets on model object:

model[:m1] # m1
+model[:y]  # y

@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.

Posterior marginal updates

The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.

We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:

m1_posterior_updates = getmarginal(m1)

After that we can subscribe on new updates and perform some actions based on new values:

m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin
+    println("New posterior for m1: ", new_posterior)
+end)

Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.

@model function my_model()
+    ...
+    m_n = randomvar(n)
+    ...
+    return m_n, ...
+end
+
+model, (m_n, ...) = create_model(my_model())
+
+m_n_updates = getmarginals(m_n)

Feeding observations

By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.

To feed an observation for a specific data input we use update! function:

update!(y, 0.0)
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:

update!(y, 0.0) # Observation didn't change, should result in the same posterior
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

If y is an array of data inputs it is possible to pass an array of observation to update! function:

for i in 1:length(data)
+    update!(y[i], data[i])
+end
+# is an equivalent of
+update!(y, data)

Variational Message Passing

Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.

using RxInfer, Distributions, Random
real_mean      = -4.0
+real_precision = 0.2
+rng            = MersenneTwister(1234)
+
+n    = 100
+data = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)
@model function normal_estimation(n)
+    m ~ NormalMeanVariance(0.0, 10.0)
+    w ~ Gamma(0.1, 10.0)
+
+    y = datavar(Float64, n)
+
+    for i in 1:n
+        y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }
+    end
+
+    return m, w, y
+end

We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:

model, (m, w, y) = create_model(normal_estimation(n))
+
+# We use vague initial marginals
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))

To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:

m_marginals = []
+w_marginals = []
+
+subscriptions = subscribe!([
+    (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),
+    (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),
+])
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(subscriptions)

As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.

using Plots
+
+p1    = plot(title = "'Mean' posterior marginals")
+grid1 = -6.0:0.01:4.0
+
+for iter in [ 1, 2, 10 ]
+
+    estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = "Estimated mean after $iter VMP iterations")
+
+end
+
+plot!(p1, [ real_mean ], seriestype = :vline, label = "Real mean", color = :red4, opacity = 0.7)
Example block output
p2    = plot(title = "'Precision' posterior marginals")
+grid2 = 0.01:0.001:0.35
+
+for iter in [ 2, 3, 10 ]
+
+    estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = "Estimated precision after $iter VMP iterations")
+
+end
+
+plot!(p2, [ real_precision ], seriestype = :vline, label = "Real precision", color = :red4, opacity = 0.7)
Example block output

Computing Bethe Free Energy

VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.

The RxInfer package exports score function for an observable of free energy values:

fe_observable = score(model, BetheFreeEnergy())
# Reset posterior marginals for `m` and `w`
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))
+
+fe_values = []
+
+fe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(fe_subscription)
plot(fe_values, label = "Bethe Free Energy", xlabel = "Iteration #")
Example block output
diff --git a/dev/manuals/inference/overview/index.html b/dev/manuals/inference/overview/index.html new file mode 100644 index 000000000..cbece0866 --- /dev/null +++ b/dev/manuals/inference/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Inference execution

The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):

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.

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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.

Automatic inference specification on static datasets

RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section.

Automatic inference specification on real-time datasets

RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section.

Manual inference specification

While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.

diff --git a/dev/manuals/inference/postprocess/index.html b/dev/manuals/inference/postprocess/index.html new file mode 100644 index 000000000..37629f882 --- /dev/null +++ b/dev/manuals/inference/postprocess/index.html @@ -0,0 +1,2 @@ + +Inference results postprocessing · RxInfer.jl
GitHub

Inference results postprocessing

infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:

diff --git a/dev/manuals/meta-specification/index.html b/dev/manuals/meta-specification/index.html new file mode 100644 index 000000000..d8e951e9a --- /dev/null +++ b/dev/manuals/meta-specification/index.html @@ -0,0 +1,122 @@ + +Meta specification · RxInfer.jl
GitHub

Meta Specification

Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.

General syntax

@meta macro accepts either regular Julia function or a single begin ... end block:

@meta function MyModelMeta(arg1, arg2)
+    Node(y,x) -> MetaObject(arg1, arg2)
+end
+
+my_meta = @meta begin 
+    Node(y,x) -> MetaObject(arg1, arg2)
+end

In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order $5$ can be specified as follows:

@meta function ARmodel_meta(num_order)
+    AR() -> ARMeta(Univariate, num_order, ARsafe())
+end
+
+my_meta = ARmodel_meta(5)

In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:

num_order = 5
+
+my_meta = @meta begin 
+    AR() -> ARMeta(Multivariate, num_order, ARsafe())
+end

Both syntax variations provide the same meta specification and there is no preference given to one over the other.

Options specification

@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

my_meta = @meta [ warn = false ] begin 
+   ...
+end
+
+@meta [ warn = false ] function MyModelMeta()
+    ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/meta specification

Meta specification

First, let's start with an example:

my_meta = @meta begin 
+    GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))
+end

This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.

You can have a list of as many meta specification entries as possible for different nodes:

my_meta = @meta begin 
+    GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))
+    AR() -> ARMeta(Multivariate, 5, ARsafe())
+    MyCustomNode() -> MyCustomMetaObject(arg1, arg2)
+end

To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+my_meta = @meta begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); meta = my_meta)

Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:

inferred_result = infer(
+    model = my_model(arguments...),
+    meta = my_meta,
+    ...
+)

Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:

@model function my_model()
+    ...
+
+    y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }
+
+    ...
+end

If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.

Create your own meta

Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:

# create your own meta structure for your custom node
+struct MyCustomMeta
+    arg1 
+    arg2 
+end
+
+# apply the new meta structure to your node
+@meta function model_meta(arg1, arg2)
+    MyCustomNode() -> MyCustomMeta(arg1,arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

or create different meta structures for a node, e.g. AR node:

# create your own meta structure for the AR node
+struct MyARMeta
+    arg1
+    arg2
+end
+
+# apply the new meta structure to the AR node
+@meta function model_meta(arg1, arg2)
+    AR() -> MyARMeta(arg1, arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.

Example

This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(2.5, 0.5)\\ + y & \sim \mathrm{Normal}(2*x, 2.0) +\end{aligned}\]

where $y$ is observable data and $x$ is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.

using RxInfer
+
+#create data
+y_data = 4.0
+
+#make model
+@model function gaussian_model()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+#do inference
+inference_result = infer(
+    model = gaussian_model(),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (x)
+

However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean $m$ clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:

#create your new meta structure for Normal node
+struct MetaConstrainedMeanNormal{T}
+    lower_limit :: T
+    upper_limit :: T
+end
+
+#define rules with meta for the Normal node
+@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
+
+@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
#make model
+@model function gaussian_model_with_meta()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+custom_meta = @meta begin
+    NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)
+end
+
+#do inference
+inference_result = inference(
+    model = gaussian_model(),
+    data = (y = y_data,),
+    meta = custom_meta
+)
Inference results:
+  Posteriors       | available for (x)
+

Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.

diff --git a/dev/manuals/model-specification/index.html b/dev/manuals/model-specification/index.html new file mode 100644 index 000000000..f495a2492 --- /dev/null +++ b/dev/manuals/model-specification/index.html @@ -0,0 +1,117 @@ + +Model specification · RxInfer.jl
GitHub

Model Specification

The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: 

@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model specification here
+    return ...
+end

Model options, model_arguments and model_keyword_arguments are optional and may be omitted:

@model function model_name()
+    # model specification here
+    return ...
+end

The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:

@model function my_model(model_arguments...)
+    # model specification here
+    # ...
+    return x, y
+end
generator = my_model(model_arguments...)

In order to create an instance of the model object we should use the create_model function:

model, (x, y) = create_model(generator)

It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.

A full example before diving in

Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:

@model function state_space_model(n_observations, noise_variance)
+
+    c = constvar(1.0)
+    x = randomvar(n_observations)
+    y = datavar(Float64, n_observations)
+
+    x[1] ~ NormalMeanVariance(0.0, 100.0)
+
+    for i in 2:n_observations
+       x[i] ~ x[i - 1] + c
+       y[i] ~ NormalMeanVariance(x[i], noise_var)
+    end
+
+    return x, y
+end

Graph variables creation

Constants

Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).

You can create a constant within a model specification macro with constvar() function. For example:

@model function model_name(...)
+    ...
+    c = constvar(1.0)
+
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0
+    end
+    ...
+end
Note

constvar() function is supposed to be used only within the @model macro.

Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:

@model function model_name(nsamples::Int, c::ConstVariable)
+    ...
+    # no need to call for a constvar() here
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`
+    end
+    ...
+end
Note

::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.

Data variables

It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.

Examples: 

@model function model_name(...)
+    ...
+    y = datavar(Float64) # Creates a single data input with `y` as identificator
+    y = datavar(Float64, n) # Returns a vector of  `y_i` data input objects with length `n`
+    y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`
+    y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

datavar() function is supposed to be used only within the @model macro.

datavar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = datavar(Float64, n) where { allow_missing = true }
+    ...
+end

Data variables available options

  • allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.

Random variables

There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.

Examples: 

@model function model_name(...)
+    ...
+    x = randomvar() # Returns a single random variable which can be used later in the model
+    x = randomvar(n) # Returns an vector of random variables with length `n`
+    x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`
+    x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

randomvar() function is supposed to be used only within the @model macro.

randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = randomvar() where { prod_constraint = ProdGeneric() }
+    ...
+end

Random variables available options

  • prod_constraint
  • prod_strategy
  • marginal_form_constraint
  • marginal_form_check_strategy
  • messages_form_constraint
  • messages_form_check_strategy
  • pipeline

The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.

Node creation

Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables.

Distributions.jl compatibility

For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:

  1. Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.
  2. Depending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.
  3. In certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.

Tilde syntax

We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define

@model function model_name(...)
+    ...
+    m = randomvar()
+    v = randomvar()
+    y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically
+    ...
+end

Another example, but using a deterministic relation between random variables:

@model function model_name(...)
+    ...
+    a = randomvar()
+    b = randomvar()
+    c ~ a + b
+    ...
+end
Note

The RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.

The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:

noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.

It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.

Note

It is forbidden to use random variable within square brackets in the model specification.

y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.
+
+y ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.

It is also possible to return a node reference from the ~ operator. Use the following syntax:

node, y ~ NormalMeanVariance(mean, var)

Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.

Broadcasting syntax

Note

Broadcasting syntax requires at least v2.1.0 of GraphPPL.jl

GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:

y = datavar(Float64, n)
+y .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations

More complex expression are also allowed:

m ~ NormalMeanPrecision(0.0, 0.0001)
+t ~ Gamma(1.0, 1.0)
+
+y = randomvar(Float64, n)
+y .~ NormalMeanPrecision(m, t)
A = constvar(...)
+x = randomvar(n)
+y = datavar(Vector{Float64}, n)
+
+w         ~ Wishart(3, diageye(2))
+x[1]      ~ MvNormalMeanPrecision(zeros(2), diageye(2))
+x[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A
+y        .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix

Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:

# Suppose `x` is a 2-dimensional Gaussian distribution
+z .~ x .+ constvar([ 1, 1 ])
+# Which is equivalent to 
+for i in 1:n
+   z[i] ~ x[i] + constvar([ 1, 1 ])
+end

Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:

# Without explicit `constvar`
+z .~ x .+ [ 1, 1 ]
+# Which is equivalent to 
+array = [1, 1]
+for i in 1:n
+   z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian 
+end

Read more about how broadcasting machinery works in Julia in the official documentation.

Node creation options

To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q

A list of the available options specific to the ReactiveMP inference engine is presented below.

Factorisation constraint option

See also Constraints Specification section.

Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:

variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }

where RecognitionFactorisationConstraint can be the following

  1. MeanField()

Automatically specifies a mean-field factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }
  1. FullFactorisation()

Automatically specifies a full factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }
  1. q(μ)q(v)q(out) or q(μ) * q(v) * q(out)

A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.

Examples: 

# Using interface names of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names for some node
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }
+
+# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names aliases for some node
+# In general aliases correspond to the function names for distribution parameters
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }
+
+# Using random variables names from `~` operator expression
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }
+
+# All methods can be combined easily
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }

Metadata option

Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.

z ~ f(x, y) where { meta = ... }
diff --git a/dev/manuals/understanding-why-to-initialize-messages/5ea1c9fa.svg b/dev/manuals/understanding-why-to-initialize-messages/5ea1c9fa.svg new file mode 100644 index 000000000..0f57af2d6 --- /dev/null +++ b/dev/manuals/understanding-why-to-initialize-messages/5ea1c9fa.svg @@ -0,0 +1,296 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/understanding-why-to-initialize-messages/a5e0b49a.svg b/dev/manuals/understanding-why-to-initialize-messages/a5e0b49a.svg new file mode 100644 index 000000000..050ea9e2b --- /dev/null +++ b/dev/manuals/understanding-why-to-initialize-messages/a5e0b49a.svg @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/understanding-why-to-initialize-messages/ee804f58.svg b/dev/manuals/understanding-why-to-initialize-messages/ee804f58.svg new file mode 100644 index 000000000..ea85b586d --- /dev/null +++ b/dev/manuals/understanding-why-to-initialize-messages/ee804f58.svg @@ -0,0 +1,396 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/manuals/understanding-why-to-initialize-messages/index.html b/dev/manuals/understanding-why-to-initialize-messages/index.html new file mode 100644 index 000000000..ac65fd5f2 --- /dev/null +++ b/dev/manuals/understanding-why-to-initialize-messages/index.html @@ -0,0 +1,57 @@ + +Messages initialization · RxInfer.jl
GitHub

Understating why we need to initialize messages in RxInfer

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.

Part 1. Framing the problem

John has recently acquired a new car and is keenly interested in its fuel consumption rate. He holds the belief that this rate follows a linear relationship with the variable speed. To validate this hypothesis, he plans to conduct tests by driving his car on the urban roads close to his home, recording both the fuel consumption and speed data. To ascertain the fuel consumption rate, John has opted for Bayesian linear regression as his analytical method.

using Random, Plots, StableRNGs
+
+function generate_data(a, b, v, nr_samples; rng = StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
+
+# For demonstration purposes we generate some fake data
+x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
Example block output

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

using RxInfer
+
+@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

Delighted with the convenience offered by the package's inference function (infer), he appreciates the time saved from building everything from the ground up. This feature allows him to effortlessly obtain the desired results for his specific road. Upon consulting the documentation, he proceeds to run the inference function.

results = infer(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)

Oeps! Exception?

exception =
+│    Variables [ a, b ] have not been updated after an update event. 
+│    Therefore, make sure to initialize all required marginals and messages. See `initmarginals` and `initmessages` keyword arguments for the inference function. 
+│    See the function documentation for detailed information regarding the initialization.

After running the inference procedure an error appears, which prompts him to initialize all required messages and marginals. Now, John is left pondering the reason behind this requirement. Why is it necessary? Should he indeed initialize all messages and marginals? And if so, how might this impact the inference procedure?

Part 2. Why and What to initialize

Before delving too deeply into the details, it's important to understand that RxInfer constructs a factorized representation of your model using a Forney Style Factor Graph (FFG). In this structure, inference is executed through message passing.

A challenge arises when RxInfer generates the FFG representation with structural loops in certain parts of the graph. These loops indicate that a message or marginal within the loop depends not only on its prior but also on itself. Consequently, proper initialization is crucial for initiating the inference process. Two general rules of thumb guide this initialization, although the intricate details are beyond the scope of this tutorial:

1. Initiate as few messages/marginals as possible when dealing with a loop structure, it will be more efficient and accurate. 2. Prioritize initializing marginals over messages.

How to identify and handle the loops?

Identifying loops is currently a manual process, as the current version of RxInfer doesn't support a graphical representation of the created graph. As such, the manual process involves:

1. Deriving the graphical representation of the model, 2. Identifying loops and the messages or marginals that need to be initialized within the loop.

However, once you receive the message Variables [x, y, z] have not been updated after an update event, it is a good indication that there is a loop in your model. If you see this message, you should check your model for loops and try to initialize the messages and/or marginals that are part of the loop.

Deriving FFG and identifying the loops

John proceeds to derive the FFG for his problem where he identifies where the loops are:

Addons_messages

He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = infer(
+    model        = linear_regression(length(x_data)),
+    data         = (y = y_data, x = x_data),
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ),
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
+
+# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)
Example block output

Now the inference runs without the error! 🎉

as = rand(results.posteriors[:a], 100)
+bs = rand(results.posteriors[:b], 100)
+p = scatter(x_data, y_data, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data, a .* x_data .+ b, alpha = 0.05, color = :red)
+end
+plot(p, size = (900, 400))
Example block output
diff --git a/dev/search_index.js b/dev/search_index.js new file mode 100644 index 000000000..690a844dc --- /dev/null +++ b/dev/search_index.js @@ -0,0 +1,3 @@ +var documenterSearchIndex = {"docs": +[{"location":"manuals/delta-node/#delta-node-manual","page":"Delta node","title":"Delta node manual","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/#Features-and-Supported-Inference-Scenarios","page":"Delta node","title":"Features and Supported Inference Scenarios","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Gaussian Nodes: For delta nodes linked to strictly multivariate or univariate Gaussian distributions, the recommended methods are Linearization or Unscented transforms.\nExponential Family Nodes: For the delta node connected to nodes from the exponential family, the CVI (Conjugate Variational Inference) is the method of choice.\nStacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Methods Gaussian Nodes Exponential Family Nodes Stacking Delta Nodes\nLinearization ✓ ✗ ✓\nUnscented ✓ ✗ ✓\nCVI ✓ ✓ ✗","category":"page"},{"location":"manuals/delta-node/#Gaussian-Case","page":"Delta node","title":"Gaussian Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For clarity, consider the following example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=0.0, var=1.0)\n y ~ tanh(x)\n z ~ Normal(mean=y, var=1.0)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Unscented()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For a deeper understanding of the Unscented method and its parameters, consult the docstrings.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To execute the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"This methodology is consistent even when the delta node is associated with multiple nodes. For instance:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"f(x, g) = x*tanh(g)","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=1.0, var=1.0)\n g ~ Normal(mean=1.0, var=1.0)\n y ~ f(x, g)\n z ~ Normal(mean=y, var=0.1)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification is:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization())\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or simply","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))\nend","category":"page"},{"location":"manuals/delta-node/#Exponential-Family-Case","page":"Delta node","title":"Exponential Family Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example1()\n z = datavar(Float64)\n x ~ Gamma(shape=1.0, rate=1.0)\n y ~ tanh(x)\n z ~ Bernoulli(y)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification can be represented as:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using StableRNGs\nusing Optimisers\n\ndelta_meta = @meta begin \n tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Consult the ProdCVI docstrings for a detailed explanation of these parameters.","category":"page"},{"location":"manuals/inference/postprocess/#user-guide-inference-postprocess","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"","category":"section"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:","category":"page"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"DefaultPostprocess\nUnpackMarginalPostprocess\nNoopPostprocess","category":"page"},{"location":"manuals/inference/postprocess/#RxInfer.DefaultPostprocess","page":"Inference results postprocessing","title":"RxInfer.DefaultPostprocess","text":"DefaultPostprocess picks the most suitable postprocessing step automatically\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.UnpackMarginalPostprocess","page":"Inference results postprocessing","title":"RxInfer.UnpackMarginalPostprocess","text":"This postprocessing step removes the Marginal wrapper type from the result\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.NoopPostprocess","page":"Inference results postprocessing","title":"RxInfer.NoopPostprocess","text":"This postprocessing step does nothing\n\n\n\n\n\n","category":"type"},{"location":"manuals/understanding-why-to-initialize-messages/#Understating-why-we-need-to-initialize-messages-in-RxInfer","page":"Messages initialization","title":"Understating why we need to initialize messages in RxInfer","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"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.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Part-1.-Framing-the-problem","page":"Messages initialization","title":"Part 1. Framing the problem","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"John has recently acquired a new car and is keenly interested in its fuel consumption rate. He holds the belief that this rate follows a linear relationship with the variable speed. To validate this hypothesis, he plans to conduct tests by driving his car on the urban roads close to his home, recording both the fuel consumption and speed data. To ascertain the fuel consumption rate, John has opted for Bayesian linear regression as his analytical method.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"using Random, Plots, StableRNGs\n\nfunction generate_data(a, b, v, nr_samples; rng = StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;\n\n# For demonstration purposes we generate some fake data \nx_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Univariate-regression-with-known-noise","page":"Messages initialization","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"using RxInfer\n\n@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Delighted with the convenience offered by the package's inference function (infer), he appreciates the time saved from building everything from the ground up. This feature allows him to effortlessly obtain the desired results for his specific road. Upon consulting the documentation, he proceeds to run the inference function.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Oeps! Exception?","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"exception =\n│ Variables [ a, b ] have not been updated after an update event. \n│ Therefore, make sure to initialize all required marginals and messages. See `initmarginals` and `initmessages` keyword arguments for the inference function. \n│ See the function documentation for detailed information regarding the initialization.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"After running the inference procedure an error appears, which prompts him to initialize all required messages and marginals. Now, John is left pondering the reason behind this requirement. Why is it necessary? Should he indeed initialize all messages and marginals? And if so, how might this impact the inference procedure?","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Part-2.-Why-and-What-to-initialize","page":"Messages initialization","title":"Part 2. Why and What to initialize","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Before delving too deeply into the details, it's important to understand that RxInfer constructs a factorized representation of your model using a Forney Style Factor Graph (FFG). In this structure, inference is executed through message passing.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"A challenge arises when RxInfer generates the FFG representation with structural loops in certain parts of the graph. These loops indicate that a message or marginal within the loop depends not only on its prior but also on itself. Consequently, proper initialization is crucial for initiating the inference process. Two general rules of thumb guide this initialization, although the intricate details are beyond the scope of this tutorial:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"1.\tInitiate as few messages/marginals as possible when dealing with a loop structure, it will be more efficient and accurate. 2.\tPrioritize initializing marginals over messages.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"How to identify and handle the loops?","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Identifying loops is currently a manual process, as the current version of RxInfer doesn't support a graphical representation of the created graph. As such, the manual process involves:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"1.\tDeriving the graphical representation of the model, 2.\tIdentifying loops and the messages or marginals that need to be initialized within the loop.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"However, once you receive the message Variables [x, y, z] have not been updated after an update event, it is a good indication that there is a loop in your model. If you see this message, you should check your model for loops and try to initialize the messages and/or marginals that are part of the loop.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Deriving-FFG-and-identifying-the-loops","page":"Messages initialization","title":"Deriving FFG and identifying the loops","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"John proceeds to derive the FFG for his problem where he identifies where the loops are:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)\n\n# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Now the inference runs without the error! 🎉","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"as = rand(results.posteriors[:a], 100)\nbs = rand(results.posteriors[:b], 100)\np = scatter(x_data, y_data, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data, a .* x_data .+ b, alpha = 0.05, color = :red)\nend\nplot(p, size = (900, 400))","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification","page":"Model specification","title":"Model Specification","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Model options, model_arguments and model_keyword_arguments are optional and may be omitted:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name()\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function my_model(model_arguments...)\n # model specification here\n # ...\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"generator = my_model(model_arguments...)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"In order to create an instance of the model object we should use the create_model function:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"model, (x, y) = create_model(generator)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.","category":"page"},{"location":"manuals/model-specification/#A-full-example-before-diving-in","page":"Model specification","title":"A full example before diving in","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function state_space_model(n_observations, noise_variance)\n\n c = constvar(1.0)\n x = randomvar(n_observations)\n y = datavar(Float64, n_observations)\n\n x[1] ~ NormalMeanVariance(0.0, 100.0)\n\n for i in 2:n_observations\n x[i] ~ x[i - 1] + c\n y[i] ~ NormalMeanVariance(x[i], noise_var)\n end\n\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/#Graph-variables-creation","page":"Model specification","title":"Graph variables creation","text":"","category":"section"},{"location":"manuals/model-specification/#user-guide-model-specification-constant-variables","page":"Model specification","title":"Constants","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"You can create a constant within a model specification macro with constvar() function. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n c = constvar(1.0)\n\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nconstvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(nsamples::Int, c::ConstVariable)\n ...\n # no need to call for a constvar() here\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\n::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-data-variables","page":"Model specification","title":"Data variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64) # Creates a single data input with `y` as identificator\n y = datavar(Float64, n) # Returns a vector of `y_i` data input objects with length `n`\n y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`\n y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\ndatavar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"datavar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64, n) where { allow_missing = true }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Data-variables-available-options","page":"Model specification","title":"Data variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-random-variables","page":"Model specification","title":"Random variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n x = randomvar() # Returns a single random variable which can be used later in the model\n x = randomvar(n) # Returns an vector of random variables with length `n`\n x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`\n x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nrandomvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = randomvar() where { prod_constraint = ProdGeneric() }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Random-variables-available-options","page":"Model specification","title":"Random variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"prod_constraint\nprod_strategy\nmarginal_form_constraint\nmarginal_form_check_strategy\nmessages_form_constraint\nmessages_form_check_strategy\npipeline","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.","category":"page"},{"location":"manuals/model-specification/#Node-creation","page":"Model specification","title":"Node creation","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables. ","category":"page"},{"location":"manuals/model-specification/#Distributions.jl-compatibility","page":"Model specification","title":"Distributions.jl compatibility","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.\nDepending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.\nIn certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.","category":"page"},{"location":"manuals/model-specification/#Tilde-syntax","page":"Model specification","title":"Tilde syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n m = randomvar()\n v = randomvar()\n y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Another example, but using a deterministic relation between random variables:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n a = randomvar()\n b = randomvar()\n c ~ a + b\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nThe RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nIt is forbidden to use random variable within square brackets in the model specification.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.\n\ny ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is also possible to return a node reference from the ~ operator. Use the following syntax:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"node, y ~ NormalMeanVariance(mean, var)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.","category":"page"},{"location":"manuals/model-specification/#Broadcasting-syntax","page":"Model specification","title":"Broadcasting syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nBroadcasting syntax requires at least v2.1.0 of GraphPPL.jl ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y = datavar(Float64, n)\ny .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"More complex expression are also allowed:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"m ~ NormalMeanPrecision(0.0, 0.0001)\nt ~ Gamma(1.0, 1.0)\n\ny = randomvar(Float64, n)\ny .~ NormalMeanPrecision(m, t)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A = constvar(...)\nx = randomvar(n)\ny = datavar(Vector{Float64}, n)\n\nw ~ Wishart(3, diageye(2))\nx[1] ~ MvNormalMeanPrecision(zeros(2), diageye(2))\nx[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A\ny .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Suppose `x` is a 2-dimensional Gaussian distribution\nz .~ x .+ constvar([ 1, 1 ])\n# Which is equivalent to \nfor i in 1:n\n z[i] ~ x[i] + constvar([ 1, 1 ])\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Without explicit `constvar`\nz .~ x .+ [ 1, 1 ]\n# Which is equivalent to \narray = [1, 1]\nfor i in 1:n\n z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian \nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Read more about how broadcasting machinery works in Julia in the official documentation.","category":"page"},{"location":"manuals/model-specification/#Node-creation-options","page":"Model specification","title":"Node creation options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A list of the available options specific to the ReactiveMP inference engine is presented below.","category":"page"},{"location":"manuals/model-specification/#Factorisation-constraint-option","page":"Model specification","title":"Factorisation constraint option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"See also Constraints Specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"where RecognitionFactorisationConstraint can be the following","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"MeanField()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a mean-field factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"FullFactorisation()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a full factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"q(μ)q(v)q(out) or q(μ) * q(v) * q(out)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Using interface names of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names for some node\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }\n\n# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names aliases for some node\n# In general aliases correspond to the function names for distribution parameters\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }\n\n# Using random variables names from `~` operator expression\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }\n\n# All methods can be combined easily\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }","category":"page"},{"location":"manuals/model-specification/#Metadata-option","page":"Model specification","title":"Metadata option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"z ~ f(x, y) where { meta = ... }","category":"page"},{"location":"examples/overview/#examples-overview","page":"Overview","title":"Examples overview","text":"","category":"section"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"Basic examples: Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.\nAdvanced examples: Advanced examples contain more complex inference problems.\nProblem specific: Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference","page":"Manual inference specification","title":"Manual inference","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"For advanced use cases it is advised to use manual inference specification. ","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Create a model with @model macro and get a references to random variables and data inputs\nSubscribe to random variable posterior marginal updates \nSubscribe to Bethe Free Energy updates (optional)\nFeed model with observations \nUnsubscribe from posterior marginal updates (optional)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-model-creation","page":"Manual inference specification","title":"Model creation","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random\n\n@model function my_model()\n m2 ~ NormalMeanVariance(0.0, 1.0)\n m1 ~ NormalMeanVariance(m2, 1.0)\n\n y = datavar(Float64)\n y ~ NormalMeanVariance(m1, 1.0)\n\n # Return variables of interests, optional\n return m1, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"And later on we may create our model with the create_model function and obtain references for variables of interests:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m1, y) = create_model(my_model())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Alternatively, it is possible to query any variable using squared brackets on model object:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model[:m1] # m1\nmodel[:y] # y\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-marginal-updates","page":"Manual inference specification","title":"Posterior marginal updates","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_updates = getmarginal(m1)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"After that we can subscribe on new updates and perform some actions based on new values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin\n println(\"New posterior for m1: \", new_posterior)\nend)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function my_model()\n ...\n m_n = randomvar(n)\n ...\n return m_n, ...\nend\n\nmodel, (m_n, ...) = create_model(my_model())\n\nm_n_updates = getmarginals(m_n)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-observations","page":"Manual inference specification","title":"Feeding observations","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To feed an observation for a specific data input we use update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0) # Observation didn't change, should result in the same posterior\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"If y is an array of data inputs it is possible to pass an array of observation to update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"for i in 1:length(data)\n update!(y[i], data[i])\nend\n# is an equivalent of\nupdate!(y, data)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp","page":"Manual inference specification","title":"Variational Message Passing","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"real_mean = -4.0\nreal_precision = 0.2\nrng = MersenneTwister(1234)\n\nn = 100\ndata = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function normal_estimation(n)\n m ~ NormalMeanVariance(0.0, 10.0)\n w ~ Gamma(0.1, 10.0)\n\n y = datavar(Float64, n)\n\n for i in 1:n\n y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }\n end\n\n return m, w, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m, w, y) = create_model(normal_estimation(n))\n\n# We use vague initial marginals\nsetmarginal!(m, vague(NormalMeanVariance)) \nsetmarginal!(w, vague(Gamma))\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m_marginals = []\nw_marginals = []\n\nsubscriptions = subscribe!([\n (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),\n (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),\n])\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(subscriptions)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using Plots\n\np1 = plot(title = \"'Mean' posterior marginals\")\ngrid1 = -6.0:0.01:4.0\n\nfor iter in [ 1, 2, 10 ]\n\n estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = \"Estimated mean after $iter VMP iterations\")\n\nend\n\nplot!(p1, [ real_mean ], seriestype = :vline, label = \"Real mean\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"p2 = plot(title = \"'Precision' posterior marginals\")\ngrid2 = 0.01:0.001:0.35\n\nfor iter in [ 2, 3, 10 ]\n\n estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = \"Estimated precision after $iter VMP iterations\")\n\nend\n\nplot!(p2, [ real_precision ], seriestype = :vline, label = \"Real precision\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp-bfe","page":"Manual inference specification","title":"Computing Bethe Free Energy","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer package exports score function for an observable of free energy values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"fe_observable = score(model, BetheFreeEnergy())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"# Reset posterior marginals for `m` and `w`\nsetmarginal!(m, vague(NormalMeanVariance))\nsetmarginal!(w, vague(Gamma))\n\nfe_values = []\n\nfe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(fe_subscription)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"plot(fe_values, label = \"Bethe Free Energy\", xlabel = \"Iteration #\")","category":"page"},{"location":"contributing/new-package/#Contributing-to-the-dependencies","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.","category":"page"},{"location":"contributing/new-package/#The-benefits-of-small-packages-for-the-ecosystem","page":"Contributing to the dependencies","title":"The benefits of small packages for the ecosystem","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.\nCollaboration: Teams can work on different packages concurrently, speeding up development.\nVersion Control: Precise versioning and fewer dependencies lead to leaner projects.\nPerformance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.\nFlexibility: Developers can select and customize packages for their needs.\nCommunity: Smaller packages attract contributors, fostering collaboration and faster feedback.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.","category":"page"},{"location":"contributing/new-package/#Use-[PkgTemplates](https://github.com/JuliaCI/PkgTemplates.jl)","page":"Contributing to the dependencies","title":"Use PkgTemplates","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> using PkgTemplates\n\njulia> USER = \"your github user name\" # Use `reactivebayes` if developing within the ReactiveBayes organisation\n\njulia> template = Template(\n user = USER, \n plugins = [\n CompatHelper(), \n ProjectFile(), \n SrcDir(), \n Git(), \n License(), \n Readme(), \n Tests(), \n GitHubActions(), \n Codecov(), \n Documenter{GitHubActions}(), \n Formatter(style=\"blue\"), \n BlueStyleBadge(), \n PkgEvalBadge()\n])\n\njulia> template(\"MyNewCoolPackage\")","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the minimum supported version of Julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9.2\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Try to be conservative and set as low version of Julia as possible.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the authors of the package","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The authors field is present in the Project.toml, e.g ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"authors = [\"John Wick \", ...]","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Add requires dependencies and their [compat] bounds","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"or ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] activate .","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Then, add dependencies like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] add SomeCoolDependency, SomeOtherCoolDependency","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9\"\nSomeCoolDependency = \"0.19.2\"\nSomeOtherCoolDependency = \"1.3.12\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For more details on compat bounds, check the official Julia documentation.","category":"page"},{"location":"contributing/new-package/#Adjust-README.md","page":"Contributing to the dependencies","title":"Adjust README.md","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"note: Note\nSome badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.","category":"page"},{"location":"contributing/new-package/#Write-code-and-tests","page":"Contributing to the dependencies","title":"Write code and tests","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.","category":"page"},{"location":"contributing/new-package/#Simplify-Testing-with-ReTestItems","page":"Contributing to the dependencies","title":"Simplify Testing with ReTestItems","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.","category":"page"},{"location":"contributing/new-package/#Write-code-and-the-documentation","page":"Contributing to the dependencies","title":"Write code and the documentation","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=docs docs/make.jl","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.","category":"page"},{"location":"contributing/new-package/#Hosting-Documentation-with-GitHub-Actions","page":"Contributing to the dependencies","title":"Hosting Documentation with GitHub Actions","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.","category":"page"},{"location":"contributing/new-package/#Enable-GitHub-Pages-in-Repository-Settings","page":"Contributing to the dependencies","title":"Enable GitHub Pages in Repository Settings","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Navigate to the GitHub Pages settings of your repository.\nChoose the Deploy from a branch option.\nSelect the gh-pages branch.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#examples-assessing-people’s-skills","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of \"Model-Based Machine Learning\" by Winn et al.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Problem-Statement","page":"Assessing People’s Skills","title":"Problem Statement","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We model the result for question i as a continuous variable r_iin01, and skill/attitude as a binary variable s_i in 0 1, where s_1 represents whether the student has partied, and s_2 and s_3 represent whether the student has studied the chapters for the corresponding questions.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We assume the following logic:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"If the student is alert (has not partied), then they will score on the first question;\nIf the student is alert or has studied chapter two, then they will score on question two;\nIf the student can answer question two and has studied chapter three, then they will score on question three.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Definition","page":"Assessing People’s Skills","title":"Generative Model Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"To model the probability for correct answers, we assume a latent state variable t_i in 01. The dependencies between the variables can then be modeled by the following Bayesian network:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"(s_1) (s_2) (s_3)\n | | |\n v v v\n(t_1)-->(t_2)-->(t_3)\n | | |\n v v v\n(r_1) (r_2) (r_3)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"As prior beliefs, we assume that a student is equally likely to study/party or not: s_i sim Ber(05) for all i. Next, we model the domain logic as beginaligned t_1 = s_1\n t_2 = t_1 s_2\n t_3 = t_2 s_3 endaligned For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as t_i sim Ber(s_i) for all i.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Custom-Nodes-and-Rules","page":"Assessing People’s Skills","title":"Custom Nodes and Rules","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"using RxInfer, Random\n\n# Create Score node\nstruct Score end\n\n@node Score Stochastic [out, in]","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Adding update rule for the Score node\n@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin \n return Bernoulli(mean(q_out))\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Specification","page":"Assessing People’s Skills","title":"Generative Model Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now build the full generative model.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# GraphPPL.jl exports the `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function skill_model()\n s = randomvar(3)\n t = randomvar(3)\n r = datavar(Float64, 3)\n\n # Priors\n for i=1:3\n s[i] ~ Bernoulli(0.5)\n end\n\n # Domain logic\n t[1] ~ ¬s[1]\n t[2] ~ t[1] || s[2]\n t[3] ~ t[2] && s[3]\n \n # Results\n for i=1:3\n r[i] ~ Score(t[i])\n end\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Inference-Specification","page":"Assessing People’s Skills","title":"Inference Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"test_results = [0.1, 0.1, 0.1]\ninference_result = infer(\n model = skill_model(),\n data = (r = test_results, )\n)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Inference results:\n Posteriors | available for (s, t)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Results","page":"Assessing People’s Skills","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Inspect the results\nmap(params, inference_result.posteriors[:s])","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"3-element Vector{Tuple{Float64}}:\n (0.9872448979591837,)\n (0.06377551020408162,)\n (0.4719387755102041,)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"These results suggest that this particular student was very likely out on the town last night.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#examples-predicting-bike-rental-demand","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using RxInfer","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Preamble:-Enabling-Predictions","page":"Predicting Bike Rental Demand","title":"Preamble: Enabling Predictions","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"RxInfer.jl facilitates predictions in two primary ways. ","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.\nExplicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Example","page":"Predicting Bike Rental Demand","title":"Example","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Consider the following model:","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"@model function example_model()\n y = datavar(Float64) where {allow_missing = true}\n\n h ~ NormalMeanPrecision(0, 1.0)\n x ~ NormalMeanPrecision(h, 1.0)\n y ~ NormalMeanPrecision(x, 10.0)\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Implicit Prediction\nresult = infer(model = example_model(), data = (y = missing,))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Explicit Prediction\nresult = infer(model = example_model(), predictvars = (y = KeepLast(),))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using CSV, DataFrames, Plots","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Objective","page":"Predicting Bike Rental Demand","title":"Objective","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Dataset-Source","page":"Predicting Bike Rental Demand","title":"Dataset Source","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Load the data\ndf = CSV.read(\"../data/bike_count/modified_bicycle.csv\", DataFrame)\ndf[1:10, :]","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"10×6 DataFrame\n Row │ datetime temp atemp humidity windspeed count\n │ String31 Float64 Float64 Float64 Float64 Int64\n─────┼──────────────────────────────────────────────────────────────────\n 1 │ 2011-01-01 0:00:00 9.84 14.395 81.0 0.0 16\n 2 │ 2011-01-01 1:00:00 9.02 13.635 80.0 0.0 40\n 3 │ 2011-01-01 2:00:00 9.02 13.635 80.0 0.0 32\n 4 │ 2011-01-01 3:00:00 9.84 14.395 75.0 0.0 13\n 5 │ 2011-01-01 4:00:00 9.84 14.395 75.0 0.0 1\n 6 │ 2011-01-01 5:00:00 9.84 12.88 75.0 6.0032 1\n 7 │ 2011-01-01 6:00:00 9.02 13.635 80.0 0.0 2\n 8 │ 2011-01-01 7:00:00 8.2 12.88 86.0 0.0 3\n 9 │ 2011-01-01 8:00:00 9.84 14.395 75.0 0.0 8\n 10 │ 2011-01-01 9:00:00 13.12 17.425 76.0 0.0 14","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# we reserve few samples for prediction\nn_future = 24\n\nX = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]\ny = Union{Float64, Missing}[df[:, \"count\"]...][1:end-n_future]\n\nstate_dim = length(X[1]); # dimensionality of feature space","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Generative-Model-with-Priors","page":"Predicting Bike Rental Demand","title":"Generative Model with Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"We present a generative model that delineates the latent dynamics of feature evolution, represented by mathbfh_t, and their link to the bike rental counts, mathbfy_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Equations-and-Priors","page":"Predicting Bike Rental Demand","title":"Equations and Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Feature Dynamics with Prior:\nPrior: mathbfa sim mathcalN(mathbf0 mathbfI)\nDynamics: mathbfh_t sim mathcalN(mathbfA h_t-1 mathbfQ)\nmathbfA\nis the transition matrix, reshaped from the prior vector mathbfa, and mathbfQ represents process noise.\nNoisy Observations:\nmathbfx_t sim mathcalN(mathbfh_t mathbfP)\nRepresents the observed noisy state of the features.\nCount Prediction with Prior:\nPrior: boldsymboltheta sim mathcalN(mathbf0 mathbfI)\nPrediction: y_t sim mathcalN(textsoftplus(boldsymboltheta^topmathbfh_t) sigma^2)\nModels the bike rental count as influenced by a non-linear transformation of the hidden state.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Interpretation","page":"Predicting Bike Rental Demand","title":"Interpretation","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This framework aims to simultaneously infer the transition matrix mathbfA and the regression parameters boldsymboltheta, providing a comprehensive view of the feature space dynamics and the count prediction.\nBy employing Gaussian priors on both mathbfa and boldsymboltheta, we incorporate beliefs about their distributions.\nThe inference process aims to discover these underlying dynamics, enabling predictions of both features mathbfx_t and counts y_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We augument the dataset with missing entries for 24 hours ahead\nappend!(X, repeat([missing], n_future))\nappend!(y, repeat([missing], n_future));","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Function to perform the state transition in the model.\n# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.\nfunction transition(a, x)\n nm, n = length(a), length(x)\n m = nm ÷ n # Calculate the number of rows for reshaping 'a' into a matrix\n A = reshape(a, (m, n)) \n return A * x\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"transition (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# The dotsoftplus function combines a dot product and softplus transformation.\n# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,\n# especially if the data suggests other forms of relationships or distributions.\nfunction dotsoftplus(a, x)\n log(1 + exp(dot(a, x)))\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"dotsoftplus (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# model definction\n@model function bicycle_ssm(n, h0, θ0, a0, Q, P)\n\n # `h` is a sequence of hidden states\n h = randomvar(n)\n\n # `x` is a sequence of observed states (features)\n x = datavar(Vector{Float64}, n) where {allow_missing = true}\n # `y` is a sequence of \"count\" bicycles\n y = datavar(Float64, n) where {allow_missing = true}\n\n a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))\n\n θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))\n\n h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))\n h_prev = h_prior\n \n for i in 1:n\n \n h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)\n \n x[i] ~ MvNormal(μ=h[i], Σ=P)\n \n y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)\n \n h_prev = h[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.\n# However, alternative methods like Unscented or CVI approximations can also be considered.\ntransition_meta = @meta begin \n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Meta specification:\n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We define rather uninformative priors \nprior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))\nprior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))\nprior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"MvNormalMeanCovariance(\nμ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0\n.0, 0.0]\nΣ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … \n0.0 1.0]\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages\nimessages = ( h = prior_h, a = prior_a, θ = prior_θ,)\n\nbicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))\n\nresult = infer(\n model = bicycle_model,\n data = (y = y, x=X), \n options = (limit_stack_depth = 500, ), \n returnvars = KeepLast(),\n initmessages = imessages,\n meta = transition_meta,\n iterations = 20,\n showprogress=true,\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (a, h, h_prior, θ)\n Predictions | available for (y, x)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# For a sake of this example, we extract only predictions\nmean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])\nmean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])\n\nmean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)\nmean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)\nmean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)\nmean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"slice = (300, length(y))\ndata = df[:, \"count\"][length(y)-n_future:length(y)]\n\np = scatter(y, \n color=:darkblue, \n markerstrokewidth=0,\n label=\"Observed Count\", \n alpha=0.6)\n\n# Plotting the mean prediction with variance ribbon\nplot!(mean_y, ribbon=sqrt.(cov_y), \n color=:orange, \n fillalpha=0.3,\n label=\"Predicted Mean ± Std Dev\")\n\n# Adding a vertical line to indicate the start of the future prediction\nvline!([length(y)-n_future], \n label=\"Prediction Start\", \n linestyle=:dash, \n linecolor=:green)\n\n# Future (unobserved) data\nplot!(length(y)-n_future:length(y), data, label=\"Future Count\")\n\n# Adjusting the limits\nxlims!(slice)\n\n# Enhancing the plot with titles and labels\ntitle!(\"Bike Rental Demand Prediction\")\nxlabel!(\"Time\")\nylabel!(\"Bike Count\")\n\n# Adjust the legend\nlegend=:topright\n\n# Show the final plot\ndisplay(p)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using Plots\n\n# Define a color palette\npalette = cgrad(:viridis)\n\n# Plot the hidden states with observations\np1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label=\"Hidden State 1\", legend=:topleft)\nplot!(df[!, :temp], color=:grey, label=\"Temperature\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Temperature vs Hidden State 1\")\n\np2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label=\"Hidden State 2\", legend=:topleft)\nplot!(df[!, :atemp], color=:grey, label=\"Feels-Like Temp\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Feels-Like Temp vs Hidden State 2\")\n\np3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label=\"Hidden State 3\", legend=:topleft)\nplot!(df[!, :humidity], color=:grey, label=\"Humidity\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Humidity vs Hidden State 3\")\n\np4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label=\"Hidden State 4\", legend=:topleft)\nplot!(df[!, :windspeed], color=:grey, label=\"Windspeed\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Windspeed vs Hidden State 4\")\n\nfor p in [p1, p2, p3, p4]\n xlims!(p, first(slice), last(slice))\nend\n\nplot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Conclusion","page":"Predicting Bike Rental Demand","title":"Conclusion","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.","category":"page"},{"location":"manuals/comparison/#comparison","page":"RxInfer.jl vs. Others","title":"Comparison to other packages","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"DISCLAIMER: ","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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, and we'll be more than willing to rectify.\nThe comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Toolbox Universality Efficiency Expressiveness Debugging & Visualization Modularity Inference Engine Language Community & Ecosystem\nRxInfer.jl ~ ✓ ✓ ~ ✗ Message-passing Julia ✗\nForneyLab.jl ✗ ~ ✗ ~ ✗ Message-passing Julia ✗\nInfer.net ~ ✓ ✗ ✓ ✗ Message-passing C# ✗\nPGMax ✗ ✓ ✗ ✓ ✗ Message-passing Python ✗\nTuring.jl ✓ ✗ ✓ ~ ✗ Sampling Julia ✓\nPyMC ✓ ✗ ✓ ✓ ✗ Sampling Python ✓\nNumPyro ✓ ✓ ~ ✓ ✗ Sampling Python ✓\nTensorFlow Probability ✓ ✗ ~ ✓ ✗ Sampling Python ✓\nStan ✓ ✗ ✓ ✓ ✗ Sampling Stan ✓","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"(Date of creation: 20/10/2023)","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Legend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"✓ : Full capability or feature is present.\n~ : Partial capability or feature is present.\n✗ : No capability or feature.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Notes:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: Denotes the capability to depict a vast array of probabilistic models.\nEfficiency: Highlights computational competence. A \"–\" in this context suggests perceived slowness.\nExpressiveness: Assesses the ability to concisely formulate intricate probabilistic models.\nDebugging & Visualization: Evaluates the suite of tools for model debugging and visualization.\nModularity: Reflects the potential to create models by integrating smaller models.\nInference Engines: Pinpoints the primary inference strategy employed by the toolbox.\nLanguage: Identifies the programming language integral to the toolbox.\nCommunity & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"","category":"page"},{"location":"manuals/comparison/#RxInfer.jl-breakdown","page":"RxInfer.jl vs. Others","title":"RxInfer.jl breakdown","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.\nEfficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.\nModularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"@model function inner_inner(τ, y)\n y ~ Normal(τ[1], τ[2])\nend\n\n@model function inner(θ, α)\n β ~ Normal(0, 1)\n α ~ Gamma(β, 1)\n α ~ inner_inner(τ = θ)\nend\n\n@model function outer()\n local w\n for i = 1:5\n w[i] ~ inner(θ = Gamma(1, 1))\n end\n y ~ inner(θ = w[2:3])\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"beginaligned\n x sim mathrmNormal(00 10)\n w sim mathrmInverseGamma(10 10)\n y sim mathrmNormal(x w)\nendaligned","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"The model then is expressed in RxInfer.jl as follows:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"using RxInfer\n\n@model function example_model()\n x ~ Normal(mean=0.0, var=1.0)\n w ~ InverseGamma(α = 1, θ = 1)\n y ~ Normal(mean = x, var = w)\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#examples-infinite-data-stream","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"using RxInfer, Plots, Random, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"mutable struct Environment\n rng :: AbstractRNG\n current_state :: Float64\n observation_precision :: Float64\n history :: Vector{Float64}\n observations :: Vector{Float64}\n \n Environment(current_state, observation_precision; seed = 123) = begin \n return new(StableRNG(seed), current_state, observation_precision, [], [])\n end\nend\n\nfunction getnext!(environment::Environment)\n environment.current_state = environment.current_state + 1.0\n nextstate = 10sin(0.1 * environment.current_state)\n observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))\n push!(environment.history, nextstate)\n push!(environment.observations, observation)\n return observation\nend\n\nfunction gethistory(environment::Environment)\n return environment.history\nend\n\nfunction getobservations(environment::Environment)\n return environment.observations\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"getobservations (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Model-specification","page":"Infinite Data Stream","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"@model function kalman_filter()\n \n # Prior for the previous state\n x_prev_mean = datavar(Float64)\n x_prev_var = datavar(Float64)\n \n x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)\n \n # Prior for the observation noise\n τ_shape = datavar(Float64)\n τ_rate = datavar(Float64)\n \n τ ~ Gamma(shape = τ_shape, rate = τ_rate)\n \n # Random walk with fixed precision\n x_current ~ Normal(mean = x_prev, precision = 1.0)\n \n # Noisy observation\n y = datavar(Float64)\n y ~ Normal(mean = x_current, precision = τ)\n \nend\n\n# We assume the following factorisation between variables \n# in the variational distribution\n@constraints function filter_constraints()\n q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"filter_constraints (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Prepare-environment","page":"Infinite Data Stream","title":"Prepare environment","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"initial_state = 0.0\nobservation_precision = 0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"After we have created the environment we can observe how our signal behaves:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"testenvironment = Environment(initial_state, observation_precision);\n\nanimation = @animate for i in 1:100\n getnext!(testenvironment)\n \n history = gethistory(testenvironment)\n observations = getobservations(testenvironment)\n \n p = plot(size = (1000, 300))\n \n p = plot!(p, 1:i, history[1:i], label = \"Hidden signal\")\n p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = \"Observation\")\nend\n\ngif(animation, \"../pics/infinite-data-stream.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-static-dataset","page":"Infinite Data Stream","title":"Filtering on static dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"n = 300\nstatic_environment = Environment(initial_state, observation_precision);\n\nfor i in 1:n\n getnext!(static_environment)\nend\n\nstatic_history = gethistory(static_environment)\nstatic_observations = getobservations(static_environment);\nstatic_datastream = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_static(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n keephistory = 10_000,\n historyvars = (x_current = KeepLast(), τ = KeepLast()),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n free_energy = true,\n autostart = true,\n )\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_static (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"result = run_static(static_environment, static_datastream);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"static_inference = @animate for i in 1:n\n estimated = result.history[:x_current]\n p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = \"Estimation\")\n p = plot!(static_history[1:i], label = \"Real states\") \n p = scatter!(static_observations[1:i], ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\nend\n\ngif(static_inference, \"../pics/infinite-data-stream-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"plot(result.free_energy_history, label = \"Bethe Free Energy (averaged)\")","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-realtime-dataset","page":"Infinite Data Stream","title":"Filtering on realtime dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"Next lets create a \"real\" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_and_plot(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n posteriors = []\n \n plotfn = (q_current) -> begin \n IJulia.clear_output(true)\n \n push!(posteriors, q_current)\n\n p = plot(mean.(posteriors), ribbon = var.(posteriors), label = \"Estimation\")\n p = plot!(gethistory(environment), label = \"Real states\") \n p = scatter!(getobservations(environment), ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\n\n display(p)\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n autostart = false,\n )\n \n qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)\n \n RxInfer.start(engine)\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_and_plot (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# This example runs in our documentation pipeline, which does not support \"real-time\" execution context\n# We skip this code if run not in Jupyter notebook (see below an example with gif)\nengine = nothing \nif isdefined(Main, :IJulia)\n timegen = 41 # 41 ms\n environment = Environment(initial_state, observation_precision);\n observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations\n datastream = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));\n engine = run_and_plot(environment, datastream)\nend;","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"if !isnothing(engine) && isdefined(Main, :IJulia)\n RxInfer.stop(engine)\n IJulia.clear_output(true)\nend;","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#examples-universal-mixtures","page":"Universal Mixtures","title":"Universal Mixtures","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"using RxInfer, Distributions, Random, Plots","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y_i mid theta) = mathrmBer(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where y_i in 01 are the outcomes of the coin tosses, i.e. heads or tails, and where theta is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter theta, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of thetain01 they come up with the prior beliefs:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJohn) = mathrmBeta(theta mid 7 2)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJane) = mathrmBeta(theta mid 2 7)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior beliefs\")\nplot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) John\", c=1)\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"p(θ) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"true_coin = Bernoulli(0.25)\nnr_throws = 10\ndataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))\nnr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)\nprintln(\"experimental outcome: \\n - heads: \", nr_heads, \"\\n - tails: \", nr_tails);","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"experimental outcome: \n - heads: 3\n - tails: 7","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"For computing the posterior beliefs p(theta mid y) about the parameter theta, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#John's-model:","page":"Universal Mixtures","title":"John's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJohn) = p(theta mid textJohn) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_john(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's prior model over θ\n θ ~ Beta(7.0, 2.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#Jane's-model:","page":"Universal Mixtures","title":"Jane's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJane) = p(theta mid textJane) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_jane(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify Jane's prior model over θ\n θ ~ Beta(2.0, 7.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy mathrmF_B bounds the model evidence p(y) as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"mathrmF_Bpq geq - ln p(y)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_john = infer(\n model = beta_model_john(nr_throws), \n data = (y = dataset, ),\n free_energy = true,\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[8.96366]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_jane = infer(\n model = beta_model_jane(nr_throws), \n data = (y = dataset, ),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[6.63988]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying theta parameter. They formulate this through the posterior distributions p(theta mid y textJohn) and p(theta mid y textJane):","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior beliefs\")\nplot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) John\", c=1)\nplot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"p(θ|y) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over theta, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta c mid textMary) = p(c mid textMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where c describes the probability of John being correct as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(c mid textMary) = mathrmBer(c mid 07)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"The predictive distribution p(theta mid textMary) for theta (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over c as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textMary) = sum_cin01 p(cmidtextMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c = 07 cdot p(theta mid textJohn) + 03 cdot p(theta mid textJane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior belief\")\nplot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) Mary\", c=1)\nplot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label=\"\")\nplot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label=\"\")","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_mary(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's and Jane's prior models over θ\n θ_jane ~ Beta(2.0, 7.0)\n θ_john ~ Beta(7.0, 2.0)\n\n # specify initial guess as to who is right\n john_is_right ~ Bernoulli(0.7) \n\n # specify mixture prior Distribution\n θ ~ Mixture(john_is_right, (θ_jane, θ_john))\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This Mixture node updates the belief over c on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_mary = infer(\n model = beta_model_mary(nr_throws), \n data = (y = dataset, ),\n returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),\n addons = AddonLogScale(),\n postprocess = UnpackMarginalPostprocess(),\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (john_is_right, θ_john, θ, θ_jane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over theta also changed, and as expected the estimate from Jane was more prominent.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior belief\")\nplot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) Mary\", c=1)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label=\"\", c=3)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label=\"\", c=3)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/overview/#examples-basic_examples-overview","page":"Overview","title":"Basic examples","text":"","category":"section"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.\nBayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.\nKalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations\nPredicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.\nHow to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#examples-global-parameter-optimisation","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Univariate-State-Space-Model","page":"Global Parameter Optimisation","title":"Univariate State Space Model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us try use the following simple state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n x_t = x_t-1 + c \n y_t sim mathcalNleft(x_t p right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Our goal is to optimize parameters c and m_x_0.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)\n \n x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n)\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ x_prev + c\n y[i] ~ NormalMeanVariance(x[i], P)\n \n x_prev = x[i]\n end\n\n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"rng = MersenneTwister(42)\n\nP = 1.0\nn = 250\nc_real = -5.0\ndata = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# c[1] is C\n# c[2] is μ0\nfunction f(c)\n x0_prior = NormalMeanVariance(c[2], 100.0)\n result = infer(\n model = smoothing(n, x0_prior, c[1], P), \n data = (y = data,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using Optim","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 3.651509e+02 1.001412e+03\n * time: 0.023710012435913086\n * Status: success\n\n * Candidate solution\n Final objective value: 3.645772e+02\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.18e-06 ≰ 0.0e+00\n |x - x'|/|x'| = 2.30e-07 ≰ 0.0e+00\n |f(x) - f(x')| = 9.13e-07 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00\n |g(x)| = 2.56e-06 ≤ 1.0e-03\n\n * Work counters\n Seconds run: 6 (vs limit Inf)\n Iterations: 9\n f(x) calls: 67\n ∇f(x) calls: 67","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"2-element Vector{Float64}:\n 1.0007749243942134\n -5.14368311177876","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", [ 1.0, c_real ])\nprintln(\"Optimized: \", res.minimizer)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: [1.0, -5.0]\nOptimized: [1.0007749243942134, -5.14368311177876]","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Multivariate-state-space-model","page":"Global Parameter Optimisation","title":"Multivariate state space model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us consider the multivariate state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n mathbfx_t sim mathcalNleft(mathbfAx_t-1 mathbfQ right) \n mathbfy_t sim mathcalNleft(mathbfx_t mathbfP right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfx_0 sim mathcalN(mathbfm_x_0 mathbfV_x_0)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"and transition matrix ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfA = beginbmatrix costheta -sintheta sintheta costheta endbmatrix\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Covariance matrices mathbfV_x_0, mathbfP and mathbfQ are known. Our goal is to optimize parameters mathbfm_x_0 and theta.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)\n \n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n \n x_prev = x_prior\n \n A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)\n y[i] ~ MvNormalMeanCovariance(x[i], P)\n \n x_prev = x[i]\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Generate data\nfunction generate_rotate_ssm_data()\n rng = MersenneTwister(1234)\n\n θ = π / 8\n A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\n Q = Matrix(Diagonal(1.0 * ones(2)))\n P = Matrix(Diagonal(1.0 * ones(2)))\n\n n = 300\n\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n \n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(x[i], Q))\n \n x_prev = x[i]\n end\n\n return θ, A, Q, P, n, x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"generate_rotate_ssm_data (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"θ, A, Q, P, n, x, y = generate_rotate_ssm_data();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function f(θ)\n x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))\n result = infer(\n model = rotate_ssm(n, θ[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 2.192003e+04 9.032537e+04\n * time: 7.295608520507812e-5\n * Status: success\n\n * Candidate solution\n Final objective value: 1.161372e+03\n\n * Found with\n Algorithm: L-BFGS\n\n * Convergence measures\n |x - x'| = 5.09e-09 ≰ 0.0e+00\n |x - x'|/|x'| = 4.48e-10 ≰ 0.0e+00\n |f(x) - f(x')| = 0.00e+00 ≤ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14\n |g(x)| = 5.63e-07 ≰ 1.0e-12\n\n * Work counters\n Seconds run: 20 (vs limit Inf)\n Iterations: 9\n f(x) calls: 58\n ∇f(x) calls: 58","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", θ)\nprintln(\"Optimized: \", res.minimizer[1])\n\n@show sin(θ), sin(res.minimizer[1])\n@show cos(θ), cos(res.minimizer[1])","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: 0.39269908169872414\nOptimized: 0.3929332481380117\n(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)\n(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)\n(0.9238795325112867, 0.9237898955654058)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))\n\nresult = infer(\n model = rotate_ssm(n, res.minimizer[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n)\n\nxmarginals = result.posteriors[:x]\n\npx = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"inf₁\")\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"inf₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Learning-Kalman-filter-with-LSTM-driven-dynamic","page":"Global Parameter Optimisation","title":"Learning Kalman filter with LSTM driven dynamic","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Our objective is to compute the marginal posterior distribution of the latent (hidden) state x_k at each time step k, considering the history of measurements up to that time step:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"\np(x_k y_1k)\n\n\nThe above expression represents the probability distribution of the latent state x_k given the measurements y_1k up to time step k\n\njulia\nusing RxInfer BenchmarkTools Flux ReverseDiff Random Plots LinearAlgebra ProgressMeter JLD StableRNGs\n\n\n\n\n Generate data\n\njulia\n Lorenz system equations to be used to generate dataset\nBasekwdef mutable struct Lorenz\n dtFloat64\n σFloat64\n ρFloat64\n βFloat64\n xFloat64\n yFloat64\n zFloat64\nend\n\nfunction step(lLorenz)\n dx = lσ * (ly - lx) lx += ldt * dx\n dy = lx * (lρ - lz) - ly ly += ldt * dy\n dz = lx * ly - lβ * lz lz += ldt * dz\nend\n\n\n\n\njulia\n Dataset\nrng = StableRNG(999)\n\nordered_dataset = \nordered_parameters = \nfor σ = 1115\n for ρ = 2327\n for β_nom = 69\n attractor = Lorenz(002 σ ρ β_nom30 1 1 1)\n noise_free_data = 10 10 10\n for i=199\n step(attractor)\n push(noise_free_data attractorx attractory attractorz)\n end\n push(ordered_dataset noise_free_data)\n push(ordered_parameters σ ρ β_nom30)\n end\n end\nend\n\nnew_order = collect(1100)\nshuffle(rngnew_order)\n\ndataset = noisy dataset\nnoise_free_dataset = noise free dataset\nlorenz_parameters = \n\nfor i in new_order\n local data = \n push(noise_free_dataset ordered_dataseti)\n push(lorenz_parameters ordered_parametersi)\n for nfd in ordered_dataseti\n push(datanfd+randn(rng3))\n end\n push(dataset data)\nend\n\ntrainset = dataset160\nvalidset = dataset6180\ntestset = dataset81end\n\nnoise_free_trainset = noise_free_dataset160\nnoise_free_validset = noise_free_dataset6180\nnoise_free_testset = noise_free_dataset81end\n\n\n\n\n\n Data visualization\n\njulia\none_nonoise=noise_free_trainset1\none=trainset1\ngx gy gz = zeros(100) zeros(100) zeros(100)\nrx ry rz = zeros(100) zeros(100) zeros(100)\nfor i=1100\n rxi ryi rzi = onei1 onei2 onei3\n gxi gyi gzi = one_nonoisei1 one_nonoisei2 one_nonoisei3\nend\np1=plot(rxrylabel=Noise observations)\np1=plot(gxgylabel=True state)\nxlabel(x)\nylabel(y)\np2=plot(rxrzlabel=Noise observations)\np2=plot(gxgzlabel=True state)\nxlabel(x)\nylabel(z)\np3=plot(ryrzlabel=Noise observations)\np3=plot(gygzlabel=True state)\nxlabel(y)\nylabel(z)\nplot(p1 p2 p3 size = (800 200)layout=(13))\n\n\n(assetsexamplesGlobal Parameter Optimisation_22_1png)\n\n\n Inference\n\n\nWe use the following state-space model representation\n\nbeginaligned\nx_k sim p(x_k x_k-1) \ny_k sim p(y_k x_k)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where x_k sim p(x_k x_k-1) represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k-1=NN(y_k-1) \np(x_k x_k-1)=mathcalN(x_k A_k-1x_k-1 Q) \np(y_k x_k)=mathcalN(y_k Bx_k R)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where NN is the neural network. The input is the observation y_k-1, and output is the trasition matrix A_k-1. B denote distortion or measurment matrix. Q and R are covariance matrices. Note that the hidden state x_k comprises three coordinates, i.e. x_k = (rx_k ry_k rz_k)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Neural Network model\nmutable struct NN\n InputLayer\n OutputLater\n g\n params\n function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n InputLayer = Dense(W1, b1, relu)\n Lstm = LSTM(W2_1,W2_2,b2,s2_1)\n OutputLayer = Dense(W3, b3)\n g = Chain(InputLayer, OutputLayer);\n new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))\n end\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Model-specification","page":"Global Parameter Optimisation","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Note that we treat the trasition matrix A_k-1 as time-varying.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#State Space Model\n@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)\n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior_mean = zeros(3)\n x_prior_cov = Matrix(Diagonal(ones(3)))\n \n x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)\n y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }\n \n for i in 2:n\n x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }\n y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }\n end\n \n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We set distortion matrix B and the covariance matrices Q and R as identity matrix.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Q = Matrix(Diagonal(ones(3)))*2\nB = Matrix(Diagonal(ones(3)))\nR = Matrix(Diagonal(ones(3)))\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix A output by the neural network. And the A is treated as a datavar in the inference function.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n n = length(data)\n neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])\n return As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"get_matrix_AS (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"The weights of neural network NN are initialized as follows:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Initial model parameters\nW1, b1 = randn(5, 3)./100, randn(5)./100\nW2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)\nW3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Before network training, we show the inference results for the hidden states:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset before training\nindex = 1\ndata=testset[index]\nn=length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training-network","page":"Global Parameter Optimisation","title":"Training network","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this part, we use the Free Energy as the objective function to optimize the weights of network.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# free energy objective to be optimized during training\nfunction fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n fe_ = 0\n for train_instance in trainset\n result = infer(\n model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = train_instance, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n )\n fe_ += result.free_energy[end]\n end\n return fe_\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"fe_tot_est (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training","page":"Global Parameter Optimisation","title":"Training","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights\n# Uncomment the following code to train the network manually\n# opt = Flux.Optimise.RMSProp(0.006, 0.95)\n# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n# @showprogress for epoch in 1:800\n# grads = ReverseDiff.gradient(fe_tot_est, params);\n# for i=1:length(params)\n# Flux.Optimise.update!(opt,params[i],grads[i])\n# end\n# end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Test","page":"Global Parameter Optimisation","title":"Test","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Import the weights of neural network that we have trained.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load(\"../data/nn_prediction/weights.jld\")[\"data\"];","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset after training\nindex = 1\ndata = testset[index]\nn = length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\n\ngx, gy, gz = zeros(100), zeros(100), zeros(100)\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Prediction","page":"Global Parameter Optimisation","title":"Prediction","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill k and estimate the future state at time k+1, k+2, dots,k+T.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k=NN(x_k) \np(x_k+1 x_k)=mathcalN(x_k+1 A_kx_k Q) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#Define the prediction function\nmultiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))\nsumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)\n\nfunction runForward(A,B,Q,R,mh_old,Vh_old)\n mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)\n mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)\nend\n\nfunction g_predict(mh_old,Vh_old,Q)\n neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)\n # Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])\n As = As[1]\n return runForward(As,B,Q,R,mh_old,Vh_old), As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"g_predict (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"After k=75, the observations are not available, and we predict the future state from k=76 to the end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"tt = 75\nmh = mean(x_est[tt])\nVh = cov(x_est[tt])\nmo_list, Vo_list, A_list = [], [], [] \ninv_Q = inv(Q)\nfor t=1:100-tt\n (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)\n push!(mo_list, mo)\n push!(Vo_list, Vh)\n push!(A_list, A_t)\n global mh = mo\n global Vh = Vo\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Prediction visualization\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\nfor i=1:tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\nfor i=tt+1:100\n ii=i-tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]\nend\np1 = plot(rx,label=\"Ground truth rx\")\np1 = plot!(rx_est_m,label=\"Inffered state rx\",ribbon=rx_est_var)\np1 = scatter!(first.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Ground truth ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index][1:tt], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Ground truth rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#examples-autoregressive-models","page":"Autoregressive Models","title":"Autoregressive Models","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\np(gamma) = mathrmGamma(gammaa b)\np(mathbftheta) = mathcalN(mathbfthetamathbfmu Sigma)\np(x_tmathbfx_t-1t-k) = mathcalN(x_tmathbftheta^Tmathbfx_t-1t-k gamma^-1)\np(y_tx_t) = mathcalN(y_tx_t tau^-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where x_t is a current state of our system, mathbfx_t-1t-k is a sequence of k previous states, k is an order of autoregression process, mathbftheta is a vector of transition coefficients, gamma is a precision of state transition process, y_k is a noisy observation of x_k with precision tau.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's generate some synthetic dataset, we use a predefined sets of coeffcients for k = 1, 3 and 5 respectively:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The following coefficients correspond to stable poles\ncoefs_ar_1 = [-0.27002517200218096]\ncoefs_ar_2 = [0.4511170798064709, -0.05740081602446657]\ncoefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"function generate_ar_data(rng, n, θ, γ, τ)\n order = length(θ)\n states = Vector{Vector{Float64}}(undef, n + 3order)\n observations = Vector{Float64}(undef, n + 3order)\n \n γ_std = sqrt(inv(γ))\n τ_std = sqrt(inv(τ))\n \n states[1] = randn(rng, order)\n \n for i in 2:(n + 3order)\n states[i] = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])\n observations[i] = rand(rng, Normal(states[i][1], τ_std))\n end\n \n return states[1+3order:end], observations[1+3order:end]\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"generate_ar_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Seed for reproducibility\nseed = 123\nrng = MersenneTwister(seed)\n\n# Number of observations in synthetic dataset\nn = 500\n\n# AR process parameters\nreal_γ = 1.0\nreal_τ = 0.5\nreal_θ = coefs_ar_5\n\nstates, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's plot our synthetic dataset:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(first.(states), label = \"Hidden states\")\nscatter!(observations, label = \"Observations\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order k > 1 and for Univariate AR (reduces to simple State-Space-Model) with order k = 1.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function lar_model(T::Type, n, order, c, τ)\n \n \n # We create a sequence of random variables for hidden states\n x = randomvar(n)\n # As well a sequence of observartions\n y = datavar(Float64, n)\n \n ct = constvar(c)\n # We assume observation noise to be known\n cτ = constvar(τ)\n \n γ = randomvar()\n θ = randomvar()\n x0 = randomvar()\n \n # Prior for first state\n if T === Multivariate\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n else\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ Normal(μ = 0.0, γ = 1.0)\n x0 ~ Normal(μ = 0.0, γ = 1.0)\n end\n \n x_prev = x0\n \n for i in 1:n\n \n x[i] ~ AR(x_prev, θ, γ) \n \n if T === Multivariate\n y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)\n else\n y[i] ~ Normal(μ = ct * x[i], γ = cτ)\n end\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@constraints function ar_constraints() \n q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_constraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@meta function ar_meta(artype, order, stype)\n AR() -> ARMeta(artype, order, stype)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_meta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"morder = 5\nmartype = Multivariate\nmc = ReactiveMP.ar_unit(martype, morder)\nmconstraints = ar_constraints()\nmmeta = ar_meta(martype, morder, ARsafe())\n\nmoptions = (limit_stack_depth = 100, )\n\nmmodel = lar_model(martype, length(observations), morder, mc, real_τ)\nmdata = (y = observations, )\nminitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))\nmreturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\n# First execution is slow due to Julia's initial compilation \n# Subsequent runs will be faster (benchmarks are below)\nmresult = infer(\n model = mmodel, \n data = mdata,\n constraints = mconstraints,\n meta = mmeta,\n options = moptions,\n initmarginals = minitmarginals,\n returnvars = mreturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@unpack x, γ, θ = mresult.posteriors","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Dict{Symbol, Vector} with 3 entries:\n :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)\n, Ga…\n :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…\n :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We will use different initial marginals depending on type of our AR process","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p1 = plot(first.(states), label=\"Hidden state\")\np1 = scatter!(p1, observations, label=\"Observations\")\np1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label=\"Inferred states\", legend = :bottomright)\n\np2 = plot(mean.(γ), ribbon = std.(γ), label = \"Inferred transition precision\", legend = :topright)\np2 = plot!([ real_γ ], seriestype = :hline, label = \"Real transition precision\")\n\np3 = plot(mresult.free_energy, label = \"Bethe Free Energy\")\n\nplot(p1, p2, p3, layout = @layout([ a; b c ]))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's also plot a subrange of our results:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"subrange = div(n,5):(div(n, 5) + div(n, 5))\n\nplot(subrange, first.(states)[subrange], label=\"Hidden state\")\nscatter!(subrange, observations[subrange], label=\"Observations\")\nplot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label=\"Inferred states\", legend = :bottomright)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"It is also interesting to see where our AR coefficients converge to:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"let\n pθ = plot()\n\n θms = mean.(θ)\n θvs = var.(θ)\n \n l = length(θms)\n\n edim(e) = (a) -> map(r -> r[e], a)\n\n for i in 1:length(first(θms))\n pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = \"Estimated θ[$i]\")\n end\n \n for i in 1:length(real_θ)\n pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = \"Real θ[$i]\")\n end\n \n plot(pθ, legend = :outertopright, size = (800, 300))\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"$(length(real_θ))-order AR inference Bethe Free Energy: \", last(mresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"5-order AR inference Bethe Free Energy: 1024.0775661298358","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can also run a 1-order AR inference on 5-order AR data:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"uorder = 1\nuartype = Univariate\nuc = ReactiveMP.ar_unit(uartype, uorder)\nuconstraints = ar_constraints()\numeta = ar_meta(uartype, uorder, ARsafe())\n\nuoptions = (limit_stack_depth = 100, )\n\numodel = lar_model(uartype, length(observations), uorder, uc, real_τ)\nudata = (y = observations, )\nuinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))\nureturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\nuresult = infer(\n model = umodel, \n data = udata,\n meta = umeta,\n constraints = uconstraints,\n initmarginals = uinitmarginals,\n returnvars = ureturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"1-order AR inference Bethe Free Energy: \", last(uresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1-order AR inference Bethe Free Energy: 1025.8792949319954","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"if uresult.free_energy[end] > mresult.free_energy[end]\n println(\"We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.\")\nelse\n error(\"AR-1 performs better than AR-5...\") \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can see that, according to final Bethe Free Energy value, in this exampl\ne 5-order AR process can describe data better than 1-order AR.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Autoregressive-Moving-Average-Model","page":"Autoregressive Models","title":"Autoregressive Moving Average Model","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\ne_t sim mathcalN(0 gamma^-1) quad\ntheta sim mathcalMN(mathbf0 mathbfI) quad\neta sim mathcalMN(mathbf0 mathbfI) \nmathbfh_0 sim mathcalMNleft(beginbmatrix\ne_-1 \ne_-2\nendbmatrix mathbfIright) \nmathbfh_t = mathbfSmathbfh_t-1 + mathbfc e_t-1 \nmathbfx_t = boldsymboltheta^topmathbfx_t-1 + boldsymboleta^topmathbfh_t + e_t \nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where shift matrix mathbfS is","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfS = beginpmatrix\n0 0 \n1 0 \nendpmatrix\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"and unit vector mathbfc: ","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfc=1 0\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"when MA order is 2","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this way, mathbfh_t containing errors e_t can be viewed as hidden state.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., boldsymboleta^topmathbfh_t, (2) induced by errors e_t that prevents analytical update of precision parameter gamma (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Load packages\nusing RxInfer, LinearAlgebra, CSV, DataFrames, Plots","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Define shift function\nfunction shift(dim)\n S = Matrix{Float64}(I, dim, dim)\n for i in dim:-1:2\n S[i,:] = S[i-1, :]\n end\n S[1, :] = zeros(dim)\n return S\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"shift (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)\n \n c = zeros(p); c[1] = 1.0; # AR\n b = zeros(q); b[1] = 1.0; # MA\n S = shift(q); # MA\n \n # initialize variables\n h = randomvar(n-1)\n e = randomvar(n)\n z = randomvar(n)\n \n x = datavar(Float64, n) where { allow_missing = true }\n \n # priors\n γ ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))\n η ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))\n θ ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))\n τ ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))\n \n # initial\n h_0 ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))\n z[1] ~ AR(h_0, η, τ)\n e[1] ~ Normal(mean = 0.0, precision = γ)\n\n x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]\n \n h_prev = h_0\n for t in 1:n-1\n \n e[t+1] ~ Normal(mean = 0.0, precision = γ)\n h[t] ~ S*h_prev + b*e[t]\n z[t+1] ~ AR(h[t], η, τ)\n x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]\n h_prev = h[t]\n end\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"x_df = CSV.read(\"../data/arma/aal_stock.csv\", DataFrame)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1259×7 DataFrame\n Row │ date open high low close volume Name\n │ Date Float64 Float64 Float64 Float64 Int64 String3\n──────┼───────────────────────────────────────────────────────────────────\n 1 │ 2013-02-08 15.07 15.12 14.63 14.75 8407500 AAL\n 2 │ 2013-02-11 14.89 15.01 14.26 14.46 8882000 AAL\n 3 │ 2013-02-12 14.45 14.51 14.1 14.27 8126000 AAL\n 4 │ 2013-02-13 14.3 14.94 14.25 14.66 10259500 AAL\n 5 │ 2013-02-14 14.94 14.96 13.16 13.99 31879900 AAL\n 6 │ 2013-02-15 13.93 14.61 13.93 14.5 15628000 AAL\n 7 │ 2013-02-19 14.33 14.56 14.08 14.26 11354400 AAL\n 8 │ 2013-02-20 14.17 14.26 13.15 13.33 14725200 AAL\n ⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮\n 1253 │ 2018-01-30 52.45 53.05 52.36 52.59 4741808 AAL\n 1254 │ 2018-01-31 53.08 54.71 53.0 54.32 5962937 AAL\n 1255 │ 2018-02-01 54.0 54.64 53.59 53.88 3623078 AAL\n 1256 │ 2018-02-02 53.49 53.99 52.03 52.1 5109361 AAL\n 1257 │ 2018-02-05 51.99 52.39 49.75 49.76 6878284 AAL\n 1258 │ 2018-02-06 49.32 51.5 48.79 51.18 6782480 AAL\n 1259 │ 2018-02-07 50.91 51.98 50.89 51.4 4845831 AAL\n 1244 rows omitted","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# we will use \"close\" column\nx_data = filter(!ismissing, x_df[:, 5]);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Plot data\nplot(x_data, xlabel=\"day\", ylabel=\"price\", label=false)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p_order = 10 # AR\nq_order = 4 # MA","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"4","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Training set\ntrain_size = 1000\nx_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]\nx_train = Float64.(x_data[p_order+1:end])[1:train_size];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Test set\nx_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]\nx_test = Float64.(x_data[p_order+1:end])[train_size+1:end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Inference","page":"Autoregressive Models","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Constraints are needed for performing VMP\narma_constraints = @constraints begin\n q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)\nend;","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# This cell defines prior knowledge for model parameters\nh_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nγ_prior = GammaShapeRate(1e4, 1.0)\nτ_prior = GammaShapeRate(1e2, 1.0)\nη_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nθ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Model's graph has structural loops, hence, it requires pre-initialisation\narma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);\narma_imessages = (h_0 = h_prior, h = h_prior);\narma_meta = ar_meta(Multivariate, q_order, ARsafe());","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"result = infer(\n model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), \n data = (x = x_train, ),\n initmarginals = arma_imarginals,\n initmessages = arma_imessages,\n constraints = arma_constraints,\n meta = arma_meta,\n iterations = 50,\n options = (limit_stack_depth = 400, ),\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = \"eₜ\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# extract posteriors\nh_posterior = result.posteriors[:h][end][end]\nγ_posterior = result.posteriors[:γ][end]\nτ_posterior = result.posteriors[:τ][end]\nη_posterior = result.posteriors[:η][end]\nθ_posterior = result.posteriors[:θ][end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Prediction","page":"Autoregressive Models","title":"Prediction","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Here we are going to use our inference results in order to predict the dataset itself","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The prediction function is aimed at approximating the predictive posterior distribution\n# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)\nfunction prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)\n h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))\n ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))\n c = zeros(p); c[1] = 1.0\n b = zeros(q); b[1] = 1.0\n ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)\n θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))\n ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)\n e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))\n ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out) \n @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out) \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"prediction (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"predictions = []\nfor x_prev in x_prev_test\n push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))\n # after every new prediction we can actually \"retrain\" the model to use the power of Bayesian approach\n # we will skip this part at this notebook\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(x_test, label=\"test data\", legend=:topleft)\nplot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label=\"predicted\", xlabel=\"day\", ylabel=\"price\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/#examples-how-to-train-your-hidden-markov-model","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"","category":"section"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate()\n;","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time t, let's call the estimate of the Roomba's position s_t.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call A.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"At time t, we will call our observations x_t and encode the mapping from the Roomba's position to the observations in a matrix we call B. B also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"beginaligned\n s_t sim mathcalCat(A s_t-1)\n x_t sim mathcalCat(B s_t)\nendaligned","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices A and B so we can use them to track the whereabouts of our little cleaning agent.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"To generate our observation data, we'll follow these steps:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.\nDetermine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.\nDetermine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.\nRepeat steps 2-3 for as many samples as we want.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"The following code implements this process and generates our observation data:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"\"\"\"\n rand_vec(rng, distribution::Categorical)\n\nThis function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.\n\"\"\"\nfunction rand_vec(rng, distribution::Categorical) \n k = ncategories(distribution)\n s = zeros(k)\n drawn_category = rand(rng, distribution)\n s[drawn_category] = 1.0\n return s\nend\n\nfunction generate_data(n_samples; seed = 42)\n \n rng = MersenneTwister(seed)\n \n # Transition probabilities \n state_transition_matrix = [0.9 0.0 0.1;\n 0.0 0.9 0.1; \n 0.05 0.05 0.9] \n # Observation noise\n observation_distribution_matrix = [0.9 0.05 0.05;\n 0.05 0.9 0.05;\n 0.05 0.05 0.9] \n # Initial state\n s_initial = [1.0, 0.0, 0.0] \n \n states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states\n observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations\n \n s_prev = s_initial\n \n for t = 1:n_samples\n s_probvec = state_transition_matrix * s_prev\n states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))\n obs_probvec = observation_distribution_matrix * states[t]\n observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))\n s_prev = states[t]\n end\n \n return observations, states\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Test data\nN = 100\nx_data, s_data = generate_data(N);\n\nscatter(argmax.(s_data), leg=false, xlabel=\"Time\",yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the A and B matrices we can use MatrixDirichlet priors. For the A-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on A with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on B. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Model specification\n@model function hidden_markov_model(n)\n \n A ~ MatrixDirichlet(ones(3,3))\n B ~ MatrixDirichlet([ 10.0 1.0 1.0; \n 1.0 10.0 1.0; \n 1.0 1.0 10.0 ])\n \n s_0 ~ Categorical(fill(1.0 / 3.0, 3))\n \n s = randomvar(n)\n x = datavar(Vector{Float64}, n)\n \n s_prev = s_0\n \n for t in 1:n\n s[t] ~ Transition(s_prev, A) \n x[t] ~ Transition(s[t], B)\n s_prev = s[t]\n end\n \nend\n\n# Constraints specification\n@constraints function hidden_markov_model_constraints()\n q(s_0, s, A, B) = q(s_0, s)q(A)q(B)\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"hidden_markov_model_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"imodel = hidden_markov_model(N)\nidata = (x = x_data,)\n\nimarginals = (\n A = vague(MatrixDirichlet, 3, 3), \n B = vague(MatrixDirichlet, 3, 3), \n s = vague(Categorical, 3)\n)\n\nireturnvars = (\n A = KeepLast(),\n B = KeepLast(),\n s = KeepLast()\n)\n\nresult = infer(\n model = imodel, \n data = idata,\n constraints = hidden_markov_model_constraints(),\n initmarginals = imarginals, \n returnvars = ireturnvars, \n iterations = 20, \n free_energy = true\n);","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over A) and about the uncertainty in the roombas observations (A good posterior over B). Let's see if it worked","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for A:\")\nmean(result.posteriors[:A])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for A:\n3×3 Matrix{Float64}:\n 0.871955 0.0290008 0.0572283\n 0.0349989 0.817591 0.135675\n 0.0930457 0.153408 0.807097","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for B:\")\nmean(result.posteriors[:B])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for B:\n3×3 Matrix{Float64}:\n 0.949636 0.0974741 0.0518997\n 0.0244903 0.833632 0.0277884\n 0.0258734 0.0688939 0.920312","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"p1 = scatter(argmax.(s_data), \n title=\"Inference results\", \n label = \"Real\", \n ms = 6, \n legend=:right,\n xlabel=\"Time\" ,\n yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]),\n size=(900,550)\n )\n\np1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),\n label = \"Inferred\",\n ms = 3\n )\n\np2 = plot(result.free_energy, \n label=\"Free energy\",\n xlabel=\"Iteration Number\"\n )\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#examples-rts-vs-bifm-smoothing","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"___Credits to Martin de Quincey___","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762\nH. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"We perform Kalman smoothing in the linear state space model, represented by:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n Z_k+1 = A Z_k + B U_k \n Y_k = C Z_k + W_k\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"with observations Y_k, latent states Z_k and inputs U_k. W_k is the observation noise. A in mathrmR^n times n, B in mathrmR^n times m and C in mathrmR^d times n are the transition matrices in the model. Here n, m and d denote the dimensionality of the latent, input and output dimension, respectively.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"The corresponding probabilistic model can be represented as ","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n p(y z u)\n = p(z_0) prod_k=1^N p(y_k mid z_k) p(z_kmid z_k-1 u_k-1) p(u_k-1) \n = mathcalN(z_0 mid mu_z_0 Sigma_z_0) left( prod_k=1^N mathcalN(y_k mid C z_k Sigma_W) delta(z_k - (Az_k-1 + Bu_k-1)) mathcalN(u_k-1 mid mu_i_k-1 Sigma_u_k-1) right)\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Import-packages","page":"RTS vs BIFM Smoothing","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Data-generation","page":"RTS vs BIFM Smoothing","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)\n \n # define noise levels\n input_noise = 500.0\n output_noise = 50.0\n\n # create random generator for reproducibility\n rng = MersenneTwister(seed)\n\n # generate matrices, input statistics and noise matrices\n A = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat)) # size (dim_lat x dim_lat)\n B = rand(dim_lat, dim_in) # size (dim_lat x dim_in)\n C = rand(dim_out, dim_lat) # size (dim_out x dim_lat)\n μu = rand(dim_in) .* collect(1:dim_in) # size (dim_in x 1)\n Σu = input_noise .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in)))) # size (dim_in x dim_in)\n Σy = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out)))) # size (dim_out x dim_out)\n Wu = inv(Σu)\n Wy = inv(Σy)\n \n # return parameters\n return A, B, C, μu, Σu, Σy, Wu, Wy\n\nend;","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)\n \n # create random data generator\n rng = StableRNG(seed)\n \n # preallocate space for variables\n z = Vector{Vector{Float64}}(undef, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n u = rand(rng, MvNormal(μu, Σu), nr_samples)'\n \n # set initial value of latent states\n z_prev = zeros(size(A,1))\n \n # generate data\n for i in 1:nr_samples\n\n # generate new latent state\n z[i] = A * z_prev + B * u[i,:]\n\n # generate new observation\n y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))\n \n # generate new observation\n z_prev .= z[i]\n \n end\n \n # return generated data\n return z, y, u\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# specify settings\nnr_samples = 200\ndim_out = 3\ndim_in = 3\ndim_lat = 25\n\n# generate parameters\nA, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);\n \n# generate data\ndata_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);\n\n# visualise data\np = Plots.plot(xlabel = \"sample\", ylabel = \"observations\")\n# plot each dimension independently\nfor i in 1:dim_out\n Plots.scatter!(p, getindex.(data_y, i), label = \"y_$i\", alpha = 0.5, ms = 2)\nend\np","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Model-specification","page":"RTS vs BIFM Smoothing","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n \n # fetch dimensionality\n dim_lat = size(A, 1)\n dim_out = size(C, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # hidden states (random variable)\n u = randomvar(nr_samples) # inputs (random variable)\n y = datavar(Vector{Float64}, nr_samples) # outputs (observed variables)\n \n # set initial hidden state\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n \n # update last/previous hidden state\n z_prev = z_prior\n\n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n \n # specify updated hidden state\n z[i] ~ A * z_prev + B * u[i]\n \n # specify observation\n y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n\n # fetch dimensionality\n dim_lat = size(A, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # latent states\n yt = randomvar(nr_samples) # latent observations\n y = datavar(Vector{Float64}, nr_samples) # actual observations\n u = randomvar(nr_samples) # inputs\n \n # set priors\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n z_tmp ~ BIFMHelper(z_prior) where { q = MeanField() }\n \n # update last/previous hidden state\n z_prev = z_tmp\n \n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n\n # specify observation\n yt[i] ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }\n y[i] ~ MvNormalMeanPrecision(yt[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \n # set final value\n z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Probabilistic-inference","page":"RTS vs BIFM Smoothing","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_RTS(data_y, A, B, C, μu, Wu, Wy)\n \n # In this task the inference is unstable and can diverge\n meta = @meta begin \n *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)\n end\n \n result = infer(\n model = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast()),\n meta = meta\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_RTS (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)\n result = infer(\n model = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast())\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_BIFM (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Experiments-for-200-observations","page":"RTS vs BIFM Smoothing","title":"Experiments for 200 observations","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)\nz_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\n\nmz_RTS = mean.(z_RTS)\nmz_BIFM = mean.(z_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:5\n Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\n\nrdata_u = collect(eachrow(data_u))\nmu_RTS = mean.(u_RTS)\nmu_BIFM = mean.(u_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:1\n Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Benchmark","page":"RTS vs BIFM Smoothing","title":"Benchmark","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation\n# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`\nrun_benchmark = false\n\nif run_benchmark\n trials_range = 30\n trials_n = 500\n trials_RTS = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n\n\n @showprogress for k = 1 : trials_range\n\n # generate parameters\n local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);\n \n # generate data|\n local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);\n\n # run inference\n trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n\n end\n\n m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9\n q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9\n m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9\n q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;\n\n p = Plots.plot(ylabel = \"duration [sec]\", xlabel = \"latent state dimension\", title = \"Benchmark\", yscale = :log)\n p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = \"blue\", label = \"mean (RTS)\")\n p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = \"orange\", label = \"mean (BIFM)\")\n Plots.savefig(p, \"../pics/rts_bifm_benchmark.png\")\n p\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"manuals/meta-specification/#user-guide-meta-specification","page":"Meta specification","title":"Meta Specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.","category":"page"},{"location":"manuals/meta-specification/#General-syntax","page":"Meta specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts either regular Julia function or a single begin ... end block:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function MyModelMeta(arg1, arg2)\n Node(y,x) -> MetaObject(arg1, arg2)\nend\n\nmy_meta = @meta begin \n Node(y,x) -> MetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order 5 can be specified as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function ARmodel_meta(num_order)\n AR() -> ARMeta(Univariate, num_order, ARsafe())\nend\n\nmy_meta = ARmodel_meta(5)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"num_order = 5\n\nmy_meta = @meta begin \n AR() -> ARMeta(Multivariate, num_order, ARsafe())\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Both syntax variations provide the same meta specification and there is no preference given to one over the other. ","category":"page"},{"location":"manuals/meta-specification/#Options-specification","page":"Meta specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta [ warn = false ] begin \n ...\nend\n\n@meta [ warn = false ] function MyModelMeta()\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"List of available options:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/meta specification","category":"page"},{"location":"manuals/meta-specification/#Meta-specification","page":"Meta specification","title":"Meta specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"First, let's start with an example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"You can have a list of as many meta specification entries as possible for different nodes:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))\n AR() -> ARMeta(Multivariate, 5, ARsafe())\n MyCustomNode() -> MyCustomMetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model(arguments...)\n ...\nend\n\nmy_meta = @meta begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); meta = my_meta)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"inferred_result = infer(\n model = my_model(arguments...),\n meta = my_meta,\n ...\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model()\n ...\n\n y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }\n\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.","category":"page"},{"location":"manuals/meta-specification/#Create-your-own-meta","page":"Meta specification","title":"Create your own meta","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for your custom node\nstruct MyCustomMeta\n arg1 \n arg2 \nend\n\n# apply the new meta structure to your node\n@meta function model_meta(arg1, arg2)\n MyCustomNode() -> MyCustomMeta(arg1,arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"or create different meta structures for a node, e.g. AR node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for the AR node\nstruct MyARMeta\n arg1\n arg2\nend\n\n# apply the new meta structure to the AR node\n@meta function model_meta(arg1, arg2)\n AR() -> MyARMeta(arg1, arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.","category":"page"},{"location":"manuals/meta-specification/#Example","page":"Meta specification","title":"Example","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"beginaligned\n x sim mathrmNormal(25 05)\n y sim mathrmNormal(2*x 20)\nendaligned","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"where y is observable data and x is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"using RxInfer\n\n#create data\ny_data = 4.0 \n\n#make model\n@model function gaussian_model()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\n#do inference\ninference_result = infer(\n model = gaussian_model(),\n data = (y = y_data,)\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean m clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#create your new meta structure for Normal node\nstruct MetaConstrainedMeanNormal{T}\n lower_limit :: T\n upper_limit :: T\nend\n\n#define rules with meta for the Normal node\n@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))\nend\n\n@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#make model\n@model function gaussian_model_with_meta()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\ncustom_meta = @meta begin\n NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)\nend\n\n#do inference\ninference_result = inference(\n model = gaussian_model(),\n data = (y = y_data,),\n meta = custom_meta\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution","page":"Overview","title":"Inference execution","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"Belief Propagation\nVariational Message Passing","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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.","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-static","page":"Overview","title":"Automatic inference specification on static datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-realtime","page":"Overview","title":"Automatic inference specification on real-time datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-manual-specification","page":"Overview","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#examples-chance-constrained-active-inference","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, \"Chance-constrained active inference\") and discussion with John Boik.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Plots, Distributions, StatsFuns, RxInfer","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Chance-Constraint-Node-Definition","page":"Chance-Constrained Active Inference","title":"Chance-Constraint Node Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not \"overflow\" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"struct ChanceConstraint end \n\n# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol\n@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Function to compute normalizing constant and central moments of a truncated Gaussian distribution\nfunction truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)\n V = clamp(V, tiny, huge)\n StdG = Distributions.Normal(m, sqrt(V))\n TrG = Distributions.Truncated(StdG, a, b)\n \n Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a) # safe mass for standard Gaussian\n \n if Z < tiny\n # Invalid region; return undefined mean and variance of truncated distribution\n Z = 0.0\n m_tr = 0.0\n V_tr = 0.0\n else\n m_tr = Distributions.mean(TrG)\n V_tr = Distributions.var(TrG)\n end\n \n return (Z, m_tr, V_tr)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@rule ChanceConstraint(:out, Marginalisation) (\n m_out::UnivariateNormalDistributionsFamily, # Require inbound message\n q_lo::PointMass, \n q_hi::PointMass, \n q_epsilon::PointMass, \n q_atol::PointMass) = begin \n\n # Extract parameters\n lo = mean(q_lo)\n hi = mean(q_hi)\n epsilon = mean(q_epsilon)\n atol = mean(q_atol)\n \n (m_bw, V_bw) = mean_var(m_out)\n (xi_bw, W_bw) = (m_bw, 1. /V_bw) # check division by zero\n (m_tilde, V_tilde) = (m_bw, V_bw)\n \n # Compute statistics (and normalizing constant) of q in safe region G\n # Phi_G is called the \"safe mass\" \n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)\n\n xi_fw = xi_bw\n W_fw = W_bw\n if epsilon <= 1.0 - Phi_G # If constraint is active\n # Initialize statistics of uncorrected belief\n m_tilde = m_bw\n V_tilde = V_bw\n for i = 1:100 # Iterate at most this many times\n (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G\n (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G\n\n # Compute moments of non-G region as a mixture of left and right truncations\n Phi_nG = Phi_lG + Phi_rG\n m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG\n V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2\n\n # Compute moments of corrected belief as a mixture of G and non-G regions\n m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG\n V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2\n # Re-compute statistics (and normalizing constant) of corrected belief\n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)\n if (1.0 - Phi_G) < (1.0 + atol)*epsilon\n break # Break the loop if the belief is sufficiently corrected\n end\n end\n \n # Convert moments of corrected belief to canonical form\n W_tilde = inv(V_tilde)\n xi_tilde = W_tilde * m_tilde\n\n # Compute canonical parameters of forward message\n xi_fw = xi_tilde - xi_bw\n W_fw = W_tilde - W_bw\n end\n\n return NormalWeightedMeanPrecision(xi_fw, W_fw)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Definition-of-the-Environment","page":"Chance-Constrained Active Inference","title":"Definition of the Environment","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile\n\nfunction initializeWorld()\n x_0 = 0.0 # Initial elevation\n \n x_t_last = x_0\n function execute(t::Int64, a_t::Float64)\n x_t = x_t_last + a_t + wind(t) # Update elevation\n \n x_t_last = x_t # Reset state\n \n return x_t\n end\n\n x_t = x_0 # Predefine outcome variable\n observe() = x_t # State is fully observed\n\n return (execute, observe)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Generative-Model-for-Regulator","page":"Chance-Constrained Active Inference","title":"Generative Model for Regulator","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@model function regulator_model(; T, lo, hi, epsilon, atol)\n # Fully observed state\n x_t = datavar(Float64)\n\n # Control prior statistics\n m_u = datavar(Float64, T)\n v_u = datavar(Float64, T) \n \n # Random variables\n u = randomvar(T) # Control\n x = randomvar(T) # Elevation\n \n # Loop over horizon\n x_k_last = x_t\n for k = 1:T\n u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior\n x[k] ~ x_k_last + u[k] # Transition model\n x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state\n pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency\n x_k_last = x[k]\n end\n \n return (u, x)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Reactive-Agent-Definition","page":"Chance-Constrained Active Inference","title":"Reactive Agent Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"function initializeAgent()\n # Set control prior statistics\n m_u = zeros(T)\n v_u = lambda^(-1)*ones(T)\n \n function compute(x_t::Float64)\n model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)\n data_t = (m_u = m_u, v_u = v_u, x_t = x_t)\n \n result = infer(\n model = model_t, \n data = data_t,\n iterations = n_its)\n\n # Extract policy from inference results\n pol = mode.(result.posteriors[:u][end])\n\n return pol\n end\n\n pol = zeros(T) # Predefine policy variable\n act() = pol[1]\n\n return (compute, act)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Action-Perception-Cycle","page":"Chance-Constrained Active Inference","title":"Action-Perception Cycle","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Simulation parameters\nN = 160 # Total simulation time\nT = 1 # Lookahead time horizon\nlambda = 1.0 # Control prior precision\nlo = 1.0 # Chance region lower bound\nhi = Inf # Chance region upper bound\nepsilon = 0.01 # Allowed chance violation\natol = 0.01 # Convergence tolerance for chance constraints\nn_its = 10; # Number of inference iterations","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(execute, observe) = initializeWorld() # Let there be a world\n(compute, act) = initializeAgent() # Let there be an agent\n\na = Vector{Float64}(undef, N) # Actions\nx = Vector{Float64}(undef, N) # States\nfor t = 1:N\n a[t] = act()\n execute(t, a[t])\n x[t] = observe()\n compute(x[t])\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Results","page":"Chance-Constrained Active Inference","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Results show that the agent does not allow the wind to push it all the way to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"p1 = plot(1:N, wind.(1:N), color=\"blue\", label=\"Wind\", ylabel=\"Velocity\", lw=2)\nplot!(p1, 1:N, a, color=\"red\", label=\"Control\", lw=2)\np2 = plot(1:N, x, color=\"black\", lw=2, label=\"Agent\", ylabel=\"Elevation\")\nplot(p1, p2, layout=(2,1))","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#examples-gamma-mixture-model","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Load-packages","page":"Gamma Mixture Model","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"using RxInfer, Random, StatsPlots","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# create custom structure for model parameters for simplicity\nstruct GammaMixtureModelParameters\n nmixtures # number of mixtures\n priors_as # tuple of priors for variable a\n priors_bs # tuple of priors for variable b\n prior_s # prior of variable s\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Model-specification","page":"Gamma Mixture Model","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)\n\n # fetch information from struct\n nmixtures = parameters.nmixtures\n priors_as = parameters.priors_as\n priors_bs = parameters.priors_bs\n prior_s = parameters.prior_s\n\n # set prior on global selection variable\n s ~ Dirichlet(probvec(prior_s))\n\n # allocate vectors of random variables\n as = randomvar(nmixtures)\n bs = randomvar(nmixtures)\n\n # set priors on variables of mixtures\n for i in 1:nmixtures\n as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))\n bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))\n end\n\n # introduce random variables for local selection variables and data\n z = randomvar(nobservations)\n y = datavar(Float64, nobservations)\n\n # convert vector to tuples for proper functioning of GammaMixture node\n tas = tuple(as...)\n tbs = tuple(bs...)\n\n # specify local selection variable and data generating process\n for i in 1:nobservations\n z[i] ~ Categorical(s)\n y[i] ~ GammaMixture(z[i], tas, tbs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"constraints = @constraints begin \n\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n\n q(as) = q(as[begin])..q(as[end])\n q(bs) = q(bs[begin])..q(bs[end])\n \n q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Constraints:\n marginals form:\n q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n q(as) = q(as[(begin)..(end)])\n q(bs) = q(bs[(begin)..(end)])\nOptions:\n warn = true","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify seed and number of data points\nrng = MersenneTwister(43)\nn_samples = 2500\n\n# specify parameters of mixture model that generates the data\n# Note that mixture components have exactly the same means\nmixtures = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]\nnmixtures = length(mixtures)\nmixing = rand(rng, nmixtures)\nmixing = mixing ./ sum(mixing)\nmixture = MixtureModel(mixtures, mixing)\n\n# generate data set\ndataset = rand(rng, mixture, n_samples);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify priors of probabilistic model\n# NOTE: As the means of the mixtures \"collide\", we specify informative prior for selector variable\nnmixtures = 2\ngpriors = GammaMixtureModelParameters(\n nmixtures, # number of mixtures\n [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ], # priors on variables a\n [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ], # priors on variables b\n Dirichlet(1e3*mixing) # prior on variable s\n)\n\ngmodel = gamma_mixture_model(length(dataset), gpriors)\ngdata = (y = dataset, )\nginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))\ngreturnvars = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())\n\ngoptions = (\n \n default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently\n)\n\ngresult = infer(\n model = gmodel, \n data = gdata,\n constraints = constraints,\n options = (limit_stack_depth = 100,),\n initmarginals = ginitmarginals,\n returnvars = greturnvars,\n free_energy = true,\n iterations = 250, \n showprogress = true\n);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# extract inferred parameters\n_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])\n_dists = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))\n_mixing = mean(gresult.posteriors[:s])\n\n# create model from inferred parameters\n_mixture = MixtureModel(_dists, _mixing);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# report on outcome of inference\nprintln(\"Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))\")\nprintln(\"Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))\")\nprintln(\"========\")\nprintln(\"Generated mixing: $(mixing)\")\nprintln(\"Inferred mixing: $(_mixing)\")","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Generated means: 0.3333333333333333 and 0.33333333333333337\nInferred means: 0.33822470398804994 and 0.33305534672666653\n========\nGenerated mixing: [0.18923488676601088, 0.8107651132339891]\nInferred mixing: [0.11395888467453213, 0.8860411153254679]","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# plot results\np1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np1 = plot!(mixture, label=false, title=\"Generated mixtures\", linewidth=3.0)\n\np2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np2 = plot!(_mixture, label=false, title=\"Inferred mixtures\", linewidth=3.0)\n\n# evaluate the convergence of the algorithm by monitoring the BFE\np3 = plot(gresult.free_energy, label=false, xlabel=\"iterations\", title=\"Bethe FE\")\n\nplot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#examples-gaussian-mixture","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Load-packages","page":"Gaussian Mixture","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Univariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Univariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Consider the data set of length N observed below.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_univariate_data(nr_samples; rng = MersenneTwister(123))\n\n # data generating parameters\n class = [1/3, 2/3]\n mean1, mean2 = -10, 10\n precision = 1.777\n\n # generate data\n z = rand(rng, Categorical(class), nr_samples)\n y = zeros(nr_samples)\n for k in 1:nr_samples\n y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_univariate = generate_univariate_data(100)\nhistogram(data_univariate, bins=50, label=\"data\", normed=true)\nxlims!(minimum(data_univariate), maximum(data_univariate))\nylims!(0, Inf)\nylabel!(\"relative occurrence [%]\")\nxlabel!(\"y\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m w z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(w_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmBeta(s mid alpha_s beta_s) \n p(m_k) = mathcalN(m_k mid mu_k sigma_k^2) p(w_k) = Gamma(w_k mid alpha_k beta_k) \n p(z_n mid s) = mathrmBer(z_n mid s) \n p(y_n mid m w z_n) = prod_k=1^K mathcalNleft(y_n mid m_k w_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions w = w_1 w_2 ldots w_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Here we implement the following model with uninformative values for the hyperparameters as","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function univariate_gaussian_mixture_model(nr_samples)\n \n s ~ Beta(1.0, 1.0)\n \n m1 ~ Normal(mean = -2.0, var = 1e3)\n w1 ~ Gamma(shape = 0.01, rate = 0.01)\n \n m2 ~ Normal(mean = 2.0, var = 1e3)\n w2 ~ Gamma(shape = 0.01, rate = 0.01)\n \n z = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n \n for n in 1:nr_samples\n z[n] ~ Bernoulli(s)\n y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m w mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m w mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(w_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmBeta(s mid hatalpha_s hatbeta_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatsigma^2_k) \n q(w_k) = Gamma (w_k mid hatalpha_k hatbeta_k) \n q(z_n) = mathrmBer(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"results_univariate = infer(\n model = univariate_gaussian_mixture_model(length(data_univariate)), \n constraints = MeanField(),\n data = (y = data_univariate,), \n initmarginals = (\n s = vague(Beta), \n m1 = NormalMeanVariance(-2.0, 1e3), \n m2 = NormalMeanVariance(2.0, 1e3), \n w1 = vague(GammaShapeRate), \n w2 = vague(GammaShapeRate)\n ), \n iterations = 10, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m2, m1, s, w2, w1, z)\n Free Energy: | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.\n277, 135.277, 135.277, 135.277, 135.277]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen as a function of the iterations","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L\"posterior $m_1$\")\nmp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L\"posterior $m_2$\")\nmp = plot!(mp, [ -10 ], seriestype = :hline, label = L\"true $m_1$\")\nmp = plot!(mp, [ 10 ], seriestype = :hline, label = L\"true $m_2$\")\n\nwp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L\"posterior $w_1$\", legend = :bottomright, ylim = (-1, 3))\nwp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L\"posterior $w_2$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_1$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_2$\")\n\nswp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L\"posterior $s$\")\nswp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L\"true $s$\")\n\nfep = plot(results_univariate.free_energy, label = \"Free Energy\", legend = :topright)\n\nplot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))\nxlabel!(\"iteration\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Multivariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Multivariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The above example can also be extended to the multivariate case. Consider the data set below","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))\n\n L = 50.0\n nr_mixtures = 6\n\n probvec = normalize!(ones(nr_mixtures), 1)\n\n switch = Categorical(probvec)\n\n gaussians = map(1:nr_mixtures) do index\n angle = 2π / nr_mixtures * (index - 1)\n basis_v = L * [ 1.0, 0.0 ]\n R = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]\n mean = R * basis_v \n covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))\n return MvNormal(mean, covariance)\n end\n\n z = rand(rng, switch, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n\n for n in 1:nr_samples\n y[n] = rand(rng, gaussians[z[n]])\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_multivariate = generate_multivariate_data(500)\n\nsdim(n) = (a) -> map(d -> d[n], a) # helper function\nscatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)\nxlabel!(L\"y_1\")\nylabel!(L\"y_2\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification-2","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m W z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(W_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmDir(s mid alpha_s) \n p(m_k) = mathcalN(m_k mid mu_k Sigma_k) p(W_k) = mathcalW(W_k mid V_k nu_k) \n p(z_n mid s) = mathrmCat(z_n mid s) \n p(y_n mid m W z_n) = prod_k=1^K mathcalNleft(y_n mid m_k W_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions W = W_1 W_2 ldots W_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)\n \n z = randomvar(nr_samples)\n m = randomvar(nr_mixtures)\n w = randomvar(nr_mixtures)\n y = datavar(Vector{Float64}, nr_samples)\n \n for k in 1:nr_mixtures \n m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])\n w[k] ~ Wishart(3, 1e2*diagm(ones(2)))\n end\n \n s ~ Dirichlet(ones(nr_mixtures))\n \n means = tuple(m...)\n precs = tuple(w...)\n \n for n in 1:nr_samples\n z[n] ~ Categorical(s) \n y[n] ~ NormalMixture(z[n], means, precs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference-2","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m W mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m W mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(W_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmDir(s mid hatalpha_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatSigma_k) \n q(w_k) = mathcalW(W_k mid hatV_k hatnu_k) \n q(z_n) = mathrmCat(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"rng = MersenneTwister(121)\nm = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]\nresults_multivariate = infer(\n model = multivariate_gaussian_mixture_model(\n 6, \n length(data_multivariate), \n m,\n [diagm(1e2 * ones(2)) for k in 1:6]\n ), \n data = (y = data_multivariate,), \n constraints = MeanField(),\n initmarginals = (\n s = vague(Dirichlet, 6), \n m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], \n w = Wishart(3, diagm(1e2 * ones(2)))\n ), \n iterations = 50, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m, w, s, z)\n Free Energy: | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49 … 3894.49, 3894.49, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results-2","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title=\"Data\", xlims=(-75, 75), ylims=(-75, 75))\np_result = plot(xlims = (-75, 75), ylims = (-75, 75), title=\"Inference result\", legend=false, colorbar = false)\nfor (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])\n gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))\n global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title=\"Inference result\", legend=false, levels = 7, colorbar = false)\nend\np_fe = plot(results_multivariate.free_energy, label = \"Free Energy\")\n\nplot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#examples-kalman-filtering-and-smoothing","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We then solve an identification problem which does not have an analytical solution.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Utimately, we show how RxInfer.jl can deal with missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Gaussian-Linear-Dynamical-System","page":"Kalman filtering and smoothing","title":"Gaussian Linear Dynamical System","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"LGSSM can be described with the following equations:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n p(x_ix_i - 1) = mathcalN(x_iA * x_i - 1 mathcalP)\n p(y_ix_i) = mathcalN(y_iB * x_i mathcalQ)\nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"where x_i are hidden states, y_i are noisy observations, A, B are state transition and observational matrices, mathcalP and mathcalQ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(rng, A, B, Q, P)\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(B * x[i], P))\n x_prev = x[i]\n end\n \n return x, y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Seed for reproducibility\nseed = 1234\n\nrng = MersenneTwister(1234)\n\n# We will model 2-dimensional observations with rotation matrix `A`\n# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`\n# are known and fixed for all time-steps\nθ = π / 35\nA = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\nB = diageye(2)\nQ = diageye(2)\nP = 25.0 .* diageye(2)\n\n# Number of observations\nn = 300;","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x, y = generate_data(rng, A, B, Q, P);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\npx = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To create a model we use GraphPPL package and @model macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rotate_ssm(n, x0, A, B, Q, P)\n \n # We create constvar references for better efficiency\n cA = constvar(A)\n cB = constvar(B)\n cQ = constvar(Q)\n cP = constvar(P)\n \n # `x` is a sequence of hidden states\n x = randomvar(n)\n # `y` is a sequence of \"clamped\" observations\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n x_prev = x_prior\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)\n y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)\n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference we also specify prior for out first hidden state:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. \n# infer(..., options = (limit_stack_depth = 500, ))`\nresult = infer(\n model = rotate_ssm(length(y), x0, A, B, Q, P), \n data = (y = y,),\n free_energy = true\n);\n\nxmarginals = result.posteriors[:x]\nlogevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\n\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :teal)\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :violet)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"logevidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"1-element Vector{Float64}:\n -1882.2434870099778","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We may be also interested in performance of our resulting Belief Propagation algorithm:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@benchmark infer(\n model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), \n data = (y = $y,)\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"BenchmarkTools.Trial: 140 samples with 1 evaluation.\n Range (min … max): 28.850 ms … 94.284 ms ┊ GC (min … max): 0.00% … 32.97\n%\n Time (median): 33.721 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 35.765 ms ± 6.834 ms ┊ GC (mean ± σ): 5.28% ± 9.06\n%\n\n ▁▁▁▅▆█▅ ▁ \n ▄▃▃▁▃▇▇█████████▇▄▃▅▁▁▁▁▁▁▁▁▄▁▃▃▄▃▆▆▁▃▁▄▁▄▁▄▁▁▁▃▁▁▁▁▁▁▁▃▁▃▃ ▃\n 28.8 ms Histogram: frequency by time 52.3 ms <\n\n Memory estimate: 9.73 MiB, allocs estimate: 226250.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#System-Identification-Problem","page":"Kalman filtering and smoothing","title":"System Identification Problem","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Distributions, StableRNGs, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)\n\n rng = StableRNG(seed)\n\n real_x = Vector{Float64}(undef, n)\n real_w = Vector{Float64}(undef, n)\n real_y = Vector{Float64}(undef, n)\n\n for i in 1:n\n real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))\n real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))\n real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))\n\n x_i_min = real_x[i]\n w_i_min = real_w[i]\n end\n \n return real_x, real_w, real_y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-1:-y-x-w","page":"Kalman filtering and smoothing","title":"Combination 1: y = x + w","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 250\nreal_x, real_w, real_y = generate_data(+, n);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, real_x, label = \"x\")\npl = plot!(pl, real_w, label = \"w\")\n\npr = plot(title = \"Combined y = x + w\")\npr = scatter!(pr, real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x = randomvar(n)\n w = randomvar(n)\n s = randomvar(n)\n y = datavar(Float64, n)\n \n x_i_min = x0\n w_i_min = w0\n \n for i in 1:n\n x[i] ~ Normal(mean = x_i_min, precision = τ_x)\n w[i] ~ Normal(mean = w_i_min, precision = τ_w)\n s[i] ~ f(x[i], w[i])\n y[i] ~ Normal(mean = s[i], precision = τ_y)\n \n x_i_min = x[i]\n w_i_min = w[i]\n end\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin \n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y\n)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The next step is to assign priors, initialise needed messages and marginals and call the inference function:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"m_x_0, τ_x_0 = -20.0, 1.0\nm_w_0, τ_w_0 = 20.0, 1.0\n\n# We set relatively strong priors for random walk noise components\n# and sort of vague prior for the noise of the observations\na_x, b_x = 0.01, 0.01var(real_x)\na_w, b_w = 0.01, 0.01var(real_w)\na_y, b_y = 1.0, 1.0\n\n# We set relatively strong priors for messages\nxinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))\nwinit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))\n\nimessages = (x = xinit, w = winit)\nimarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))\n\nresult = infer(\n model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),\n data = (y = real_y,), \n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = imessages, \n initmarginals = imarginals, \n iterations = 50\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's examine our inference results:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"τ_x_marginals = result.posteriors[:τ_x]\nτ_w_marginals = result.posteriors[:τ_w]\nτ_y_marginals = result.posteriors[:τ_y]\n\nsmarginals = result.posteriors[:s]\nxmarginals = result.posteriors[:x]\nwmarginals = result.posteriors[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-2:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Combination 2: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Smoothed version of `min` without zero-ed derivatives\nfunction smooth_min(x, y) \n if x < y\n return x + 1e-4 * y\n else\n return y + 1e-4 * x\n end\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"smooth_min (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_meta = @meta begin \n # In this example we are going to use a simple `Linearization` method\n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 200\nmin_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, min_real_x, label = \"x\")\npl = plot!(pl, min_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, min_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_m_x_0, min_τ_x_0 = -1.0, 1.0\nmin_m_w_0, min_τ_w_0 = 1.0, 1.0\n\nmin_a_x, min_b_x = 1.0, 1.0\nmin_a_w, min_b_w = 1.0, 1.0\nmin_a_y, min_b_y = 1.0, 1.0\n\nmin_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))\nmin_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))\n\nmin_result = infer(\n model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),\n data = (y = min_real_y,), \n meta = min_meta,\n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = min_imessages, \n initmarginals = min_imarginals, \n iterations = 100\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_τ_x_marginals = min_result.posteriors[:τ_x]\nmin_τ_w_marginals = min_result.posteriors[:τ_w]\nmin_τ_y_marginals = min_result.posteriors[:τ_y]\n\nmin_smarginals = min_result.posteriors[:s]\nmin_xmarginals = min_result.posteriors[:x]\nmin_wmarginals = min_result.posteriors[:w]\n\npx1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, min_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, min_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, min_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks). ","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Online-(filtering)-identification:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Online (filtering) identification: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rx_identification(f)\n \n # We are going to continuosly update our priors\n # based on new posteriors\n m_x_0 = datavar(Float64) \n τ_x_0 = datavar(Float64)\n m_w_0 = datavar(Float64) \n τ_w_0 = datavar(Float64)\n a_x = datavar(Float64) \n b_x = datavar(Float64)\n a_y = datavar(Float64) \n b_y = datavar(Float64)\n a_w = datavar(Float64) \n b_w = datavar(Float64)\n s = randomvar()\n y = datavar(Float64)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x ~ Normal(mean = x0, precision = τ_x)\n w ~ Normal(mean = w0, precision = τ_w)\n\n s ~ f(x, w)\n y ~ Normal(mean = s, precision = τ_y)\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We impose structured mean-field assumption for this model as well:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_constraints = @constraints begin \n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ\n_y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"autoupdates = @autoupdates begin \n m_x_0, τ_x_0 = mean_precision(q(x))\n m_w_0, τ_w_0 = mean_precision(q(w))\n a_x = shape(q(τ_x)) \n b_x = rate(q(τ_x))\n a_y = shape(q(τ_y))\n b_y = rate(q(τ_y))\n a_w = shape(q(τ_w)) \n b_w = rate(q(τ_w))\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_\nx = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_\ny)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_meta = @meta begin \n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 300\nrx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, rx_real_x, label = \"x\")\npl = plot!(pl, rx_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"engine = infer(\n model = rx_identification(smooth_min),\n constraints = rx_constraints,\n data = (y = rx_real_y,),\n autoupdates = autoupdates,\n meta = rx_meta,\n returnvars = (:x, :w, :τ_x, :τ_w, :τ_y, :s),\n keephistory = 1000,\n historyvars = KeepLast(),\n initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),\n iterations = 10,\n free_energy = true, \n free_energy_diagnostics = nothing,\n autostart = true,\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInferenceEngine:\n Posteriors stream | enabled for (w, s, τ_x, τ_w, τ_y, x)\n Free Energy stream | enabled\n Posteriors history | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)\n Free Energy history | available\n Enabled events | [ ]","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_smarginals = engine.history[:s]\nrx_xmarginals = engine.history[:x]\nrx_wmarginals = engine.history[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, rx_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = \"Estimated X\")\n\npx1 = plot!(px1, rx_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = \"Estimated W\")\n\npx2 = scatter!(px2, rx_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the \"disabled\" state, does not infer anything and simply increases its variance (which is expected for the random walk).","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Handling-Missing-Data","page":"Kalman filtering and smoothing","title":"Handling Missing Data","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let us assume that the following model generates the data","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n x_t sim mathcalNleft(x_t-1 10right) \n y_t sim mathcalNleft(x_t P right) \nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation haty_t in mathrmR we sometimes will catch missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function smoothing(n, x0)\n \n P ~ Gamma(shape = 0.001, scale = 0.001)\n x_prior ~ Normal(mean = mean(x0), var = var(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ Normal(mean = x_prev, precision = 1.0)\n y[i] ~ Normal(mean = x[i], precision = P)\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We need to manually extend the set of rules to support ::Missing values","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"P = 1.0\nn = 250\n\nreal_signal = map(e -> sin(0.05 * e), collect(1:n))\nnoisy_data = real_signal + rand(Normal(0.0, sqrt(P)), n);\nmissing_indices = 100:125\nmissing_data = similar(noisy_data, Union{Float64, Missing}, )\n\ncopyto!(missing_data, noisy_data)\n\nfor index in missing_indices\n missing_data[index] = missing\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0_prior = NormalMeanVariance(0.0, 1000.0)\n\nresult = infer(\n model = smoothing(n, x0_prior), \n data = (y = missing_data,), \n constraints = constraints,\n initmarginals = (P = Gamma(0.001, 0.001), ),\n returnvars = (x = KeepLast(),),\n iterations = 20\n);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"plot(real_signal, label = \"Noisy signal\", legend = :bottomright)\nscatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = \"Missing region\")\nplot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = \"Estimated hidden state\")","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#examples-conjugate-computational-variational-message-passing-(cvi)","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#An-example:-nonlinear-dynamical-system","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"An example: nonlinear dynamical system","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position z_t at time t. Instead they have access to the observed squared distance y_t between the object and some reference point s. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# data generating process\nnr_observations = 50\nreference_point = 53\nhidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)\nmeasurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot hidden location and reference frame\np1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label=\"hidden location\")\nhline!([reference_point], linewidth=3, label=\"reference point\")\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot measurements\np2 = scatter(1:nr_observations, measurements, linewidth=3, label=\"measurements\")\nxlabel!(\"time [sec]\"), ylabel!(\"squared distance [cm2]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"beginaligned\n p(tau) = Gamma(tau mid alpha_tau beta_tau)\n p(gamma) = Gamma(gamma mid alpha_gamma beta_gamma)\n p(z_t mid z_t - 1 tau) = mathcalN(z_t mid z_t - 1 + 1 tau^-1)\n p(y_t mid z_t gamma) = mathcalN(y_t mid (z_t - s)^2 gamma^-1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"where the researchers put priors on the process and measurement noise parameters, tau and gamma, respectively. They do this, because they do not know the accuracy of their devices.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"function compute_squared_distance(z)\n (z - reference_point)^2\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function measurement_model(nr_observations)\n\n # allocate random variables and observations\n z = randomvar(nr_observations)\n y = datavar(Float64, nr_observations)\n\n # set priors on precision parameters\n τ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n γ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n \n # specify estimate of initial location\n z[1] ~ Normal(mean = 0, precision = τ)\n y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)\n\n # loop over observations\n for t in 2:nr_observations\n\n # specify state transition model\n z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)\n\n # specify non-linear observation model\n y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)\n \n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)\n compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function model_meta(...)\n f() -> CVI(args...)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"See ?CVI for more information about the args....","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In the above example, we will assume the following posterior factorization:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function measurement_constraints()\n q(z, τ, γ) = q(z)q(τ)q(γ)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function posterior_constraints() begin\n q(z, γ) = q(z)q(γ) # CVI\n q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"results = infer(\n model = measurement_model(nr_observations),\n data = (y = measurements,),\n iterations = 5,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = measurement_constraints(),\n meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),\n initmessages = (z = NormalMeanVariance(0, 5),),\n initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),\n)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Inference results:\n Posteriors | available for (z)\n Free Energy: | Real[1241.91, 429.933, 376.869, 365.774, 362.879]","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot estimates for location\np1 = plot(collect(1:nr_observations), hidden_location, label = \"hidden location\", legend=:topleft, linewidth=3, color = :red)\nplot!(map(mean, results.posteriors[:z]), label = \"estimated location (±2σ)\", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot Bethe free energy\np2 = plot(results.free_energy, linewidth=3, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size = (1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Requirements","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Requirements","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"There are several main requirements for the CVI procedure to satisfy:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The out interface of the non-linearity must be independently factorized with respect to other variables in the model.\nThe messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function model(...)\n ...\n y ~ f(x1, x2, ..., xN)\n ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity\n ... \nend\n\n@constraints function constraints_meta() begin\n q(y, z1, ..., zn) = q(y)q(z1,...,zM)\n ...\nend;\n\n@meta function model_meta(...)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer))\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note that not all exponential family distributions are implemented.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Extensions","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Extensions","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Using-a-custom-optimizer","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Using a custom optimizer","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"CVI only supports Optimisers optimizers out of the box.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Below an explanation on how to extend to it to a custom optimizer.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Suppose we have CustomDescent structure which we want to use inside CVI for optimization.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"ReactiveMP.cvi_update! incapsulates the gradient step:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"opt is used to select your optimizer structure\nλ is the current value\n∇ is a gradient value computed inside CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"struct CustomDescent \n learning_rate::Float64\nend\n\n# Must return an optimizer and its initial state\nfunction ReactiveMP.cvi_setup(opt::CustomDescent, q)\n return (opt, nothing)\nend\n\n# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)\nfunction ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)\n opt, _ = opt_and_state\n λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))\n copyto!(new_λ, λ̂)\n return opt_and_state, new_λ\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's try to apply it to a model: beginaligned p(x) = mathcalN(0 1)\n p(y_imid x) = mathcalN(y_i mid x^2 1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's generate some synthetic data for the model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# generate data\ny = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)\nhistogram(y)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Again we can create the corresponding model as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# specify non-linearity\nf(x) = x ^ 2\n\n# specify model\n@model function normal_square_model(nr_observations)\n\n # allocate observations\n y = datavar(Float64, nr_observations)\n\n # describe prior on latent state\n x ~ NormalMeanPrecision(0, 100)\n\n # transform latent state\n mean ~ f(x)\n\n # observation model\n y .~ NormalMeanVariance(mean, 1)\n\nend\n\n# specify meta\n@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"normal_square_meta (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"res = infer(\n model = normal_square_model(1000),\n data = (y = y,),\n iterations = 10,\n free_energy = true,\n initmessages = (x = NormalMeanVariance(0, 100),),\n meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))\n)\n\nmean(res.posteriors[:x][end])","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"-18.998075156688632","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working! ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note: x^2 can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"page"},{"location":"library/functional-forms/#lib-forms","page":"Built-in functional form constraints","title":"Built-in Functional Forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.","category":"page"},{"location":"library/functional-forms/#lib-forms-custom-constraints","page":"Built-in functional form constraints","title":"Custom functional forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.","category":"page"},{"location":"library/functional-forms/#lib-forms-unspecified-constraint","page":"Built-in functional form constraints","title":"UnspecifiedFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: Nothing # This is the default setting\nend","category":"page"},{"location":"library/functional-forms/#lib-forms-point-mass-constraint","page":"Built-in functional form constraints","title":"PointMassFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. ","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.PointMassFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.PointMassFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.PointMassFormConstraint","text":"PointMassFormConstraint\n\nOne of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.\n\nKeyword arguments\n\noptimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer\nstarting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point\nboundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries\n\nCustom optimizer callback interface\n\n# This is an example of the `custom_optimizer` interface\nfunction custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # should return argmin of the -logpdf(distribution)\nend\n\nCustom starting point callback interface\n\n# This is an example of the `custom_starting_point` interface\nfunction custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # built-in optimizer expects an array, even for a univariate distribution\n return [ 0.0 ] \nend\n\nCustom boundaries callback interface\n\n# This is an example of the `custom_boundaries` interface\nfunction custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # returns a tuple of `lower` and `upper` boundaries\n return (-Inf, Inf)\nend\n\nTraits\n\nis_point_mass_form_constraint = true\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = PointMass (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-sample-list-constraint","page":"Built-in functional form constraints","title":"SampleListFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000)\n # or \n q(y) :: SampleList(1000, LeftProposal())\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.SampleListFormConstraint\nRxInfer.AutoProposal\nRxInfer.LeftProposal\nRxInfer.RightProposal","category":"page"},{"location":"library/functional-forms/#RxInfer.SampleListFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.SampleListFormConstraint","text":"SampleListFormConstraint(rng, strategy, method)\n\nOne of the form constraint objects. Approximates DistProduct with a SampleList object. \n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = SampleList (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.AutoProposal","page":"Built-in functional form constraints","title":"RxInfer.AutoProposal","text":"Tries to determine the proposal distribution in the SampleList approximation automatically.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.LeftProposal","page":"Built-in functional form constraints","title":"RxInfer.LeftProposal","text":"Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.RightProposal","page":"Built-in functional form constraints","title":"RxInfer.RightProposal","text":"Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-fixed-marginal-constraint","page":"Built-in functional form constraints","title":"FixedMarginalFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints function block_updates(x_posterior = nothing) \n # `nothing` returns the computed posterior marginal\n q(x) :: Marginal(x_posterior)\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.FixedMarginalFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.FixedMarginalFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.FixedMarginalFormConstraint","text":"FixedMarginalFormConstraint\n\nOne of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.\n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = Marginal (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-composite-constraint","page":"Built-in functional form constraints","title":"CompositeFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass()\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/#examples-hierarchical-gaussian-filter","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"","category":"section"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Simple HGF model can be defined as:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n x^(j)_k sim mathcalN(x^(j)_k - 1 f_k(x^(j - 1)_k)) \n y_k sim mathcalN(x^(j)_k tau_k)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"where j is an index of layer in hierarchy, k is a time step and f_k is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with f_k = exp(kappa x + omega) variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n z_k sim mathcalN(z_k - 1 mathcaltau_z) \n x_k sim mathcalN(x_k - 1 exp(kappa z_k + omega)) \n y_k sim mathcalN(x_k mathcaltau_y)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"For simplicity we will consider tau_z, tau_y, kappa and omega known and fixed, but there are no principled limitations to make them random variables too.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"using RxInfer, BenchmarkTools, Random, Plots","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function generate_data(rng, k, w, zv, yv)\n z_prev = 0.0\n x_prev = 0.0\n\n z = Vector{Float64}(undef, n)\n v = Vector{Float64}(undef, n)\n x = Vector{Float64}(undef, n)\n y = Vector{Float64}(undef, n)\n\n for i in 1:n\n z[i] = rand(rng, Normal(z_prev, sqrt(zv)))\n v[i] = exp(k * z[i] + w)\n x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))\n y[i] = rand(rng, Normal(x[i], sqrt(yv)))\n\n z_prev = z[i]\n x_prev = x[i]\n end \n \n return z, x, y\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Seed for reproducibility\nseed = 42\n\nrng = MersenneTwister(seed)\n\n# Parameters of HGF process\nreal_k = 1.0\nreal_w = 0.0\nz_variance = abs2(0.2)\ny_variance = abs2(0.1)\n\n# Number of observations\nn = 300\n\nz, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n scatter!(px, 1:n, y, label = \"y_i\", color = :red, ms = 2, alpha = 0.2)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To create a model we use the @model macro:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# We create a single-time step of corresponding state-space process to\n# perform online learning (filtering)\n@model function hgf(real_k, real_w, z_variance, y_variance)\n \n # Priors from previous time step for `z`\n zt_min_mean = datavar(Float64)\n zt_min_var = datavar(Float64)\n \n # Priors from previous time step for `x`\n xt_min_mean = datavar(Float64)\n xt_min_var = datavar(Float64)\n\n zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)\n xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)\n\n # Higher layer is modelled as a random walk \n zt ~ NormalMeanVariance(zt_min, z_variance)\n \n # Lower layer is modelled with `GCV` node\n gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)\n \n # Noisy observations \n y = datavar(Float64)\n y ~ NormalMeanVariance(xt, y_variance)\n \n return gcvnode\nend\n\n@constraints function hgfconstraints() \n q(xt, zt, xt_min) = q(xt, xt_min)q(zt)\nend\n\n@meta function hgfmeta()\n # Lets use 31 approximation points in the Gauss Hermite cubature approximation method\n GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) \nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"hgfmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function run_inference(data, real_k, real_w, z_variance, y_variance)\n\n autoupdates = @autoupdates begin\n zt_min_mean, zt_min_var = mean_var(q(zt))\n xt_min_mean, xt_min_var = mean_var(q(xt))\n end\n\n return infer(\n model = hgf(real_k, real_w, z_variance, y_variance),\n constraints = hgfconstraints(),\n meta = hgfmeta(),\n data = (y = data, ),\n autoupdates = autoupdates,\n keephistory = length(data),\n historyvars = (\n xt = KeepLast(),\n zt = KeepLast()\n ),\n initmarginals = (\n zt = NormalMeanVariance(0.0, 5.0),\n xt = NormalMeanVariance(0.0, 5.0),\n ), \n iterations = 5,\n free_energy = true,\n autostart = true,\n callbacks = (\n after_model_creation = (model, returnval) -> begin \n gcvnode = returnval\n setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))\n end,\n )\n )\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"run_inference (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"result = run_inference(y, real_k, real_w, z_variance, y_variance);\n\nmz = result.history[:zt];\nmx = result.history[:xt];","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = \"estimated z_i\", color = :teal)\n \n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = \"estimated x_i\", color = :violet)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"plot(result.free_energy_history, label = \"Bethe Free Energy\")","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see BetheFreeEnergy converges nicely to a stable point.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"At final, lets check the overall performance of our resulting Variational Message Passing algorithm:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"BenchmarkTools.Trial: 44 samples with 1 evaluation.\n Range (min … max): 90.900 ms … 158.543 ms ┊ GC (min … max): 0.00% … 0.0\n0%\n Time (median): 111.841 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 115.239 ms ± 12.876 ms ┊ GC (mean ± σ): 1.41% ± 2.9\n5%\n\n ██ \n ▄▁▁▁▁▁▁▁▁▁▄▁▇▆▆▆▇▄██▄▁▁▁▄▄▄▆▄▁▁▄▁▁▁▁▁▄▁▁▁▁▁▁▄▁▁▄▁▁▁▁▁▁▁▁▄▁▁▁▄ ▁\n 90.9 ms Histogram: frequency by time 159 ms <\n\n Memory estimate: 18.78 MiB, allocs estimate: 456888.","category":"page"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = RxInfer","category":"page"},{"location":"#RxInfer","page":"Home","title":"RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"Julia package for automatic Bayesian inference on a factor graph with reactive message passing.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.","category":"page"},{"location":"#Package-Features","page":"Home","title":"Package Features","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"User friendly syntax for specification of probabilistic models.\nAutomatic generation of message passing algorithms including\nBelief propagation\nVariational message passing\nExpectation maximization\nSupport for hybrid models combining discrete and continuous latent variables.\nSupport for hybrid distinct message passing inference algorithm under a unified paradigm.\nFactorisation and functional form constraints specification.\nEvaluation of Bethe free energy as a model performance measure.\nSchedule-free reactive message passing API.\nHigh performance.\nScalability for large models with millions of parameters and observations.\nInference procedure is differentiable.\nEasy to extend with custom nodes and message update rules.","category":"page"},{"location":"#Why-RxInfer","page":"Home","title":"Why RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a \"variational Free Energy\" cost function. For large models, manual derivation of these gradients might not be feasible, while automated \"black-box\" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.","category":"page"},{"location":"","page":"Home","title":"Home","text":"RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different \"what-if\" scenarios and enables very efficient inference in specific cases.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.","category":"page"},{"location":"#How-to-get-started?","page":"Home","title":"How to get started?","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"manuals/background.md\",\n \"manuals/comparison.md\",\n \"manuals/getting-started.md\",\n \"manuals/model-specification.md\",\n \"manuals/constraints-specification.md\",\n \"manuals/meta-specification.md\",\n \"manuals/inference-execution.md\",\n \"manuals/custom-node.md\",\n \"manuals/debugging.md\",\n \"manuals/delta-node.md\",\n \"examples/overview.md\",\n \"library/exported-methods.md\",\n \"library/functional-forms.md\",\n \"contributing/overview.md\",\n \"contributing/new-example.md\"\n]\nDepth = 2","category":"page"},{"location":"#References","page":"Home","title":"References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RxInfer: A Julia package for reactive real-time Bayesian inference - a reference paper for the RxInfer.jl framwork.\nVariational Message Passing and Local Constraint Manipulation in Factor Graphs - describes theoretical aspects of the underlying Bayesian inference method.\nReactive Message Passing for Scalable Bayesian Inference - describes implementation aspects of the Bayesian inference engine and performs benchmarks and accuracy comparison on various models.\nA Julia package for reactive variational Bayesian inference - a reference paper for the ReactiveMP.jl package, the underlying inference engine.\nThe Factor Graph Approach to Model-Based Signal Processing - an introduction to message passing and FFGs.","category":"page"},{"location":"#Ecosystem","page":"Home","title":"Ecosystem","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ReactiveMP.jl - core package for efficient and scalable for reactive message passing \nGraphPPL.jl - package for model and constraints specification\nRocket.jl - reactive programming tools","category":"page"},{"location":"#Index","page":"Home","title":"Index","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"manuals/inference/infer/#user-guide-inference","page":"Static vs Streamline inference","title":"Automatic Inference Specification","text":"","category":"section"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors. ","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"For details on manual inference specification, see the Manual Inference section.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"infer\nInferenceResult\nRxInfer.start\nRxInfer.stop\n@autoupdates\nRxInferenceEngine\nRxInferenceEvent","category":"page"},{"location":"manuals/inference/infer/#RxInfer.infer","page":"Static vs Streamline inference","title":"RxInfer.infer","text":"infer(\n model; \n data = nothing,\n datastream = nothing,\n autoupdates = nothing,\n initmarginals = nothing,\n initmessages = nothing,\n constraints = nothing,\n meta = nothing,\n options = nothing,\n returnvars = nothing, \n predictvars = nothing, \n historyvars = nothing,\n keephistory = nothing,\n iterations = nothing,\n free_energy = false,\n free_energy_diagnostics = BetheFreeEnergyDefaultChecks,\n showprogress = false,\n callbacks = nothing,\n addons = nothing,\n postprocess = DefaultPostprocess(),\n warn = true,\n events = nothing,\n uselock = false,\n autostart = true,\n catch_exception = false\n)\n\nThis function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.\n\nArguments\n\nFor more information about some of the arguments, please check below. \n\nmodel: specifies a model generator, required\ndata: NamedTuple or Dict with data, required (or datastream or predictvars)\ndatastream: A stream of NamedTuple with data, required (or data)\nautoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates\ninitmarginals = nothing: NamedTuple or Dict with initial marginals, optional\ninitmessages = nothing: NamedTuple or Dict with initial messages, optional\nconstraints = nothing: constraints specification object, optional, see @constraints\nmeta = nothing: meta specification object, optional, may be required for some models, see @meta\noptions = nothing: model creation options, optional, see ModelInferenceOptions\nreturnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information\npredictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)\nhistoryvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)\nkeephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)\niterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information\nfree_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl\nfree_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.\nshowprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)\ncatch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)\ncallbacks = nothing: inference cycle callbacks, optional, see below for more info\naddons = nothing: inject and send extra computation information along messages, see below for more info\npostprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info\nevents = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)\nuselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)\nautostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)\nwarn = true: enables/disables warnings\n\nNote on NamedTuples\n\nWhen passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.\n\nThe model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:\n\n@model function coin_toss(some_argument, some_keyword_argument = 3)\n ...\nend\n\nresult = infer(\n model = coin_toss(some_argument; some_keyword_argument = 3)\n)\n\nNote: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.\n\ndata\n\nEither data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.\n\nNote: The behavior of the data keyword argument depends on the inference setting (batch or streamline).\n\nThe data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.\n\nstreamline setting\n\nAll entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.\n\ndatastream\n\nThe datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.\n\nNote: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.\n\nFor specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as\n\ninfer(...\n initmarginals = (\n # initialize the marginal distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.\n\n- ### `initmessages`\n\nFor specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as\n\njulia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )\n\noptions\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\nreturnvars\n\nreturnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.\n\nBatch inference:\n\nAccepts a NamedTuple or Dict of return variable specifications.\nTwo specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).\nWhen iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).\nUse iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.\n\nExample:\n\nresult = infer(\n ...,\n returnvars = (\n x = KeepLast(),\n τ = KeepEach()\n )\n)\n\nShortcut for setting the same option for all variables:\n\nresult = infer(\n ...,\n returnvars = KeepLast() # or KeepEach()\n)\n\nStreamline inference:\n\nFor each symbol in returnvars, infer creates an observable stream of posterior updates.\nAgents can subscribe to these updates using the Rocket.jl package.\n\nExample:\n\nengine = infer(\n ...,\n autoupdates = my_autoupdates,\n returnvars = (:x, :τ),\n autostart = false\n)\n\npredictvars\n\npredictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.\n\nSimilar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n predictvars = (\n o = KeepLast(),\n τ = KeepEach()\n )\n)\n\nNote: The predictvars argument is exclusive for batch setting.\n\nhistoryvars\n\nhistoryvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.\n\nhistoryvars accepts a NamedTuple or Dict or return var specification. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = (\n x = KeepLast(),\n τ = KeepEach()\n ),\n keephistory = 10\n)\n\nIt is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.\n\nExample:\n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = KeepLast(),\n keephistory = 10\n)\n\nkeep_history\n\nSpecifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.\n\niterations\n\nSpecifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration. \n\nfree_energy\n\nStreamline inference:\n\nSpecifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.\n\nWhen free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.\nengine.free_energy_history: Averaged BFE history over VMP iterations.\nengine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.\nengine.free_energy_raw_history: Raw BFE history.\n\nBatch inference:\n\nSpecifies if the infer function should return Bethe Free Energy (BFE) values.\n\nOptionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.\nfree_energy_diagnostics\n\nThis settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.\n\ncatch_exception\n\nThe catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.\n\ncallbacks\n\nThe inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.\n\nresult = infer(\n ...,\n callbacks = (\n on_marginal_update = (model, name, update) -> println(\"$(name) has been updated: $(update)\"),\n after_inference = (args...) -> println(\"Inference has been completed\")\n )\n)\n\nThe callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:\n\non_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)\nbefore_model_creation: args: ()\nafter_model_creation: args: (model::FactorGraphModel, returnval)\nbefore_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nbefore_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nafter_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\nafter_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\n\nbefore_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.\n\naddons\n\nThe addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.\n\npostprocess\n\nThe postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.InferenceResult","page":"Static vs Streamline inference","title":"RxInfer.InferenceResult","text":"InferenceResult\n\nThis structure is used as a return value from the infer function. \n\nPublic Fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.\nfree_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\nerror: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.start","page":"Static vs Streamline inference","title":"RxInfer.start","text":"start(engine::RxInferenceEngine)\n\nStarts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.stop\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.stop","page":"Static vs Streamline inference","title":"RxInfer.stop","text":"stop(engine::RxInferenceEngine)\n\nStops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.start\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.@autoupdates","page":"Static vs Streamline inference","title":"RxInfer.@autoupdates","text":"@autoupdates\n\nCreates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification. \n\nEach line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.\n\nFor example:\n\n@autoupdates begin \n x = f(q(z))\nend\n\nThis structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically. \n\nAs an example consider the following model and auto-update specification:\n\n@model function kalman_filter()\n x_current_mean = datavar(Float64)\n x_current_var = datavar(Float64)\n\n x_current ~ Normal(mean = x_current_mean, var = x_current_var)\n\n x_next ~ Normal(mean = x_current, var = 1.0)\n\n y = datavar(Float64)\n y ~ Normal(mean = x_next, var = 1.0)\nend\n\nThis model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:\n\nautoupdates = @autoupdates begin\n x_current_mean, x_current_var = mean_cov(q(x_next))\nend\n\nThis structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.\n\nSee also: infer\n\n\n\n\n\n","category":"macro"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEngine","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEngine","text":"RxInferenceEngine\n\nThe return value of the rxinference function. \n\nPublic fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.\nfree_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.\nhistory: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.\nfree_energy_history: (optional) Free energy history, average over variational iterations \nfree_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)\nfree_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)\nevents: (optional) A stream of events send by the inference engine. See the events argument for the infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\n\nUse the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.\n\nSee also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEvent","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEvent","text":"RxInferenceEvent{T, D}\n\nThe RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.\n\nThe events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:\n\nusing Rocket\n\nstruct MyEventListener <: Rocket.Actor{RxInferenceEvent}\n # ... extra fields\nend\n\nfunction Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })\n model, iteration = event\n println(\"Iteration $(iteration) has been finished.\")\nend\n\nfunction Rocket.on_error!(listener::MyEventListener, err)\n # ...\nend\n\nfunction Rocket.on_complete!(listener::MyEventListener)\n # ...\nend\n\n\nand later on:\n\nengine = infer(events = Val((:after_iteration, )), ...)\n\nsubscription = subscribe!(engine.events, MyEventListener(...))\n\nSee also: infer, RxInferenceEngine\n\n\n\n\n\n","category":"type"},{"location":"examples/advanced_examples/overview/#examples-advanced_examples-overview","page":"Overview","title":"Advanced examples","text":"","category":"section"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Advanced examples contain more complex inference problems.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.\nAdvanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.\nAssessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.\nChance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.\nConjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.\nGlobal Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.\nSolve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.\nInfinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.\nNonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors","category":"page"},{"location":"manuals/constraints-specification/#user-guide-constraints-specification","page":"Constraints specification","title":"Constraints Specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"using RxInfer","category":"page"},{"location":"manuals/constraints-specification/#General-syntax","page":"Constraints specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"\n# `functional` style\n@constraints function create_my_constraints(arg1, arg2)\n ...\nend\n\n# `block` style\nmyconstraints = @constraints begin \n ...\nend\n","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In the first case it returns a function that return constraints upon calling, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(mean_field)\n q(x) :: PointMass\n\n if mean_field\n q(x, y) = q(x)q(y)\n end\nend\n\nmyconstraints = make_constraints(true)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"and in the second case it evaluates automatically and returns constraints object directly.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints begin \n q(x) :: PointMass\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/#Options-specification","page":"Constraints specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints [ warn = false ] begin \n ...\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"List of available options:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/constraints specification","category":"page"},{"location":"manuals/constraints-specification/#Marginal-and-messages-form-constraints","page":"Constraints specification","title":"Marginal and messages form constraints","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"The following constraint:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"mathrmapproximate q(x) = fracoverrightarrowmu(x)overleftarrowmu(x)int overrightarrowmu(x)overleftarrowmu(x) mathrmdxmathrmasPointMass","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\n μ(x) :: SampleList(1000)\n # it is possible to assign different form constraints on the same variable \n # both for the marginal and for the messages \nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro understands \"stacked\" form constraints. For example the following form constraint","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\nNot all combinations of \"stacked\" form constraints are compatible between each other.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.","category":"page"},{"location":"manuals/constraints-specification/#Factorisation-constraints-on-posterior-distribution-q()","page":"Constraints specification","title":"Factorisation constraints on posterior distribution q()","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"For example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) = q(x[begin])..q(x[end])\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables x_i.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\n@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"It is possible to write more complex factorisation constraints, for example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(k)\n q(x) = q(x[begin:k])q(x[k+1:end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end]. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model function my_model(arguments...)\n ...\nend\n\nconstraints = @constraints begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); constraints = constraints)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument. ","category":"page"},{"location":"contributing/overview/#contributing-overview","page":"Overview","title":"Contributing","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.","category":"page"},{"location":"contributing/overview/#Reporting-bugs","page":"Overview","title":"Reporting bugs","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.","category":"page"},{"location":"contributing/overview/#Nightly-Julia-status","page":"Overview","title":"Nightly Julia status","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"(Image: PkgEval)","category":"page"},{"location":"contributing/overview/#Suggesting-features","page":"Overview","title":"Suggesting features","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome new feature proposals. However, before submitting a feature request, consider a few things:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.\nIf you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.","category":"page"},{"location":"contributing/overview/#Contributing-code","page":"Overview","title":"Contributing code","text":"","category":"section"},{"location":"contributing/overview/#Installing-RxInfer","page":"Overview","title":"Installing RxInfer","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] dev git@github.com:your_username/RxInfer.jl.git","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nIt is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.","category":"page"},{"location":"contributing/overview/#Core-dependencies","page":"Overview","title":"Core dependencies","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.","category":"page"},{"location":"contributing/overview/#Committing-code","page":"Overview","title":"Committing code","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well. ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.","category":"page"},{"location":"contributing/overview/#Style-conventions","page":"Overview","title":"Style conventions","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Use 4 spaces for indentation\nType names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..\nFunction names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..\nVariable names and function arguments use snake_case\nThe name of a method that modifies its argument(s) must end in !","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nRxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.","category":"page"},{"location":"contributing/overview/#Unit-tests","page":"Overview","title":"Unit tests","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The tests can be evaluated by running following command in the Julia REPL:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] test RxInfer","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"In addition tests can be evaluated by running following command in the RxInfer root directory:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make test","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make devtest to use local dev-ed versions of the core packages.","category":"page"},{"location":"contributing/overview/#Makefile","page":"Overview","title":"Makefile","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl uses Makefile for most common operations:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make help: Shows help snippet\nmake test: Run tests, supports extra arguments\nmake test test_args=\"distributions:normal_mean_variance\" would run tests only from distributions/test_normal_mean_variance.jl\nmake test test_args=\"distributions:normal_mean_variance models:lgssm\" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl\nmake test dev=true would run tests while using dev-ed versions of core packages\nmake devtest: Alias for the make test dev=true ...\nmake docs: Compile documentation\nmake devdocs: Same as make docs, but uses dev-ed versions of core packages\nmake examples: Run all examples and put them in the docs/ folder if successfull \nmake devexamples: Same as make examples, but uses dev-ed versions of core packages\nmake lint: Check codestyle\nmake format: Check and fix codestyle ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nCore packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.","category":"page"},{"location":"contributing/new-release/#contributing-new-release","page":"Publishing a new release","title":"Publishing a new release","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.","category":"page"},{"location":"contributing/new-release/#Start-the-release-process","page":"Publishing a new release","title":"Start the release process","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"In order to start the release process a person with the associated permissions should: ","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Open a commit page on GitHub\nWrite the @JuliaRegistrator register comment for the commit:","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"(Image: Release comment)","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#examples-solve-gp-regression-by-sde","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"In this notebook, we solve a GP regression problem by using \"Stochastic Differential Equation\" (SDE). This method is well described in the dissertation \"Stochastic differential equation methods for spatio-temporal Gaussian process regression.\" by Arno Solin and \"Sequential Inference for Latent Temporal Gaussian Process Models\" by Jouni Hartikainen. The idea of the method is as follows.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Suppose a function f(x) follows a zero-mean Gaussian Process beginaligned f(x) sim mathcalGP(0 k(xx)) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"When the dimensionality of x is 1, we can consider f(x) as a stochastic process over time, i.e. f(t). For a certain classses of covariance functions, f(t) is a solution to an m-th order linear stochastic differential equation (SDE) beginaligned a_0 f(t) + a_1 fracd f(t)dt + dots + a_m fracd^m f(t)dt^m = w(t) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where w(t) is a zero-mean white noise process with spectral density Q_c. If we define a vector-valued function mathbff(t) = (f(t) ddt f(t)dots d^m-1dt^m-1f(t)), then we can rewrite the above SDE under the companion form","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracd mathbff(t)dt = mathbfF mathbff(t) + mathbfL w(t) quad (1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfF and mathbfL are defined based on the choice of covariance functions. From (1), we have the following state-space model: beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) quad(2a) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) quad(2b) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfA_k = exp(mathbfFDelta t_k), with Delta t_k = t_k+1 - t_k, is called the discrete-time state transition matrix, and mathbfQ_k the process noise covariance matrix. For the computation of mathbfQ_k, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state f_0 sim mathcalN(mathbf0 mathbfP_0). For stationary covariance function, the SDE has a stationary state f_infty sim mathcalN(mathbf0 mathbfP_infty), where mathbfP_infty is the solution to beginaligned fracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0 quad (mathrmLyapunov equation) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"With this stationary condition, the process noise covariance mathbfQ_k is computed as follows beginaligned mathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"For one-dimensional problem the SDE representation of the GP is defined by the matrices mathbfF mathbfL mathbfQ_c mathbfP_0 and mathbfH. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"using RxInfer, Random, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Create-state-space-model-for-GP-regression","page":"Solve GP regression by SDE","title":"Create state space model for GP regression","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Here we create a state-space model beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) \nendaligned where y_k is the noisy observation of the function f at time t_k, and sigma^2_noise is the noise variance and assumed to be known.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"@model function gp_regression(n, P∞, A, Q, H, σ²_noise)\n f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)\n f = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n \n f_prev = f_0\n\n for i=1:n\n f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])\n y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)\n f_prev = f[i]\n end\n return f, y\nend","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Generate-data","page":"Solve GP regression by SDE","title":"Generate data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Random.seed!(10)\nn = 100\nσ²_noise = 0.04;\nt = collect(range(-2, 2, length=n)); #timeline\nf_true = sinc.(t); # true process\nf_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process\n\npos = sort(randperm(75)[1:2:75]); \nt_obser = t[pos]; # time where we observe data\n\ny_data = Array{Union{Float64,Missing}}(missing, n)\nfor i in pos \n y_data[i] = f_noisy[i]\nend\n\nθ = [1., 1.]; # store [l, σ²]\nΔt = [t[1]]; # time difference\nappend!(Δt, t[2:end] - t[1:end-1]);","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Let's-visualize-our-data","page":"Solve GP regression by SDE","title":"Let's visualize our data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"plot(t, f_true, label=\"True process f(t)\")\nscatter!(t_obser, y_data[pos], label = \"Noisy observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-3/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-3/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"The Matern is a stationary covariance function and defined as follows beginaligned k(tau) = sigma^2 frac2^1-nuGamma(nu) left(fracsqrt2nutaul right)^nu K_nuleft(fracsqrt2nutaul right) endaligned where beginaligned sigma^2 textthe magnitude scale hyperparameter\nl textthe characteristic length-scale\nnu textthe smoothness hyperparameter\nK_nu() textthe modified Bessel function of the second kind endaligned When we say the Matern-3/2, we mean nu=32. The matrices for the state space model are computed as follows beginaligned mathbfF = beginpmatrix 0 1\n-lambda^2 -2lambda endpmatrix quad quad mathbfL = beginpmatrix 0 1 endpmatrix quad quad mathbfP_infty = beginpmatrix sigma^2 0 0 lambda^2sigma^2 endpmatrix quad quad mathbfH = beginpmatrix 1 0 endpmatrix quad quad Q_c = 4lambda^3sigma^2 endaligned where lambda = fracsqrt3l From these matrices we can define mathbfA_k and mathbfQ_k.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(3)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 1.];\nH = [1., 0.];\nF = [0. 1.; -λ^2 -2λ]\nP∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_32 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-5/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-5/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfF = beginpmatrix\n0 1 0\n0 0 1 \n-lambda^3 -3lambda^2 -3lambda\nendpmatrix quad quad mathbfL = beginpmatrix\n0 0 1\nendpmatrix quad quad mathbfH = beginpmatrix\n1 0 0\nendpmatrix quad quad Q_c = frac163 sigma^2 lambda^5 \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where lambda = sqrt5 l. To find mathbfP_infty, we solve the Lyapunov equation","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"of which the solution is","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nvec(mathbfP_infty) = (mathbfI otimes mathbfF + mathbfFotimesmathbfI)^-1 vec(-mathbfLQ_cmathbfL^T)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where vec() is the vectorization operator and otimes denotes the Kronecker product. Now we can find mathbfA_k and mathbfQ_k ","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfA_k = exp(mathbfFDelta t_k) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(5)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 0., 1.];\nH = [1., 0., 0.];\nF = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]\nQc = 16/3 * θ[2] * λ^5;\n\nI = diageye(3) ; \nvec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); \nP∞ = reshape(vec_P,3,3);\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_52 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Result","page":"Solve GP regression by SDE","title":"Result","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"slicedim(dim) = (a) -> map(e -> e[dim], a)\n\nplot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M32\", title = \"Matern-3/2\", legend =false, lw = 2)\nplot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M52\",legend = :bottomleft, title = \"GPRegression by SSM\", lw = 2)\nplot!(t, f_true,label=\"true process\", lw = 2)\nscatter!(t_obser, f_noisy[pos], label=\"Observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"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. ","category":"page"},{"location":"contributing/new-documentation/#guide-docs-contributing","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.\nIdentify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.\nFork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.\nMake Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.\nSubmit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.\nReview and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.\nMerging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.","category":"page"},{"location":"contributing/new-documentation/#Use-[LiveServer.jl](https://github.com/tlienart/LiveServer.jl)","page":"Contributing to the documentation","title":"Use LiveServer.jl","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"To use LiveServer.jl, simply follow these steps[1]","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"[1]: Make sure to install the LiveServer and Documenter in your current working environment.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Make sure to import the required packages ","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> using LiveServer, Documenter","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"After importing the required packages, you can start the live server with the following command:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> servedocs()","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#examples-bayesian-linear-regression-tutorial","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The first part uses a regular Bayesian Linear Regression on a simple application of fuel consumption for a car with synthetic data.\nThe second part is an adaptation of a tutorial from NumPyro and uses Hierarchical Bayesian linear regression on the OSIC pulmonary fibrosis progression dataset from Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-1.-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 1. Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-known-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He records the speed and fuel consumption for the urban road which is the xdata and ydata.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b)\n Free Energy: | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184\n.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821\n, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a\\mid y)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0,Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b)\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b\\mid y)\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"a = results.posteriors[:a]\nb = results.posteriors[:b]\n\nprintln(\"Real a: \", 0.5, \" | Estimated a: \", mean_var(a), \" | Error: \", abs(mean(a) - 0.5))\nprintln(\"Real b: \", 25.0, \" | Estimated b: \", mean_var(b), \" | Error: \", abs(mean(b) - 25.0))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err\nor: 0.001490188462705988\nReal b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error\n: 0.18735789804394898","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-unknown-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with unknown noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. beginaligned p(y_n mid a b s) = mathcalN(y_n mid ax_n + b s)\np(s) = mathcalIG(smidalpha theta)\np(a) = mathcalN(a mid m_a v_a) \np(b) = mathcalN(b mid m_b v_b) endaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_unknown_noise(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n s ~ InverseGamma(1.0, 1.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = s)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)\n\nscatter(x_data_un, y_data_un, title = \"Dateset with unknown noise (mountain road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_unknown_noise = infer(\n model = linear_regression_unknown_noise(length(x_data_un)), \n data = (y = y_data_un, x = x_data_un), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast(), s = KeepLast()), \n iterations = 20,\n constraints = MeanField(),\n initmarginals = (s = vague(InverseGamma), ),\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, s)\n Free Energy: | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125\n.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56\n, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"plot(results_unknown_noise.free_energy, title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Below he visualizes the obtained posterior distributions for parameters:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(a)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(b)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25.0 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(b)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25.0 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L\"Prior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(s)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 200 ], label=L\"True $s$\", c = 3)\npsb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L\"Posterior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(s)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 200 ], label=L\"True $s$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$s$\", ylabel=L\"$p(s)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He sees that in the presence of more noise the inference result is more uncertain about the actual values for a and b parameters.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John samples a and b and plot many possible regression lines on the same plot:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"as = rand(results_unknown_noise.posteriors[:a], 100)\nbs = rand(results_unknown_noise.posteriors[:b], 100)\np = scatter(x_data_un, y_data_un, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)\nend\n\nplot(p, size = (900, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"From this plot John can see that many lines do fit the data well and there is no definite \"best\" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Multivariate-linear-regression","page":"Bayesian Linear Regression Tutorial","title":"Multivariate linear regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_multivariate(dim, nr_samples)\n a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))\n b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))\n W ~ InverseWishart(dim + 2, 100 * diageye(dim))\n\n # Here is a small trick to make the example work\n # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`\n x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n z = randomvar(nr_samples)\n\n z .~ x .* a .+ b\n y .~ MvNormal(mean = z, covariance = W)\n\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"After received all the measurement records, he plots the measurements and performance index:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dim_mv = 6\nnr_samples_mv = 50\nrng_mv = StableRNG(42)\na_mv = randn(rng_mv, dim_mv)\nb_mv = 10 * randn(rng_mv, dim_mv)\nv_mv = 100 * rand(rng_mv, dim_mv)\n\nx_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft)\n\nplt = palette(:tab10)\n\ndata_set_label = [\"\"]\n\nfor k in 1:dim_mv\n global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\nxlabel!(L\"$x$\")\nylabel!(L\"$y$\")\np","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Before this data can be used to perform inference, John needs to change its format slightly.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)\ny_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_mv = infer(\n model = linear_regression_multivariate(dim_mv, nr_samples_mv),\n data = (y = y_data_mv_processed, x = x_data_mv_processed),\n initmarginals = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),\n initmessages = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),\n returnvars = (a = KeepLast(), b = KeepLast(), W = KeepLast()),\n free_energy = true,\n iterations = 50,\n constraints = MeanField()\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, W)\n Free Energy: | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7\n22, 712.341, 700.865, 690.782, 682.505 … 664.434, 664.434, 664.434, 664.4\n34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft, xlabel=L\"$x$\", ylabel=L\"$y$\")\n\n# how many lines to plot\nr = 50\n\ni_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))\ni_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))\n\nplt = palette(:tab10)\n\nfor k in 1:dim_mv\n x_mv_k = x_data_mv[k]\n y_mv_k = y_data_mv[k]\n\n for i in 1:r\n global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])\n end\n\n global p = scatter!(p, x_mv_k, y_mv_k, label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\n\n# truncate the init step\nf = plot(results_mv.free_energy[2:end], title =\"Bethe free energy convergence\", label = nothing, xlabel = \"Iteration\", ylabel = \"Bethe free energy [nats]\") \n\nplot(p, f, size = (1000, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_a_mv = results_mv.posteriors[:a]\n\nps_a = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $a_{%$k}$\", xlabel=L\"$a_{%$k}$\", ylabel=L\"$p(a_{%$k})$\", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])\n\n local m_a_mv_k = mean(i_a_mv)[k]\n local v_a_mv_k = std(i_a_mv)[k, k]\n \n _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(a_{%$k})$\", c=2,)\n _p = vline!(_p, [ a_mv[k] ], label=L\"True $a_{%$k}$\", c = 3)\n \n push!(ps_a, _p)\nend\n\nplot(ps_a...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_b_mv = results_mv.posteriors[:b]\n\nps_b = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $b_{%$k}$\", xlabel=L\"$b_{%$k}$\", ylabel=L\"$p(b_{%$k})$\", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])\n local m_b_mv_k = mean(i_b_mv)[k]\n local v_b_mv_k = std(i_b_mv)[k, k]\n\n _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(b_{%$k})$\", c=2,)\n _p = vline!(_p, [ b_mv[k] ], label=L\"Real $b_{%$k}$\", c = 3)\n \n push!(ps_b, _p)\nend\n\nplot(ps_b...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L\"True $s_d$\")\nscatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L\"$\\mathrm{E}[s_d] \\pm \\sigma$\")\nplot!(; xlabel=L\"Dimension $d$\", ylabel=\"Variance\", title=\"Estimated variance of the noise\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-2.-Hierarchical-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 2. Hierarchical Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# https://www.machinelearningplus.com/linear-regression-in-julia/\n# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Understanding-the-Task","page":"Bayesian Linear Regression Tutorial","title":"Understanding the Task","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's explore the data and delve deeper into the problem involved.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dataset = CSV.read(\"../data/hbr/osic_pulmonary_fibrosis.csv\", DataFrame);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"describe(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"7×7 DataFrame\n Row │ variable mean min median max \n ⋯\n │ Symbol Union… Any Union… Any \n ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ Patient ID00007637202177411956430 ID004266\n372 ⋯\n 2 │ Weeks 31.8618 -5 28.0 133\n 3 │ FVC 2690.48 827 2641.0 6399\n 4 │ Percent 77.6727 28.8776 75.6769 153.145\n 5 │ Age 67.1885 49 68.0 88 \n ⋯\n 6 │ Sex Female Male\n 7 │ SmokingStatus Currently smokes Never sm\noke\n 3 columns om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"first(dataset, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5×7 DataFrame\n Row │ Patient Weeks FVC Percent Age Sex Sm\noki ⋯\n │ String31 Int64 Int64 Float64 Int64 String7 St\nrin ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ ID00007637202177411956430 -4 2315 58.2536 79 Male Ex\n-sm ⋯\n 2 │ ID00007637202177411956430 5 2214 55.7121 79 Male Ex\n-sm\n 3 │ ID00007637202177411956430 7 2061 51.8621 79 Male Ex\n-sm\n 4 │ ID00007637202177411956430 9 2144 53.9507 79 Male Ex\n-sm\n 5 │ ID00007637202177411956430 11 2069 52.0634 79 Male Ex\n-sm ⋯\n 1 column om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart(dataset, patient_id; line_kws = true)\n info = patientinfo(dataset, patient_id)\n x = info[!, \"Weeks\"]\n y = info[!, \"FVC\"]\n\n p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)\n p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = \"Weeks\", ylabel = \"FVC\")\n \n if line_kws\n # Use the `GLM.jl` package to estimate linear regression\n linearFormulae = @formula(FVC ~ Weeks)\n linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))\n linearPredicted = predict(linearRegressor)\n p = plot!(p, x, linearPredicted, color = :red, lw = 3)\n end\n\n return p\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart(dataset, \"ID00007637202177411956430\")\np2 = patientchart(dataset, \"ID00009637202177434476278\")\np3 = patientchart(dataset, \"ID00010637202177584971671\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modelling:-Bayesian-Hierarchical-Linear-Regression-with-Partial-Pooling","page":"Bayesian Linear Regression Tutorial","title":"Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the \"pooled model.\" On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the \"unpooled model,\" where each patient has completely separate regression lines.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In this analysis, we will adopt a middle ground approach known as \"Partial pooling.\" Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Mathematically, the model is described by the following equations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n mu_alpha sim mathcalN(mathrmmean = 00 mathrmvariance = 2500000) \n sigma_alpha sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mu_beta sim mathcalN(mathrmmean = 00 mathrmvariance = 90) \n sigma_beta sim mathcalGamma(mathrmshape = 175 mathrmscale = 136) \n alpha_i sim mathcalN(mathrmmean = mu_alpha mathrmprecision = sigma_alpha) \n beta sim mathcalN(mathrmmean = mu_beta mathrmprecision = sigma_beta) \n sigma sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mathrmFVC_ij sim mathcalN(mathrmmean = alpha_i + t beta_i mathrmprecision = sigma)\n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Implementing this model in RxInfer is pretty straightforward:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled(patient_codes, weeks)\n μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β ~ Normal(mean = 0.0, var = 9.0) # Prior for the mean of β (slope)\n σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)\n σ_β ~ Gamma(shape = 1.75, scale = 1.36) # Prior for the precision of β (slope)\n\n n_codes = length(patient_codes) # Total number of data points\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution\n β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the standard deviation of the error term\n \n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes) # Observed FVC measurements\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@constraints function partially_pooled_constraints()\n # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent\n q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)\n # Assume that `μ_α`, `σ_α`, `α` are jointly independent\n q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)\n # Assume that `μ_β`, `σ_β`, `β` are jointly independent\n q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)\n # Assume that `FVC_est`, `σ` are jointly independent\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inference-in-the-model","page":"Bayesian Linear Regression Tutorial","title":"Inference in the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patient_ids = dataset[!, \"Patient\"] # get the column of all patients\npatient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));\npatient_code_column = map(patient -> patient_code_encoder[patient], patient_ids)\n\ndataset[!, :PatientCode] = patient_code_column\n\nfirst(patient_code_encoder, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5-element Vector{Pair{InlineStrings.String31, Int64}}:\n \"ID00197637202246865691526\" => 85\n \"ID00388637202301028491611\" => 160\n \"ID00341637202287410878488\" => 142\n \"ID00020637202178344345685\" => 9\n \"ID00305637202281772703145\" => 127","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_inference(dataset)\n\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n\n results = infer(\n model = partially_pooled(patient_codes, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n σ = vague(Gamma),\n σ_α = vague(Gamma),\n σ_β = vague(Gamma),\n ),\n returnvars = KeepLast(),\n iterations = 100\n )\n \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference_results = partially_pooled_inference(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Checking-the-model","page":"Bayesian Linear Regression Tutorial","title":"Checking the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspecting-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspecting the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)\n local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Looks like our model learned personalized alphas and betas for each patient!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Visualizing-FVC-decline-curves-for-some-patients","page":"Bayesian Linear Regression Tutorial","title":"Visualizing FVC decline curves for some patients","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)\n info = patientinfo(dataset, patient_id)\n patient_code_id = encoder[patient_id]\n\n patient_α = results.posteriors[:α][patient_code_id]\n patient_β = results.posteriors[:β][patient_code_id]\n\n estimated_σ = inv(mean(results.posteriors[:σ]))\n \n predict_weeks = range(-12, 134)\n\n predicted = map(predict_weeks) do week\n pm = mean(patient_α) + mean(patient_β) * week\n pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ\n return pm, sqrt(pv)\n end\n \n p = patientchart(dataset, patient_id; kwargs...)\n \n return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart_bayesian (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\")\np2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\")\np3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The results match our expectations perfectly! Let's highlight the observations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.\nThe model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.\nAdditionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Computing-the-modified-Laplace-Log-Likelihood-and-RMSE","page":"Bayesian Linear Regression Tutorial","title":"Computing the modified Laplace Log Likelihood and RMSE","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n sigma_mathrmclipped = max(sigma 70) \n delta = min(vert mathrmFVC_mathrmtrue - mathrmFVC_mathrmpredvert 1000) \n mathrmmetric = -fracsqrt2deltasigma_mathrmclipped - mathrmln(sqrt2sigma_mathrmclipped) \n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function FVC_predict(results)\n return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s\n return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"FVC_predict (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function compute_rmse(results, dataset)\n FVC_predicted = FVC_predict(results)\n return mean((dataset[!, \"FVC\"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)\nend\n\nfunction compute_laplace_log_likelihood(results, dataset)\n FVC_predicted = FVC_predict(results)\n sigma_c = std.(FVC_predicted)\n sigma_c[sigma_c .< 70] .= 70\n delta = abs.(mean.(FVC_predicted) .- dataset[!, \"FVC\"])\n delta[delta .> 1000] .= 1000\n return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"compute_laplace_log_likelihood (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.0313266260767\nLaplace Log Likelihood: -6.15689374755478","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Add-layer-to-model-hierarchy:-Smoking-Status","page":"Bayesian Linear Regression Tutorial","title":"Add layer to model hierarchy: Smoking Status","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We can enhance the model by incorporating the column \"SmokingStatus\" as a pooling level, where model parameters will be partially pooled within the groups \"Never smoked,\" \"Ex-smoker,\" and \"Currently smokes.\" To achieve this, we need to:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Encode the \"SmokingStatus\" column. Map the patient encoding to the corresponding \"SmokingStatus\" encodings. Refine and retrain the model with the additional hierarchical structure.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"combine(groupby(dataset, \"SmokingStatus\"), nrow)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"3×2 DataFrame\n Row │ SmokingStatus nrow\n │ String31 Int64\n─────┼─────────────────────────\n 1 │ Ex-smoker 1038\n 2 │ Never smoked 429\n 3 │ Currently smokes 82","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, \"SmokingStatus\"]))))\nsmoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id\n smoking_status = first(unique(patientinfo(dataset, patient_id)[!, \"SmokingStatus\"]))\n return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]\nend)\n\nsmoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)\n μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)\n σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n σ_β_global ~ Gamma(shape = 1.75, scale = 1.36) # Corresponds to half-normal with scale 3.0\n\n n_codes = length(patient_codes) # Total number of data points\n n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern\n μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern\n \n for i in 1:n_smoking_statuses\n μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)\n μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)\n end\n \n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)\n β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n\n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes)\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\n \nend\n\n@constraints function partially_pooled_with_smooking_constraints()\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)\n q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)\n q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)\n q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smooking_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n \n return infer(\n model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_with_smooking_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n σ = Gamma(1.75, 45.54),\n σ_α_global = Gamma(1.75, 45.54),\n σ_β_global = Gamma(1.75, 1.36),\n ),\n returnvars = KeepLast(),\n iterations = 100,\n )\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspect-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspect the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)\n local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)\n local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])\n local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α_global)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β_global)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n local p5 = plot(title = \"q(μ_α_smoking_status)...\", legend = false)\n local p6 = plot(title = \"q(μ_β_smoking_status)...\", legend = false)\n \n foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) \n foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)\n \n plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Interpret-smoking-status-model-parameters","page":"Bayesian Linear Regression Tutorial","title":"Interpret smoking status model parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Dict{InlineStrings.String31, Int64} with 3 entries:\n \"Currently smokes\" => 3\n \"Ex-smoker\" => 1\n \"Never smoked\" => 2","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]\n\nprintln(\"Trend for\")\nforeach(pairs(smoking_id_mapping)) do (key, id)\n println(\" $key: $(mean(posteriors_μ_β_smoking_status[id]))\")\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Trend for\n Currently smokes: 1.8157457671008241\n Ex-smoker: -4.56516461765951\n Never smoked: -4.446729680170274","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Let's look at these curves for individual patients to help interpret these model results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Never smoked\np1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\") \n# Ex-smoker\np2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\") \n# Currently smokes\np3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\") \n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Review-patients-that-currently-smoke","page":"Bayesian Linear Regression Tutorial","title":"Review patients that currently smoke","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"When plotting each patient with the smoking status \"Currently smokes,\" we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Depending on the purpose of the model, we can proceed in different ways:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.\nHowever, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the \"Currently smokes\" group's parameters closer to the global parameters, or even consider merging the group with \"Ex-smokers.\" Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"let \n local plots = []\n\n for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==(\"Currently smokes\"), dataset)[!, \"Patient\"]))\n push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))\n end\n\n plot(plots..., size = (1200, 1200))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modified-Laplace-Log-Likelihood-and-RMSE-for-model-with-Smoking-Status-Level","page":"Bayesian Linear Regression Tutorial","title":"Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We calculate the metrics for the updated model and compare to the original model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.7845980866563\nLaplace Log Likelihood: -6.165346437287973","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#References","page":"Bayesian Linear Regression Tutorial","title":"References","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#examples-probit-model-(ep)","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable x_t with the discrete variable y_t. The model is defined as:","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"beginaligned\n u = 01 \n x_0 sim mathcalN(0 100) \n x_t sim mathcalN(x_t-1+ u 001) \n y_t sim mathrmBer(Phi(x_t))\nendaligned","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Import-packages","page":"Probit Model (EP)","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"using RxInfer, StableRNGs, Random, Plots\nusing StatsFuns: normcdf","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Data-generation","page":"Probit Model (EP)","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n \n # hyper parameters\n u = 0.1\n\n # allocate space for data\n data_x = zeros(nr_samples + 1)\n data_y = zeros(nr_samples)\n \n # initialize data\n data_x[1] = -2\n \n # generate data\n for k = 2:nr_samples + 1\n \n # calculate new x\n data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)\n \n # calculate y\n data_y[k-1] = normcdf(data_x[k]) > rand(rng)\n \n end\n \n # return data\n return data_x, data_y\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"n = 40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"data_x, data_y = generate_data(n);","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"p = plot(xlabel = \"t\", ylabel = \"x, y\")\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\")","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Model-specification","page":"Probit Model (EP)","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"@model function probit_model(nr_samples::Int64)\n \n # allocate space for variables\n x = randomvar(nr_samples + 1)\n y = datavar(Float64, nr_samples)\n \n # specify uninformative prior\n x[1] ~ Normal(mean = 0.0, precision = 0.01)\n \n # create model \n for k = 2:nr_samples + 1\n x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)\n y[k - 1] ~ Probit(x[k]) where {\n # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge\n # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations\n pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) \n }\n end\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Inference","page":"Probit Model (EP)","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"result = infer(\n model = probit_model(length(data_y)), \n data = (y = data_y, ), \n iterations = 5, \n returnvars = (x = KeepLast(),),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"Inference results:\n Posteriors | available for (x)\n Free Energy: | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Results","page":"Probit Model (EP)","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"mx = result.posteriors[:x]\n\np = plot(xlabel = \"t\", ylabel = \"x, y\", legend = :bottomright)\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\", lw = 2)\np = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label=\"x (inferred mean)\")\n\nf = plot(xlabel = \"t\", ylabel = \"BFE\")\nf = plot!(result.free_energy, label = \"Bethe Free Energy\")\n\nplot(p, f, size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#examples-advanced-tutorial","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This tutorial is also available in the documentation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#General-model-specification-syntax","page":"Advanced Tutorial","title":"General model specification syntax","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We use the @model macro from the RxInfer.jl package to create a probabilistic model p(s y) and we also specify extra constraints on the variational family of distributions mathcalQ, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `@model` macro accepts a regular Julia function\n@model function test_model1(s_mean, s_precision)\n \n # We use the `randomvar` function to create \n # a random variable in our model\n s = randomvar()\n \n # the `tilde` operator creates a functional dependency\n # between variables in our model and can be read as \n # `sampled from` or `is modeled by`\n s ~ Normal(mean = s_mean, precision = s_precision)\n \n # We use the `datavar` function to create \n # observed data variables in our models\n # We also need to specify the type of our data \n # In this example it is `Float64`\n y = datavar(Float64)\n \n y ~ Normal(mean = s, precision = 1.0)\n \n # It is possible to return something from the model specification (including variables and nodes)\n return \"Hello world\"\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"modelgenerator = test_model1(0.0, 1.0)\n\nmodel, returnval = create_model(modelgenerator)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(FactorGraphModel(), \"Hello world\")","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(): returns an array of factor nodes in a corresponding factor graph\ngetrandom(): returns an array of random variables in the model\ngetdata(): returns an array of data inputs in the model\ngetconstant(): returns an array of constant values in the model","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(model)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"FactorNodesCollection(nodes: 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getrandom(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :s","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getdata(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :y","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getconstant(model) .|> getconst","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 1.0","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model2(n)\n \n if n <= 1\n error(\"`n` argument must be greater than one.\")\n end\n \n # `randomvar(n)` creates a dense sequence of \n # random variables\n s = randomvar(n)\n \n # `datavar(Float64, n)` creates a dense sequence of \n # observed data variables of type `Float64`\n y = datavar(Float64, n)\n \n s[1] ~ Normal(mean = 0.0, precision = 0.1)\n y[1] ~ Normal(mean = s[1], precision = 1.0)\n \n for i in 2:n\n s[i] ~ Normal(mean = s[i - 1], precision = 1.0)\n y[i] ~ Normal(mean = s[i], precision = 1.0)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, _ = create_model(test_model2(10));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of factor nodes in generated Factor Graph\ngetnodes(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"20","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of random variables\ngetrandom(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of data inputs\ngetdata(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of constant values\ngetconstant(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"21","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use complex expressions inside the functional dependency expressions","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# s = randomvar() here is optional\n# `~` creates random variables automatically\ns ~ NormalMeanPrecision(0.0, 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example model which will throw an error:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function error_model1()\n s = 1.0\n s ~ NormalMeanPrecision(0.0, 1.0)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Creates constant reference in a model with a prespecified value\nc = constvar(0.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)\n \n s = randomvar(n)\n \n y = datavar(Vector{Float64}, n)\n \n # Here we create constant references\n # for constant matrices in our model \n # to make inference more memory efficient\n cA = constvar(A)\n cP = constvar(P)\n cQ = constvar(Q)\n \n s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)\n y[1] ~ MvNormal(mean = s[1], covariance = cQ)\n \n for i in 2:n\n s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)\n y[i] ~ MvNormal(mean = s[i], covariance = cQ)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n\n # In this example `ynode` refers to the corresponding \n # `GaussianMeanVariance` node created in the factor graph\n ynode, y ~ GaussianMeanVariance(0.0, 1.0)\n \n return ynode, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Probabilistic-inference-in-RxInfer.jl","page":"Advanced Tutorial","title":"Probabilistic inference in RxInfer.jl","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Observables","page":"Advanced Tutorial","title":"Observables","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Observables are lazy push-based collections and they deliver their values over time.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Timer that emits a new value every second and has an initial one second delay \nobservable = timer(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerObservable(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"actor = (value) -> println(value)\nsubscription1 = subscribe!(observable, actor)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We always need to unsubscribe from some observables\nunsubscribe!(subscription1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We can modify our observables\nmodified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Int64, MapProxy(Int64))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscription2 = subscribe!(modified, (value) -> println(value))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(subscription2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n \n # We assume that the outcome of each coin flip \n # is modeled by a Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during the inference step\n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can call the inference function to run inference in such model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"p = 0.75 # Bias of a coin\n\ndataset = float.(rand(Bernoulli(p), 500));\n\nresult = infer(\n model = coin_toss_model(length(dataset)),\n data = (y = dataset, )\n)\n\nprintln(\"Inferred bias: \", mean_var(result.posteriors[:θ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inferred bias: (0.7406679764243614, 0.00037662534338000586)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can see that the inferred bias is quite close to the actual value we used in the dataset generation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getmarginal(x): for a single random variable x\ngetmarginals(xs): for a dense sequence of random variables sx","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = create_model(coin_toss_model(length(dataset)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# As soon as we have a new value for the marginal posterior over the `θ` variable\n# we simply print the first two statistics of it\nθ_subscription = subscribe!(getmarginal(θ), (marginal) -> println(\"New update: mean(θ) = \", mean(marginal), \", std(θ) = \", std(marginal)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To pass data to our model we use update! function","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"New update: mean(θ) = 0.7406679764243614, std(θ) = 0.01940683754195943","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It is necessary to always unsubscribe from running observables\nunsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them\n# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing\nupdate!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `keep` actor simply keeps all incoming updates in an internal storage, ordered\nθvalues = keep(Marginal)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"KeepActor{Marginal}(Marginal[])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `getmarginal` always emits last cached value as its first value\nsubscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=377.0, β=132.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"2-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=377.0, β=132.0))\n Marginal(Beta{Float64}(α=377.0, β=132.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `buffer` actor keeps very last incoming update in an internal storage and can also store \n# an array of updates for a sequence of random variables\nθbuffer = buffer(Marginal, 1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=377.0, β=132.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=377.0, β=132.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Reactive-Online-Inference","page":"Advanced Tutorial","title":"Reactive Online Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function online_coin_toss_model()\n \n # We create datavars for the prior \n # over `θ` variable\n θ_a = datavar(Float64)\n θ_b = datavar(Float64)\n \n θ ~ Beta(θ_a, θ_b)\n \n y = datavar(Float64)\n y ~ Bernoulli(θ)\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"autoupdates = @autoupdates begin \n θ_a, θ_b = params(q(θ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(θ_a,θ_b = params(q(θ)),)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"rxresult = infer(\n model = online_coin_toss_model(),\n data = (y = dataset, ),\n autoupdates = autoupdates,\n historyvars = (θ = KeepLast(), ),\n keephistory = length(dataset),\n initmarginals = (\n θ = vague(Beta),\n ),\n autostart = true\n);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"animation = @animate for i in 1:length(dataset)\n plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = \"Online coin bias inference\", label = \"Inferred bias\", legend = :bottomright)\n hline!([ p ], label = \"Real bias\", size = (600, 200))\nend\n\ngif(animation, \"../pics/online-coin-bias-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Variational-inference","page":"Advanced Tutorial","title":"Variational inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions q in mathcalQ. Often this involves assuming some factorization over q. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_a for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"There are several options to specify the mean-field factorisation constraint. ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use local structured factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-constraints-macro","page":"Advanced Tutorial","title":"RxInfer.jl constraints macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints6 = @constraints begin\n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: where blocks have higher priority over constraints specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Inference","page":"Advanced Tutorial","title":"Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To run inference in this model we again need to create a synthetic dataset:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#inference-function","page":"Advanced Tutorial","title":"inference function","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Use ?inference to quickly check the documentation for the inference function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"result = infer(\n model = test_model6(length(dataset)),\n data = (y = dataset, ),\n constraints = constraints6, \n initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),\n returnvars = (μ = KeepLast(), τ = KeepLast()),\n iterations = 10,\n free_energy = true,\n showprogress = true\n)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inference results:\n Posteriors | available for (μ, τ)\n Free Energy: | Real[14763.3, 3276.35, 693.1, 656.243, 656.243, 656.24\n3, 656.243, 656.243, 656.243, 656.243]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(result.posteriors[:μ]), \", std = \", std(result.posteriors[:μ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -3.0157043055468535, std = 0.014635651570634027","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(result.posteriors[:τ]), \", std = \", std(result.posteriors[:τ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 4.668474019482058, std = 0.2085720373196144","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Manual-inference","page":"Advanced Tutorial","title":"Manual inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.0217421867709698e-9, w\n=0.010000001002000566))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.644059446887734, w=9.\n17668128961832))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9343.678975344314, w=309\n8.3439261025555))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14071.65054777373, w=466\n6.124108101663))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.760251762773, w=46\n68.481663100324))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.76735083667, w=466\n8.484017130393))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357921546, w=46\n68.484019479642))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357928664, w=46\n68.484019482041))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357928651, w=46\n68.484019482041))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14078.767357928633, w=46\n68.484019482028))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(GammaShapeRate{Float64}(a=501.0, b=5.000000000046544e14))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=54654.4582680546))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=161.69980768671172))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.36985602862222))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.3156347847015))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558067189445))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061788989))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061783582))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061783593))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=107.31558061783606))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(last(μ_values)), \", std = \", std(last(μ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -3.0157043055468535, std = 0.014635651570634027","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(last(τ_values)), \", std = \", std(last(τ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 4.668474019482058, std = 0.2085720373196144","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Form-constraints","page":"Advanced Tutorial","title":"Form constraints","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints7 = @constraints begin \n q(μ) :: PointMass\n \n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_i for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar()\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, PointMass(1.0))\n\nμ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(PointMass{Float64}(-3.0157043119936424))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(GammaShapeRate{Float64}(a=501.0, b=107.20847946934565))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { \n prod_constraint = ProdGeneric(),\n form_constraint = SampleListFormConstraint() \n}","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: @constraints macro specifies required prod_constraint automatically.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Free-Energy","page":"Advanced Tutorial","title":"Free Energy","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_observable = score(model, Float64, BetheFreeEnergy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Float64, ErrorIfProxy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_subscription = subscribe!(bfe_observable, (fe) -> println(\"Current BFE value: \", fe));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Reset the model with vague marginals\nsetmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Current BFE value: 668.7879683577721\nCurrent BFE value: 656.2431248164271\nCurrent BFE value: 656.2431245675102\nCurrent BFE value: 656.2431245675134\nCurrent BFE value: 656.2431245675061\nCurrent BFE value: 656.2431245675098\nCurrent BFE value: 656.2431245675107\nCurrent BFE value: 656.2431245675107\nCurrent BFE value: 656.2431245675107\nCurrent BFE value: 656.2431245675107","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It always necessary to unsubscribe and release computer resources\nunsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Meta-data-specification","page":"Advanced Tutorial","title":"Meta data specification","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of \n# the autoregressive process and its order. In addition it specifies that the message computation rules should\n# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations\n# by cost of possible numerical instabilities during an inference procedure\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }\n...\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` \n# method with `21` sigma points for approximation of non-lineariety between hierarchy layers\nxt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-@meta-macro","page":"Advanced Tutorial","title":"RxInfer.jl @meta macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@meta begin \n AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Meta specification:\n AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Creating-custom-nodes-and-message-computation-rules","page":"Advanced Tutorial","title":"Creating custom nodes and message computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-nodes","page":"Advanced Tutorial","title":"Custom nodes","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification\n@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]\n\n# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error\nstruct NormalMeanVariance end \n\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# It is also possible to use function objects as a node functional form\nfunction dot end\n\n# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them \n# out = dot(x, a)\n@node typeof(dot) Deterministic [ out, x, a ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"After that it is possible to use the newly created node during model specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n ...\n y ~ dot(x, a)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-messages-computation-rules","page":"Advanced Tutorial","title":"Custom messages computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu_z = mu_x + mu_y\nV_z = V_x + V_y\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To specify this in RxInfer.jl we use the @node and @rule macros:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@node typeof(+) Deterministic [ z, x, y ]\n\n@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin\n x_mean, x_var = mean_var(m_x)\n y_mean, y_var = mean_var(m_y)\n return NormalMeanVariance(x_mean + y_mean, x_var + y_var)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(z) = int q(z x y) mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu(z) = int f(x y z)mu(x)mu(y)mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nnu(z) = exp int log f(x y z)q(x)q(y)mathrmdxmathrmdy \nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @rule macro supports both cases with special prefixes during rule specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"m_ prefix corresponds to the incoming message on a specific edge\nq_ prefix corresponds to the posterior marginal of a specific edge","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Sum-Product rule with m_ messages used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin \n m_out_mean, m_out_cov = mean_cov(m_out)\n return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Variational rule with Mean-Field assumption with q_ posteriors used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin \n return NormalMeanPrecision(mean(q_out), mean(q_τ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin\n m, V = mean_cov(q_out_μ)\n θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))\n α = convert(typeof(θ), 1.5)\n return Gamma(α, θ)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference backend expects arguments in `@rule` macro to be in the same order\n@node NormalMeanPrecision Stochastic [ out, μ, τ ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Any rule always has access to the meta information with hidden the meta::Any variable:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin \n ...\n println(meta)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to dispatch on a specific type of a meta object:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"or","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Customizing-messages-computational-pipeline","page":"Advanced Tutorial","title":"Customizing messages computational pipeline","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Logs all outbound messages\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }\n# Initialise messages to be vague\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }\n# In principle, it is possible to approximate outbound messages with Laplace Approximation\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let us return to the coin toss model, but this time we want to print flowing messages:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model_log(n)\n\n y = datavar(Float64, n)\n\n θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage(\"θ\") }\n\n for i in 1:n\n y[i] ~ Bernoulli(θ) where { pipeline = LoggerPipelineStage(\"y[$i]\") }\n end\n \n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"θ_subscription = subscribe!(getmarginal(θ), (value) -> println(\"New posterior marginal for θ: \", value));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[θ][Beta][out]: VariationalMessage()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"coinflips = float.(rand(Bernoulli(0.5), 5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, coinflips)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[y[1]][Bernoulli][p]: VariationalMessage()\n[y[2]][Bernoulli][p]: VariationalMessage()\n[y[3]][Bernoulli][p]: VariationalMessage()\n[y[4]][Bernoulli][p]: VariationalMessage()\n[y[5]][Bernoulli][p]: VariationalMessage()\nNew posterior marginal for θ: Marginal(Beta{Float64}(α=3.0, β=11.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference is lazy and does not send messages if no one is listening for them\nupdate!(y, coinflips)","category":"page"},{"location":"manuals/custom-node/#create-node","page":"Defining a custom node and rules","title":"Creating your own custom nodes","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To create a custom node in RxInfer, 4 steps are required:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Create your custom node in RxInfer using the @node macro.\nDefine the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.\nSpecify computations for marginal distributions of the relevant variables with the @marginalrule macro.\nImplement the computation of the Free Energy in a node with the @average_energy macro.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!","category":"page"},{"location":"manuals/custom-node/#Problem-statement","page":"Defining a custom node and rules","title":"Problem statement","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin K=20 times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment x_kin01 using the Bernoulli distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_k mid pi) = mathrmBer(x_k mid pi) = pi^x_k (1-pi)^1-x_k","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"where pi in01 denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of pi which she models using the Beta distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(pi) = mathrmBeta(pi mid 4 8)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With this prior belief, the total probabilistic model that she has for this experiment is given by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_1K pi) = p(pi) prod_k=1^K p(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of pi, p(pi mid x_1K), denoting how pi is distributed after we have seen the data.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-1:-Creating-the-custom-node","page":"Defining a custom node and rules","title":"Step 1: Creating the custom node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nIn this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"First things first, let's import RxInfer:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using RxInfer","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The name of the node. (::Type)\nWhether the node is Deterministic or Stochastic.\nThe interfaces of the node and any potential aliases. (::Vector)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"# struct for Bernoulli distribution with success probability π\nstruct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution\n π :: T\n new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError(\"π must be between 0 and 1\"))\t\nend\n\n# for simplicity, let's also specify the mean of the distribution\nDistributions.mean(d::MyBernoulli) = d.π\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nYou can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of pi, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Concluding, we can create the MyBernoulli factor node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@node MyBernoulli Stochastic [out, (π, aliases = [p])]","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Cool! Step 1 is done, we have created a custom node.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-2:-Defining-rules-for-our-node","page":"Defining a custom node and rules","title":"Step 2: Defining rules for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as p(pimid x_1K), we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.","category":"page"},{"location":"manuals/custom-node/#Sum-product-message-passing-update-rules","page":"Defining a custom node and rules","title":"Sum-product message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In sum-product message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecmu(x) propto int mathrmBer(xmid pi) vecmu(pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(pi) propto sum_x in 01 mathrmBer(xmid pi) overleftarrowmu(x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain pi = fracalphaalpha + beta, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for \"the incoming message on interface π\". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(π) propto mathrmBeta(1 + x 2 - x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which gives us the following update rule:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin\n p = mean(m_out)\n Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/#Variational-message-passing-update-rules","page":"Defining a custom node and rules","title":"Variational message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecnu(x) propto exp int q(pi) ln mathrmBer(xmid pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrownu(pi) propto exp sum_x in 01 q(x) ln mathrmBer(xmid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"#rules towards out\n@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))\n\n@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin\n rho_1 = mean(log, q_π) # E[ln(x)]\n rho_2 = mean(mirrorlog, q_π) # E[log(1-x)]\n m = max(rho_1, rho_2)\n tmp = exp(rho_1 - m)\n p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))\n return Bernoulli(p)\nend\n\n#rules towards π\n@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin\n p = mean(q_out)\n return Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"node: Node\nTypically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-3:-Defining-joint-marginals-for-our-node","page":"Defining a custom node and rules","title":"Step 3: Defining joint marginals for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Fqf = - sum_ainmathcalV mathrmHq_a(s_a) - sum_ainmathcalVmathrmE_q_a(s_a)ln f_a(s_a) + sum_iinmathcalEmathrmHq_i(s_i)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here we call q_a(s_a) the joint marginals around a node and -mathrmE_q_a(s_a)ln f_a(s_a) we term the average energy.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to be able to compute the Bethe free energy, we need to first describe how to compute q_a(s_a), defined in our case as ","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"q(x_k pi) = vecmu(pi) overleftarrowmu(x_k) mathrmBer(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin\n r = mean(m_out)\n p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)\n return (out = m_out, p = p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as q(x_k pi) = q(x_k)q(pi). These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing q(pi) we need to compute the product vecmu(pi)overleftarrowmu(pi). We already know how overleftarrowmu(pi) looks like from the previous step, so we can just use the prod function.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-4:-Defining-the-average-energy-for-our-node","page":"Defining a custom node and rules","title":"Step 4: Defining the average energy for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as -mathrmE_q(x_k pi)ln p(x_k mid pi), however, because we know that we observe x_k and therefore q(x_k pi) factorizes, we can instead compute beginaligned -mathrmE_q(x_k)q(pi)ln p(x_k mid pi) = -mathrmE_q(x_k)q(pi) ln (pi^x_k (1-pi)^1 - x_k) \n= -mathrmE_q(x_k)q(pi) x_k ln(pi) + (1-x_k) ln(1-pi) \n= -mathrmE_q(x_k)x_k mathrmE_q(pi) ln(pi) - (1-mathrmE_q(x_k)x_k) mathrmE_q(pi)ln(1-pi) endaligned","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to mathrmE_q(x)1-logx.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....","category":"page"},{"location":"manuals/custom-node/#Using-our-node-in-a-model","page":"Defining a custom node and rules","title":"Using our node in a model","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Random\n\nrng = MersenneTwister(42)\nn = 500\nπ_real = 0.75\ndistribution = Bernoulli(π_real)\n\ndataset = float.(rand(rng, distribution, n))\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model_mybernoulli(n)\n\n # `datavar` creates data 'inputs' in our model\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n π ~ Beta(4.0, 8.0)\n\n # We assume that outcome of each coin flip is governed by the MyBernoulli distribution\n for i in 1:n\n y[i] ~ MyBernoulli(π)\n end\n\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Finally, we can run inference with this model and the generated dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"result_mybernoulli = infer(\n model = coin_model_mybernoulli(length(dataset)), \n data = (y = dataset, ),\n)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label=\"p(π|x)\", c=3)\nvline!([π_real], label=\"Real π\")","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model(n)\n \n y = datavar(Float64, n)\n p ~ Beta(4.0, 8.0)\n\n for i in 1:n\n y[i] ~ Bernoulli(p)\n end\n\nend\n\nresult_bernoulli = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, ),\n)\n\nif !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])\n error(\"Results are not identical\")\nelse \n println(\"Results are identical 🎉🎉🎉\")\nend\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#examples-simple-nonlinear-node","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using RxInfer, Random, StableRNGs","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here is an example of creating custom node with nonlinear function approximation with samplelist.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Custom-node-creation","page":"Simple Nonlinear Node","title":"Custom node creation","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"struct NonlinearNode end # Dummy structure just to make Julia happy\n\nstruct NonlinearMeta{R, F}\n rng :: R\n fn :: F # Nonlinear function, we assume 1 float input - 1 float output\n nsamples :: Int # Number of samples used in approximation\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@node NonlinearNode Deterministic [ out, in ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"We need to define two Sum-product message computation rules for our new custom node","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Rule for outbound message on out edge given inbound message on in edge\nRule for outbound message on in edge given inbound message on out edge\nBoth rules accept optional meta object","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `out` edge given inbound message on `in` edge\n@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin \n samples = rand(meta.rng, m_in, meta.nsamples)\n return SampleList(map(meta.fn, samples))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `in` edge given inbound message on `out` edge\n@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin \n return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Model-specification","page":"Simple Nonlinear Node","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"After we have defined our custom node with custom rules we may proceed with a model specification:","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"beginaligned\np(theta) = mathcalN(thetamu_theta sigma_theta)\np(m) = mathcalN(thetamu_m sigma_m)\np(w) = f(theta)\np(y_im w) = mathcalN(y_im w)\nendaligned","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable theta through a non-linear transformation f to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of theta. ","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@model function nonlinear_estimation(n)\n \n θ ~ Normal(mean = 0.0, variance = 100.0)\n m ~ Normal(mean = 0.0, variance = 1.0)\n \n w ~ NonlinearNode(θ)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = m, precision = w)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@constraints function nconstsraints(nsamples)\n q(θ) :: SampleList(nsamples, LeftProposal())\n q(w) :: SampleList(nsamples, RightProposal())\n \n q(θ, w, m) = q(θ)q(m)q(w)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nconstsraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@meta function nmeta(fn, nsamples)\n NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here we generate some data","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn(x) = abs(exp(x) * sin(x))","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"seed = 123\nrng = StableRNG(seed)\n\nniters = 15 # Number of VMP iterations\nnsamples = 5_000 # Number of samples in approximation\n\nn = 500 # Number of IID samples\nμ = -10.0\nθ = -1.0\nw = nonlinear_fn(θ)\n\ndata = rand(rng, NormalMeanPrecision(μ, w), n);","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"result = infer(\n model = nonlinear_estimation(n),\n meta = nmeta(nonlinear_fn, nsamples),\n constraints = nconstsraints(nsamples),\n data = (y = data, ), \n initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),\n returnvars = (θ = KeepLast(), ),\n iterations = niters, \n showprogress = true\n)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"θposterior = result.posteriors[:θ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"SampleList(Univariate, 5000)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using Plots, StatsPlots\n\nestimated = Normal(mean_std(θposterior)...)\n\nplot(estimated, title=\"Posterior for θ\", label = \"Estimated\", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))\nvline!([ θ ], label = \"Real value of θ\")","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"page"},{"location":"library/exported-methods/#lib-using-methods","page":"Exported methods","title":"Using methods from RxInfer","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"A nice explanation about how modules/packages work in Julia can be found in the official documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean as mean_from_rxinfer\nimport Distributions: mean as mean_from_distributions\n\nmean_from_rxinfer === mean_from_distributions","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"# It is easier to let Julia resolve names automatically\n# Julia will not overwrite `mean` that is coming from both packages\nusing RxInfer, Distributions ","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`","category":"page"},{"location":"library/exported-methods/#lib-list-methods","page":"Exported methods","title":"List of available methods","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"note: Note\nSome exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer #hide\nforeach(println, names(RxInfer))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/#examples-nonlinear-sensor-fusion","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"section"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers\nusing DataFrames, DelimitedFiles, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"To illustrate these noisy measurements, the engineers decided to plot them:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# fetch measurements\nbeacon_locations = readdlm(\"../data/sensor_fusion/beacons.txt\")\ndistances = readdlm(\"../data/sensor_fusion/distances.txt\")\nposition = readdlm(\"../data/sensor_fusion/position.txt\")\nnr_observations = size(distances, 1);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual location of WALL-E\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\")\n\n# plot noisy distance measurements\np2 = plot(distances, legend=:topleft, linewidth=3, label=[\"distance to beacon 1\" \"distance to beacon 2\" \"distance to beacon 3\"])\nxlabel!(\"time [sec]\"), ylabel!(\"distance [m]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time t, denoted by z_t, follows a 2-dimensional normal random walk:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(z_t mid z_t - 1) = mathcalN(z_t mid z_t-1mathrmI_2)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"where mathrmI_2 denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements y_t as a noisy set of the distances between WALL-E and the beacons, specified by s_i:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(y_t mid z_t) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixmathrmI_3 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# function to compute distance to beacons\nfunction compute_distances(z) \n distance1 = norm(z - beacon_locations[1,:])\n distance2 = norm(z - beacon_locations[2,:])\n distance3 = norm(z - beacon_locations[3,:])\n distances = [distance1, distance2, distance3]\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model(nr_observations)\n \n # specify precision matrices\n W = diageye(2)\n R = diageye(3)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], W)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":" compute_distances(z) -> CVI(..., Val(false), ...)","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)\n compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"NOTE: You can try out different meta for approximating the nonlinearity, e.g.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_linear_meta()\n compute_distances(z) -> Linearization()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_unscented_meta()\n compute_distances(z) -> Unscented()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_fast = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_accuracy = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1000, 100, StableRNG(42)),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"After running this fast inference procedure, the engineers plot the results and evaluate the performance:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_fast.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Fast (1 sample, 3 iterations)\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot beacon and actual and estimated location of WALL-E (accurate inference)\np2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_accuracy.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Accurate (1000 samples, 100 iterations)\"); p2.series_list[end][:label] = \"estimated location ±2σ\"\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, Q and R respectively. They did this by adding Wishart priors to those matrices:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(Q) = mathcalW(Q mid 3 mathrmI_2) \n p(R) = mathcalW(R mid 4 mathrmI_3) \n p(z_t mid z_t - 1 Q) = mathcalN(z_t mid z_t-1 Q^-1)\n p(y_t mid z_t R) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixR^-1 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model_wishart(nr_observations)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # set priors on precision matrices\n Q ~ Wishart(3, diageye(2))\n R ~ Wishart(4, diageye(3))\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], Q)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"meta = @meta begin \n compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"constraints = @constraints begin\n q(z, Q, R) = q(z)q(Q)q(R)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_wishart = infer(\n model = random_walk_model_wishart(nr_observations),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = constraints,\n meta = meta,\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),\n initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"They plot the new estimates and the performance over time, and luckily WALL-E is found!","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_wishart.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot bethe free energy performance\np2 = plot(results_wishart.free_energy, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"page"},{"location":"examples/problem_specific/overview/#examples-problem_specific-overview","page":"Overview","title":"Problem specific","text":"","category":"section"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Autoregressive Models: An example of Bayesian treatment of latent AR and ARMA models. Reference: Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.\nGamma Mixture Model: This example implements one of the Gamma mixture experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/ .\nGaussian Mixture: This example implements variational Bayesian inference in univariate and multivariate Gaussian mixture models with mean-field assumption.\nHierarchical Gaussian Filter: An example of online inference procedure for Hierarchical Gaussian Filter with univariate noisy observations using Variational Message Passing algorithm. Reference: Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter.\nInvertible neural networks: a tutorial: An example of variational Bayesian Inference with invertible neural networks. Reference: Bart van Erp, Hybrid Inference with Invertible Neural Networks in Factor Graphs.\nProbit Model (EP): In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model.\nRTS vs BIFM Smoothing: This example performs BIFM Kalman smoother on a factor graph using message passing and compares it with the RTS implementation.\nSimple Nonlinear Node: In this example we create a non-conjugate model and use a nonlinear link function between variables. We show how to extend the functionality of RxInfer and to create a custom factor node with arbitrary message passing update rules.\nUniversal Mixtures: Universal mixture modeling.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/#examples-coin-toss-model-(beta-bernoulli)","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"section"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"In this example, we are going to perform an exact inference for a coin toss model that can be represented as:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"beginaligned\np(theta) = mathrmBeta(thetaa b)\np(y_itheta) = mathrmBer(y_itheta)\nendaligned","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"where y_i in 0 1 is a binary observation induced by Bernoulli likelihood while theta is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of theta.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using RxInfer, Random","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"rng = MersenneTwister(42)\nn = 500\nθ_real = 0.75\ndistribution = Bernoulli(θ_real)\n\ndataset = float.(rand(rng, Bernoulli(θ_real), n));","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n θ ~ Beta(4.0, 8.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n\n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, )\n)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Beta{Float64}(α=365.0, β=147.0)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\nplot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\nvline!([θ_real], label=\"Real θ\")","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#examples-invertible-neural-networks:-a-tutorial","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Table of contents","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Introduction\nModel specification\nModel compilation\nProbabilistic inference\nParameter estimation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Introduction","page":"Invertible neural networks: a tutorial","title":"Introduction","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Load-required-packages","page":"Invertible neural networks: a tutorial","title":"Load required packages","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Before we can start, we need to import some packages:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using RxInfer\nusing Random\nusing StableRNGs\n\nusing ReactiveMP # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality\nusing LinearAlgebra # only used for some matrix specifics\nusing Plots # only used for visualisation\nusing Distributions # only used for sampling from multivariate distributions\nusing Optim # only used for parameter optimisation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-specification","page":"Invertible neural networks: a tutorial","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Alternatively, the input_dim can also be passed as an InputLayer layer as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the above AdditiveCouplingLayer layers the input bfx = x_1 x_2 ldots x_N is partitioned into chunks of unit length. These partitions are additively coupled to an output bfy = y_1 y_2 ldots y_N as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n y_1 = x_1 \n y_2 = x_2 + f_1(x_1) \n vdots \n y_N = x_N + f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Importantly, this structure can easily be converted as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n x_1 = y_1 \n x_2 = y_2 - f_1(x_1) \n vdots \n x_N = y_N - f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"f_n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow(); permute=false),\n PermutationLayer(PermutationMatrix(2)),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-compilation","page":"Invertible neural networks: a tutorial","title":"Model compilation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the current models, the layers are setup to work with the passed input dimension. This means that the function f_n is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P\nlanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa\nyerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou\nplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar\nFlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad\nditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive\nMP.PlanarFlowEmpty{1}(),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel - specifies that we are dealing with a flow model.\n3 - Number of layers.\nTuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.\nTuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions f_n.\nPermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(-0.5530639593835304, -0.2163616\n102550308, 1.2521116434309154),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.34763211887023543, -0.9116171319236555, -0.0789378301\n24018),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361\n28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323\n52386),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Probabilistic-inference","page":"Invertible neural networks: a tutorial","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)\n\n rng = StableRNG(seed)\n \n # specify latent sampling distribution\n dist = MvNormal([1.5, 0.5], I)\n\n # sample from the latent distribution\n x = rand(rng, dist, nr_samples)\n\n # transform data\n y = zeros(Float64, size(x))\n for k = 1:nr_samples\n y[:,k] .= ReactiveMP.forward(model, x[:,k])\n end\n\n # return data\n return y, x\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# generate data\ny, x = generate_data(1000, compiled_model)\n\n# plot generated data\np1 = scatter(x[1,:], x[2,:], alpha=0.3, title=\"Original data\", size=(800,400))\np2 = scatter(y[1,:], y[2,:], alpha=0.3, title=\"Transformed data\", size=(800,400))\nplot(p1, p2, legend = false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The probabilistic model for doing inference can be described as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network(nr_samples::Int64)\n \n # initialize variables\n z_μ = randomvar()\n z_Λ = randomvar()\n x = randomvar(nr_samples)\n y_lat = randomvar(nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n\n # specify prior\n z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))\n z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)\n\n # specify transformed latent value\n y_lat[k] ~ Flow(x[k])\n\n # specify observations\n y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))\n\n end\n\n # return variables\n return z_μ, z_Λ, x, y_lat, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here the model is passed inside a meta data object of the flow node. Inference then resorts to","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"observations = [y[:,k] for k=1:size(y,2)]\n\nfmodel = invertible_neural_network(length(observations))\ndata = (y = observations, )\ninitmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))\nreturnvars = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())\n\nconstraints = @constraints begin\n q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)\nend\n\n@meta function fmeta(model)\n compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))\n Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). \n # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))\nend\n\n# First execution is slow due to Julia's initial compilation \nresult = infer(\n model = fmodel, \n data = data,\n constraints = constraints,\n meta = fmeta(model),\n initmarginals = initmarginals,\n returnvars = returnvars,\n free_energy = true,\n iterations = 10, \n showprogress = false\n)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Inference results:\n Posteriors | available for (z_μ, z_Λ, y_lat, x)\n Free Energy: | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357\n0.6, 23570.6, 23570.6, 23570.6, 23570.6]","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fe_flow = result.free_energy\nzμ_flow = result.posteriors[:z_μ]\nzΛ_flow = result.posteriors[:z_Λ]\nx_flow = result.posteriors[:x]\ny_flow = result.posteriors[:y_lat];","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"As we can see, the variational free energy decreases inside of our model.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"plot(1:10, fe_flow/size(y,2), xlabel=\"iteration\", ylabel=\"normalized variational free energy [nats/sample]\", legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"If we plot a random noisy observation and its approximated transformed uncertainty we obtain:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# pick a random observation\nid = rand(StableRNG(321), 1:size(y,2))\nrand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))\nwarped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');\n\np1 = scatter(x[1,:], x[2,:], alpha=0.1, title=\"Latent distribution\", size=(1200,500), label=\"generated data\")\ncontour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)\nscatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color=\"red\", markershape=:x, markersize=5, label=\"inferred mean\")\ncontour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, colorbar=false)\nscatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color=\"red\", label=\"transformed noisy observation\")\np2 = scatter(y[1,:], y[2,:], alpha=0.1, label=\"generated data\")\nscatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color=\"red\", marker=:x, label=\"inferred mean\")\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, label=\"random noisy observation\", colorba=false)\nscatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color=\"red\", label=\"random noisy observation\")\nplot(p1, p2, legend = true)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Parameter-estimation","page":"Invertible neural networks: a tutorial","title":"Parameter estimation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n\n # sample weights\n w = rand(rng, nr_samples, 2)\n\n # sample appraisal\n y = zeros(Float64, nr_samples)\n for k = 1:nr_samples\n y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)\n end\n\n # return data\n return y, w\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"data_y, data_x = generate_data(50);\nscatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel=\"w1\", ylabel=\"w2\", colorbar=false, legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We will then specify a possible model as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# specify flow model\nmodel = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The corresponding probabilistic model for the binary classification task can be created as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network_classifier(nr_samples::Int64)\n \n # initialize variables\n x_lat = randomvar(nr_samples)\n y_lat1 = randomvar(nr_samples)\n y_lat2 = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n x = datavar(Vector{Float64}, nr_samples)\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))\n\n # specify transformed latent value\n y_lat1[k] ~ Flow(x_lat[k])\n y_lat2[k] ~ dot(y_lat1[k], [1, 1])\n\n # specify observations\n y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }\n\n end\n\n # return variables\n return x_lat, x, y_lat1, y_lat2, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fcmodel = invertible_neural_network_classifier(length(data_y))\ndata = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )\n\n@meta function fmeta(model, params)\n compiled_model = compile(model, params)\n Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)\nend","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fmeta (generic function with 2 methods)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function f(params)\n Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure\n result = infer(\n model = fcmodel, \n data = data,\n meta = fmeta(model, params),\n free_energy = true,\n free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure\n iterations = 10, \n showprogress = false\n );\n \n result.free_energy[end]\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"uses finitediff and is slower/less accurate.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"or","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# create gradient function\ng = (x) -> ForwardDiff.gradient(f, x);\n\n# specify initial params\nparams = randn(nr_params(model))\n\n# create custom optimizer (here Adam)\noptimizer = Adam(params; λ=1e-1)\n\n# allocate space for gradient\n∇ = zeros(nr_params(model))\n\n# perform optimization\nfor it = 1:10000\n\n # backward pass\n ∇ .= ForwardDiff.gradient(f, optimizer.x)\n\n # gradient update\n ReactiveMP.update!(optimizer, ∇)\n\nend\n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Iter Function value Gradient norm \n 0 5.888958e+02 8.943663e+02\n * time: 0.015251874923706055\n 100 1.059826e+01 4.120090e+00\n * time: 11.705296039581299\n * Status: success\n\n * Candidate solution\n Final objective value: 1.010332e+01\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.21e-03 ≰ 0.0e+00\n |x - x'|/|x'| = 5.80e-04 ≰ 0.0e+00\n |f(x) - f(x')| = 6.28e-03 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03\n |g(x)| = 2.07e+00 ≰ 1.0e-08\n\n * Work counters\n Seconds run: 13 (vs limit Inf)\n Iterations: 113\n f(x) calls: 301\n ∇f(x) calls: 301","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"optimization results are then given as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"params = Optim.minimizer(res)\ninferred_model = compile(model, params)\ntrans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'\ntrans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])\ntrans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title=\"original data\")\np2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title=\"|> warp\")\np3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title=\"|> dot\")\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using StatsFuns: normcdf\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title=\"original labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title=\"predicted labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title=\"Classification map\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"contributing/new-example/#contributing-new-example","page":"Contributing to the examples","title":"Contributing to the examples","text":"","category":"section"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/\"subcategory\" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"After preparing the new example it is necessary to modify the examples/.meta.jl file.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"Make sure that the very first cell of the notebook contains ONLY # in it and has the markdown cell type. This is important for generating links in our documentation.\nThe path option must be set to a local path in a category sub-folder.\nThe text in the description option will be used on the Examples page in the documentation.\nSet category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).\nPlease do no use Overview as a name for the new example, the title Overview is reserved.\nUse the following template for equations, note that $$ and both \\begin and \\end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"$$\\begin{aligned}\n <latex equations here>\n\\end{aligned}$$","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.\nNotebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"variable = 0\nfor i in 1:10\n global variable = variable + i\nend","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.\nAll plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nPlease avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nUse make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.","category":"page"},{"location":"library/model-specification/#lib-model-specification","page":"Model specification","title":"Model specification in RxInfer","text":"","category":"section"},{"location":"library/model-specification/","page":"Model specification","title":"Model specification","text":"RxInfer.@model\nRxInfer.ModelGenerator\nRxInfer.create_model\nRxInfer.ModelInferenceOptions","category":"page"},{"location":"library/model-specification/#RxInfer.@model","page":"Model specification","title":"RxInfer.@model","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model description\nend\n\n@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.\n\nSupported alias in the model specification\n\na || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).\na && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\na -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\n¬a and !a: alias for NOT(a) node (Unicode \\neg, operator precedence ||, &&, -> and ! is the same as in Julia).\na + b + c: alias for (a + b) + c\na * b * c: alias for (a * b) * c\nNormal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.\nNormal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.\nMvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nGamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.\nGamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.\n\n\n\n\n\n","category":"macro"},{"location":"library/model-specification/#RxInfer.ModelGenerator","page":"Model specification","title":"RxInfer.ModelGenerator","text":"ModelGenerator\n\nModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"library/model-specification/#RxInfer.create_model","page":"Model specification","title":"RxInfer.create_model","text":"create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)\n\nCreates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.\n\nReturns a tuple of 2 values:\n\nan instance of FactorGraphModel\nreturn value from the @model macro function definition\n\n\n\n\n\n","category":"function"},{"location":"library/model-specification/#RxInfer.ModelInferenceOptions","page":"Model specification","title":"RxInfer.ModelInferenceOptions","text":"ModelInferenceOptions(; kwargs...)\n\nCreates model inference options object. The list of available options is present below.\n\nOptions\n\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\nwarn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.\n\nAdvanced options\n\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/getting-started/#user-guide-getting-started","page":"Getting started","title":"Getting started","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.","category":"page"},{"location":"manuals/getting-started/#Installation","page":"Getting started","title":"Installation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Install RxInfer through the Julia package manager:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"] add RxInfer","category":"page"},{"location":"manuals/getting-started/#Importing-RxInfer","page":"Getting started","title":"Importing RxInfer","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"To add RxInfer package (and all associated packages) into a running Julia session simply run:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more about about using in the Using methods from RxInfer section of the documentation.","category":"page"},{"location":"manuals/getting-started/#Example:-Inferring-the-bias-of-a-coin","page":"Getting started","title":"Example: Inferring the bias of a coin","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The RxInfer approach to solving inference problems consists of three phases:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.\nInference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.\nInference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.","category":"page"},{"location":"manuals/getting-started/#Coin-flip-simulation","page":"Getting started","title":"Coin flip simulation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"First let's setup our environment by importing all needed packages:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Next, let's define our dataset:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"rng = MersenneTwister(42)\nn = 10\np = 0.75\ndistribution = Bernoulli(p)\n\ndataset = float.(rand(rng, Bernoulli(p), n))","category":"page"},{"location":"manuals/getting-started/#getting-started-model-specification","page":"Getting started","title":"Model specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In 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.","category":"page"},{"location":"manuals/getting-started/#Likelihood","page":"Getting started","title":"Likelihood","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"y_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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 01.","category":"page"},{"location":"manuals/getting-started/#Prior","page":"Getting started","title":"Prior","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"theta sim Beta(a b)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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. ","category":"page"},{"location":"manuals/getting-started/#Joint-probability","page":"Getting started","title":"Joint probability","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The joint probability is given by the multiplication of the likelihood and the prior, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"P(y_1N θ) = P(θ) prod_i=1^N P(y_i θ)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Now let's see how to specify this model using GraphPPL's package syntax.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"\n# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n \n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during inference step\n return y, θ\nend\n","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create \"clamped\" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG. ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-specification","page":"Getting started","title":"Inference specification","text":"","category":"section"},{"location":"manuals/getting-started/#Automatic-inference-specification","page":"Getting started","title":"Automatic inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Once 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 inference function that supports static datasets.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"result = infer(\n model = coin_model(length(dataset)),\n data = (y = dataset, )\n)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more information about the inference function in the Static Inference documentation section.","category":"page"},{"location":"manuals/getting-started/#Manual-inference-specification","page":"Getting started","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Return variables of interests from model specification\nSubscribe on variables of interests posterior marginal updates\nPass data to the model\nUnsubscribe ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here is an example of inference procedure:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"function custom_inference(data)\n n = length(data)\n\n # `coin_model` function from `@model` macro returns a reference to the model generator object\n # we need to use the `create_model` function to get actual model object\n model, (y, θ) = create_model(coin_model(n))\n \n # Reference for future posterior marginal \n mθ = nothing\n\n # `getmarginal` function returns an observable of future posterior marginal updates\n # We use `Rocket.jl` API to subscribe on this observable\n # As soon as posterior marginal update is available we just save it in `mθ`\n subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)\n \n # `update!` function passes data to our data inputs\n update!(y, data)\n \n # It is always a good practice to unsubscribe and to \n # free computer resources held by the subscription\n unsubscribe!(subscription)\n \n # Here we return our resulting posterior marginal\n return mθ\nend","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-execution","page":"Getting started","title":"Inference execution","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = custom_inference(dataset)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title=\"Prior\", fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\np2 = plot(rθ, (x) -> pdf(θestimated, x), title=\"Posterior\", fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"dataset_100 = float.(rand(rng, Bernoulli(p), 100))\ndataset_1000 = float.(rand(rng, Bernoulli(p), 1000))\ndataset_10000 = float.(rand(rng, Bernoulli(p), 10000))\nnothing # hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated_100 = custom_inference(dataset_100)\nθestimated_1000 = custom_inference(dataset_1000)\nθestimated_10000 = custom_inference(dataset_10000)\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"p3 = plot(title = \"Posterior\", legend = :topleft)\n\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_100)\", c = 4)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_1000)\", c = 5)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_10000)\", c = 6)\n\nplot(p1, p3, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated_10000))\nprintln(\"std: \", std(θestimated_10000))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/#Where-to-go-next?","page":"Getting started","title":"Where to go next?","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.","category":"page"},{"location":"manuals/debugging/#user-guide-debugging","page":"Debugging","title":"Debugging","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want. ","category":"page"},{"location":"manuals/debugging/#Requesting-a-trace-of-messages","page":"Debugging","title":"Requesting a trace of messages","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a \"Memory Addon\". Below is an example explaining how you can extract this history and use it to fix a bug.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Consider the coin toss example from earlier in the documentation. We model the binary outcome x (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the theta parameter, with a known shape 𝑎 and rate 𝑏 parameter.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"x_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"theta sim mathrmBeta(a b)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"where x_i in 0 1 are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"using RxInfer, Random, Plots\n\nn = 4\nθ_real = 0.3\ndataset = convert.(Int64, rand(Bernoulli(θ_real), n))\n\n@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, huge)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);\n","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The model will run without errors. But when we plot the posterior distribution for theta, something's wrong. The posterior seems to be a flat distribution:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"\nrθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n addons = (AddonMemory(),)\n)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now we have access to the messages that led to the marginal posterior:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"underbraceoverrightarrowmu_θ(θ)_substack textoutgoing textmessage = sum_x_1ldotsx_n underbraceoverrightarrowmu_X_1(x_1)cdots overrightarrowmu_X_n(x_n)_substacktextincoming textmessages cdot underbracef(θx_1ldotsx_n)_substacktextnode textfunction","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Graph)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of theta we used in the code block above. So why does the posterior have this rate parameter?","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, 100)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"rθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now the posterior is visible in the plot.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#examples-active-inference-mountain-car","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#The-environmental-process-of-the-mountain","page":"Active Inference Mountain car","title":"The environmental process of the mountain","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Firstly, we specify the environmental process according to Ueltzhoeffer (2017) \"Deep active inference\". This process shows how the environment evolves after interacting with the agent.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Particularly, let's denote z_t = (phi_t dotphi_t) as the environmental state depending on the position phi_t and velocity dotphi_t of the car; a_t as the action of the environment on the car. Then the evolution of the state is described as follows ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndotphi_t = dotphi_t-1 + F_g(phi_t-1) + F_f(dotphi_t-1) + F_a(a_t)\nphi_t = phi_t-1 + dotphi_t \nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where F_g(phi_t-1) is the gravitational force of the hill landscape that depends on the car's position","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_g(phi) = begincases\n -005(2phi + 1) mathrmif phi 0 \n -005 left(1 + 5phi^2)^-frac12 + phi^2 (1 + 5phi^2)^-frac32 + frac116phi^4 right mathrmotherwise\nendcases","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_f(dotphi)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"is the friction on the car defined through the car's velocity F_f(dotphi) = -01 dotphi and F_a(a) is the engine force F_a(a) = 004 tanh(a) Since the car is on low battery, we use the tanh(cdot) function to limit the engine force to the interval [-0.04, 0.04].","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the create_physics function defines forces F_g F_f F_a; and the create_world function defines the environmental process of the mountain.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import HypergeometricFunctions: _₂F₁\n\nfunction create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)\n # Engine force as function of action\n Fa = (a::Real) -> engine_force_limit * tanh(a) \n\n # Friction force as function of velocity\n Ff = (y_dot::Real) -> -friction_coefficient * y_dot \n \n # Gravitational force (horizontal component) as function of position\n Fg = (y::Real) -> begin\n if y < 0\n 0.05*(-2*y - 1)\n else\n 0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)\n end\n end\n \n # The height of the landscape as a function of the horizontal coordinate\n height = (x::Float64) -> begin\n if x < 0\n h = x^2 + x\n else\n h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80\n end\n return 0.05*h\n end\n\n return (Fa, Ff, Fg,height)\nend;\n\nfunction create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)\n\n y_t_min = initial_position\n y_dot_t_min = initial_velocity\n \n y_t = y_t_min\n y_dot_t = y_dot_t_min\n \n execute = (a_t::Float64) -> begin\n # Compute next state\n y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)\n y_t = y_t_min + y_dot_t\n \n # Reset state for next step\n y_t_min = y_t\n y_dot_t_min = y_dot_t\n end\n \n observe = () -> begin \n return [y_t, y_dot_t]\n end\n \n return (execute, observe)\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_world (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Let's visualize the mountain landscape and the situation of the car. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"engine_force_limit = 0.04\nfriction_coefficient = 0.1\n\nFa, Ff, Fg, height = create_physics(\n engine_force_limit = engine_force_limit,\n friction_coefficient = friction_coefficient\n);\ninitial_position = -0.5\ninitial_velocity = 0.0\n\nx_target = [0.5, 0.0] \n\nvalley_x = range(-2, 2, length=400)\nvalley_y = [ height(xs) for xs in valley_x ]\nplot(valley_x, valley_y, title = \"Mountain valley\", label = \"Landscape\", color = \"black\")\nscatter!([ initial_position ], [ height(initial_position) ], label=\"initial car position\") \nscatter!([x_target[1]], [height(x_target[1])], label=\"camping site\")","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Naive-approach","page":"Active Inference Mountain car","title":"Naive approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"N_naive = 100 # Total simulation time\npi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only\n\n# Let there be a world\n(execute_naive, observe_naive) = create_world(; \n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n);\n\ny_naive = Vector{Vector{Float64}}(undef, N_naive)\nfor t = 1:N_naive\n execute_naive(pi_naive[t]) # Execute environmental process\n y_naive[t] = observe_naive() # Observe external states\nend\n\nanimation_naive = @animate for i in 1:N_naive\n plot(valley_x, valley_y, title = \"Naive policy\", label = \"Landscape\", color = \"black\", size = (800, 400))\n scatter!([y_naive[i][1]], [height(y_naive[i][1])], label=\"car\")\n scatter!([x_target[1]], [height(x_target[1])], label=\"goal\") \nend\n\n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_naive, \"../pics/ai-mountain-car-naive.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Active-inference-approach","page":"Active Inference Mountain car","title":"Active inference approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned\np_t(xsu) propto p(s_t-1) prod_k=t^t+T p(x_k mid s_k) p(s_k mid s_k-1u_k) p(u_k) p(x_k) nonumber\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where the factors are defined as","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k) = mathcalN(x_k mid x_goalV_goal) quad (mathrmtarget)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_k mid s_k-1u_k) = mathcalN(s_k mid tildeg(s_k-1)+h(u_k)gamma^-1) quad (mathrmstate transition)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k mid s_k) = mathcalN(x_k mid s_ktheta) quad (mathrmobservation)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(u_k) = mathcalN(u_k mid m_uV_u) quad (mathrmcontrol)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_t-1) = mathcalN(s_t-1 mid m_t-1V_t-1) quad (mathrmprevious state)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"x\ndenotes observations of the agent after interacting with the environment; \ns_t = (s_tdots_t)\nis the state of the car embodying its position and velocity; \nu_t\ndenotes the control state of the agent; \nh(cdot)\nis the tanh(cdot) function modeling engine control; \ntildeg(cdot)\nexecutes a linear approximation of equations (1) and (2): ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndots_t = dots_t-1 + F_g(s_t-1) + F_f(dots_t-1)\ns_t = s_t-1 + dots_t\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)\n \n # Transition function modeling transition due to gravity and friction\n g = (s_t_min::AbstractVector) -> begin \n s_t = similar(s_t_min) # Next state\n s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity\n s_t[1] = s_t_min[1] + s_t[2] # Update position\n return s_t\n end\n \n # Function for modeling engine control\n h = (u::AbstractVector) -> [0.0, Fa(u[1])] \n \n # Inverse engine force, from change in state to corresponding engine force\n h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] \n \n # Internal model perameters\n Gamma = 1e4*diageye(2) # Transition precision\n Theta = 1e-4*diageye(2) # Observation variance\n \n m_s_t_min = datavar(Vector{Float64})\n V_s_t_min = datavar(Matrix{Float64})\n\n s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)\n s_k_min = s_t_min\n \n m_u = datavar(Vector{Float64}, T)\n V_u = datavar(Matrix{Float64}, T)\n \n m_x = datavar(Vector{Float64}, T)\n V_x = datavar(Matrix{Float64}, T)\n \n u = randomvar(T)\n s = randomvar(T)\n x = randomvar(T)\n \n u_h_k = randomvar(T)\n s_g_k = randomvar(T)\n u_s_sum = randomvar(T)\n \n for k in 1:T\n u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])\n u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }\n s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }\n u_s_sum[k] ~ s_g_k[k] + u_h_k[k]\n s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)\n x[k] ~ MvNormal(mean = s[k], cov = Theta)\n x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal\n s_k_min = s[k]\n end\n \n return (s, )\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time t and gets T observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next T time step. \nInfer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state s_t and control u_t, i.e. p(s_tmid x_t) and p(u_tmid x_t).\nSlide: After updating its internal belief, the agent moves to the next time step and uses the inferred action u_t in the previous time step to interact with the environment. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next T positions based on the current action. These two function implement the Act-Execute-Observe phase.\nThe compute function infers the policy (which is a set of actions for the next T time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.\nThe slide function implements the Slide phase, which moves the agent internal model to the next time step.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"# We are going to use some private functionality from ReactiveMP, \n# in the future we should expose a proper API for this\nimport RxInfer.ReactiveMP: getrecent, messageout\n\nfunction create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)\n Epsilon = fill(huge, 1, 1) # Control prior variance\n m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors\n V_u = Matrix{Float64}[ Epsilon for k=1:T ]\n\n Sigma = 1e-4*diageye(2) # Goal prior variance\n m_x = [zeros(2) for k=1:T]\n V_x = [huge*diageye(2) for k=1:T]\n V_x[end] = Sigma # Set prior to reach goal at t=T\n\n # Set initial brain state prior\n m_s_t_min = [initial_position, initial_velocity] \n V_s_t_min = tiny * diageye(2)\n \n # Set current inference results\n result = nothing\n\n # The `infer` function is the heart of the agent\n # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing\n compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin\n m_u[1] = [ upsilon_t ] # Register action with the generative model\n V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action\n\n m_x[1] = y_hat_t # Register observation with the generative model\n V_x[1] = tiny*diageye(2) # Clamp goal prior to observation\n\n data = Dict(:m_u => m_u, \n :V_u => V_u, \n :m_x => m_x, \n :V_x => V_x,\n :m_s_t_min => m_s_t_min,\n :V_s_t_min => V_s_t_min)\n \n model = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) \n result = infer(model = model, data = data)\n end\n \n # The `act` function returns the inferred best possible action\n act = () -> begin\n if result !== nothing\n return mode(result.posteriors[:u][2])[1]\n else\n return 0.0 # Without inference result we return some 'random' action\n end\n end\n \n # The `future` function returns the inferred future states\n future = () -> begin \n if result !== nothing \n return getindex.(mode.(result.posteriors[:s]), 1)\n else\n return zeros(T)\n end\n end\n\n # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step\n # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`\n slide = () -> begin\n (s, ) = result.returnval\n \n slide_msg_idx = 3 # This index is model dependend\n (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))\n\n m_u = circshift(m_u, -1)\n m_u[end] = [0.0]\n V_u = circshift(V_u, -1)\n V_u[end] = Epsilon\n\n m_x = circshift(m_x, -1)\n m_x[end] = x_target\n V_x = circshift(V_x, -1)\n V_x[end] = Sigma\n end\n\n return (compute, act, slide, future) \nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_agent (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now it's time to see if we can help our friends arrive at the camping site by midnight?","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(execute_ai, observe_ai) = create_world(\n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n) # Let there be a world\n\nT_ai = 50\n\n(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent\n T = T_ai, \n Fa = Fa,\n Fg = Fg, \n Ff = Ff, \n engine_force_limit = engine_force_limit,\n x_target = x_target,\n initial_position = initial_position,\n initial_velocity = initial_velocity\n) \n\nN_ai = 100\n\n# Step through experimental protocol\nagent_a = Vector{Float64}(undef, N_ai) # Actions\nagent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future\nagent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations\n\nfor t=1:N_ai\n agent_a[t] = act_ai() # Invoke an action from the agent\n agent_f[t] = future_ai() # Fetch the predicted future states\n execute_ai(agent_a[t]) # The action influences hidden external states\n agent_x[t] = observe_ai() # Observe the current environmental outcome (update p)\n compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)\n slide_ai() # Prepare for next iteration\nend\n\nanimation_ai = @animate for i in 1:N_ai\n # pls - plot landscape\n pls = plot(valley_x, valley_y, title = \"Active inference results\", label = \"Landscape\", color = \"black\")\n pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label=\"car\")\n pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label=\"goal\") \n pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = \"Predicted future\", alpha = map(i -> 0.5 / i, 1:T_ai))\n \n # pef - plot engine force\n pef = plot(Fa.(agent_a[1:i]), title = \"Engine force (agents actions)\", xlim = (0, N_ai), ylim = (-0.05, 0.05))\n \n plot(pls, pef, size = (800, 400))\nend\n \n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_ai, \"../pics/ai-mountain-car-ai.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Voila! The car now is able to reach the camping site with a smart strategy.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now our friends can enjoy their trip at the camping site!. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Reference","page":"Active Inference Mountain car","title":"Reference","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We refer reader to the Thijs van de Laar (2019) \"Simulating active inference processes by message passing\" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) \"Deep active inference\".","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-free-energy","page":"Bethe Free Energy","title":"Bethe Free Energy implementation in RxInfer","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-factorized-model","page":"Bethe Free Energy","title":"Factorized model","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, y = (y_1 dots y_j dots y_m) and variables that can not be observed directly, also known as latent variables, x = (x_1 dots x_i dots x_n) We then define a model that factorizes over consituent smaller factors (functions), as f(yx) = prod_a f_a(y_ax_a)","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-vfe","page":"Bethe Free Energy","title":"Variational Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, Fq(haty) = mathbbE_q(x)leftlog fracq(x)f(y=haty x) right A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-variational-inference","page":"Bethe Free Energy","title":"Variational inference","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The goal of variational inference is to find a variational distibution that minimizes the VFE, q^*(x) = argmin_qinmathcalQ Fq(haty) This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-approximation","page":"Bethe Free Energy","title":"Bethe approximation","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, q(x) triangleq fracprod_a q_a(x_a)prod_i q_i(x_i)^d_i - 1 The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-bfe","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as F_Bq(haty) = sum_a U_aq_a(haty_a) - sum_a Hq_a + sum_i (d_i - 1) Hq_i The first term of the BFE specifies an average energy, U_aq_a(haty_a) = -mathbbE_q_a(x_a)leftlog f_a(y_a=haty_a x_a)right which internalizes the factors of the model. The last two terms specify entropies.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-further-reading","page":"Bethe Free Energy","title":"Further reading","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Pearl (1986) on the original foundations of Bayesian networks and belief propagation;\nYedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;\nDauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);\nSenoz et al. (2021) on constraint manipulation and message passing on FFGs.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"RxInfer.AbstractScoreObjective\nRxInfer.BetheFreeEnergy\nRxInfer.apply_diagnostic_check\nRxInfer.BetheFreeEnergyCheckNaNs\nRxInfer.BetheFreeEnergyCheckInfs","category":"page"},{"location":"library/bethe-free-energy/#RxInfer.AbstractScoreObjective","page":"Bethe Free Energy","title":"RxInfer.AbstractScoreObjective","text":"AbstractScoreObjective\n\nAbstract type for functional objectives that can be used in the score function. \n\nnote: Note\n\n\nscore is defined in the ReactiveMP package.\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergy","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergy","text":"BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)\n\nCreates Bethe Free Energy values stream when passed to the score function. \n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.apply_diagnostic_check","page":"Bethe Free Energy","title":"RxInfer.apply_diagnostic_check","text":"apply_diagnostic_check(check, context, stream)\n\nThis function applies a check to the stream. Accepts optional context object for custom error messages.\n\n\n\n\n\n","category":"function"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckNaNs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckNaNs","text":"BetheFreeEnergyCheckNaNs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return NaNs. Throws an error if finds NaN. \n\nSee also: BetheFreeEnergyCheckInfs\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckInfs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckInfs","text":"BetheFreeEnergyCheckInfs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return Infs. Throws an error if finds Inf. \n\nSee also: BetheFreeEnergyCheckNaNs\n\n\n\n\n\n","category":"type"},{"location":"manuals/background/#intro-background-variational-inference","page":"Background: variational inference","title":"Background: variational inference","text":"","category":"section"}] +} diff --git a/dev/siteinfo.js b/dev/siteinfo.js new file mode 100644 index 000000000..334349194 --- /dev/null +++ b/dev/siteinfo.js @@ -0,0 +1 @@ +var DOCUMENTER_CURRENT_VERSION = "dev"; diff --git a/index.html b/index.html new file mode 100644 index 000000000..6a5afc301 --- /dev/null +++ b/index.html @@ -0,0 +1,2 @@ +<!--This file is automatically generated by Documenter.jl--> +<meta http-equiv="refresh" content="0; url=./stable/"/> diff --git a/stable b/stable new file mode 120000 index 000000000..b71174af3 --- /dev/null +++ b/stable @@ -0,0 +1 @@ +v2.16.2 \ No newline at end of file diff --git a/v2 b/v2 new file mode 120000 index 000000000..b71174af3 --- /dev/null +++ b/v2 @@ -0,0 +1 @@ +v2.16.2 \ No newline at end of file diff --git a/v2.15 b/v2.15 new file mode 120000 index 000000000..39326cb95 --- /dev/null +++ b/v2.15 @@ -0,0 +1 @@ +v2.15.0 \ No newline at end of file diff --git a/v2.15.0/.documenter-siteinfo.json b/v2.15.0/.documenter-siteinfo.json new file mode 100644 index 000000000..e521d1778 --- /dev/null +++ b/v2.15.0/.documenter-siteinfo.json @@ -0,0 +1 @@ +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-29T17:37:09","documenter_version":"1.2.0"}} \ No newline at end of file diff --git a/v2.15.0/assets/biglogo-blacktheme.svg b/v2.15.0/assets/biglogo-blacktheme.svg new file mode 100644 index 000000000..101ebb89d --- /dev/null +++ b/v2.15.0/assets/biglogo-blacktheme.svg @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 27.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) --> +<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" + viewBox="0 0 642.5 213.6" style="enable-background:new 0 0 642.5 213.6;" xml:space="preserve"> +<style type="text/css"> + .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFFFFF;stroke-miterlimit:10;} + .st1{fill:#389826;} + .st2{fill:#9558B2;} + .st3{fill:#FFFFFF;stroke:#FFFFFF;stroke-miterlimit:10;} + .st4{fill:#CB3C33;} + .st5{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFE9E9;stroke-miterlimit:10;} + .st6{fill-rule:evenodd;clip-rule:evenodd;fill:#4063D8;stroke:#FFFFFF;stroke-miterlimit:10;} +</style> +<g id="Слой_2"> + <g id="Layer_1_00000116955105323099935610000000039006590443086520_"> + <path class="st0" d="M66.6,114.5h63c6.7-0.3,12-5.8,12-12.5c0-14.1,0.3-27.6,0.3-41.5c0-6.3,5.1-11.4,11.3-11.4h40.1 + c6.3,0,11.4,5.1,11.4,11.4v40.1c0,6.3-5.1,11.4-11.4,11.4h-35.1c-6.2,0.9-10.8,6.2-10.8,12.4v70.9c0,9.8-8,17.8-17.9,17.8H66.6 + c-9.8,0-17.8-8-17.8-17.8V130c0-6.8-5.5-12.2-12.3-12.2H9.2c-4.8,0-8.7-3.9-8.7-8.7V78.2c0-4.8,3.9-8.7,8.7-8.7h28.7 + c6,0,10.8-4.8,10.8-10.8V13c0-6.9,5.6-12.5,12.5-12.5h44c6.9,0,12.5,5.6,12.5,12.5v44c0,6.9-5.6,12.5-12.5,12.5H59.6 + c-6,0-10.8,4.8-10.8,10.8v22c0,6.7,5.5,12.2,12.2,12.2H66.6z"/> + <rect x="62" y="13.8" class="st1" width="42.3" height="42.3"/> + <rect x="155.2" y="62.4" class="st2" width="36.2" height="36.2"/> + <rect x="13.7" y="82.8" class="st3" width="21.7" height="21.7"/> + <rect x="62" y="127.7" class="st4" width="72" height="72"/> + <path class="st5" d="M213.7,130.1c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.1-9.6,10.4-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.1,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C223.6,131.6,219,130.1,213.7,130.1z"/> + <polygon class="st0" points="281.9,165.8 306.4,130.8 294,130.8 276.2,156.7 260.4,130.8 232.2,130.8 259.8,175.5 234.7,211.6 + 247.2,211.6 265.4,184.8 281.9,211.6 310,211.6 "/> + <polygon class="st0" points="342.1,211.6 342.1,130 315.8,134.3 315.8,211.6 "/> + <path class="st6" d="M329.3,124.6c3.7,0.1,7.2-1.3,9.8-3.9c2.6-2.7,4-6.3,3.9-10.1c0.1-3.7-1.3-7.3-3.9-9.9s-6.1-4.1-9.8-4 + c-3.9-0.1-7.6,1.3-10.4,4c-2.7,2.6-4.2,6.2-4.1,9.9c-0.1,3.8,1.4,7.5,4.1,10.1C321.7,123.3,325.6,124.8,329.3,124.6z"/> + <path class="st0" d="M405.2,129.3c-5.7-0.1-11.3,1.4-16.3,4.1c-4.8,2.5-8.8,6.3-11.7,10.9V130l-26.3,4.3v77.3h26.3v-55.4 + c3.6-8.1,10.4-13.3,17.6-13.3c6.6,0,11.5,5.2,11.5,12.5v56.2h26.3v-55.7c0.2-7.2-2.6-14.1-7.8-19 + C419.6,131.9,413.1,129.4,405.2,129.3z"/> + <path class="st0" d="M479.3,93.6c-9.7,0-17.8,2.8-24.3,8.3s-9.8,12.5-9.8,20.7v8.2h-9.4v8.7h9.4v72.1h26.3v-72.1h16.4v-8.7h-16.4 + v-10.3c-0.2-4.3,1.3-8.5,4.1-11.8c2.7-3.1,6.6-4.9,10.6-5c-1.4,1.9-2.1,4.2-2.1,6.6c0,2.9,1.2,5.7,3.4,7.7 + c2.2,2.1,5.1,3.3,8.1,3.2c2.8,0.1,5.6-1.1,7.6-3.1s3.2-4.8,3.1-7.7c0-4.7-2.6-8.7-7.7-11.9S487,93.6,479.3,93.6z"/> + <path class="st0" d="M527.9,129.4v8.6l0,0V129.4L527.9,129.4z"/> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M527.3,129.3c-11.7,0.2-21.6,4.2-29.7,12c-8.3,7.9-12.6,17.9-12.6,29.8c-0.2,11.4,4.6,22.4,13.2,29.9 + c7.9,7.3,17.9,11.3,29.8,12v-0.1c1.2,0.1,2.5,0.1,3.7,0.1c9.9,0,18.4-2.1,25.4-6.4s10.5-9.5,10.5-15.7c0.1-3-1.1-6-3.2-8.2 + c-2-2.2-4.9-3.3-7.9-3.3c-3.2-0.1-6.2,1.1-8.5,3.3c-2.3,2.1-3.6,5.1-3.6,8.2c-0.1,3.9,1.9,7.6,5.4,9.5c-3.3,1.5-6.9,2.3-10.5,2.2 + c-3.9,0.1-7.8-0.6-11.4-2l0,0c-9.9-3.9-15.2-13.8-16-29.5h55.9c0-12-3.8-22-11.4-29.9c-7.6-8-17.2-11.9-28.8-11.9L527.3,129.3 + M527.9,138c8.5,0.1,14.2,9.1,15.1,24.4h-15.7l0,0h-15.1c0.6-7.3,2.4-13.2,5.3-17.7C520.3,140.5,523.8,138.2,527.9,138L527.9,138" + /> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M623.6,129.4c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.2-9.6,10.3-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.2,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C633.4,130.9,629,129.4,623.6,129.4z"/> + </g> +</g> +<g id="Layer_2_00000036966862148631286250000015780344526604021166_"> +</g> +</svg> diff --git a/v2.15.0/assets/biglogo.svg b/v2.15.0/assets/biglogo.svg new file mode 100644 index 000000000..b9f3d9f8e --- /dev/null +++ b/v2.15.0/assets/biglogo.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 641.51 212.57"><defs><style>.cls-1{fill:#333;}.cls-1,.cls-6{fill-rule:evenodd;}.cls-2{fill:#389826;}.cls-3{fill:#9558b2;}.cls-4{fill:#fff;}.cls-5{fill:#cb3c33;}.cls-6{fill:#4063d8;}</style></defs><title>1 \ No newline at end of file diff --git a/v2.15.0/assets/documenter.js b/v2.15.0/assets/documenter.js new file mode 100644 index 000000000..f5311607b --- /dev/null +++ b/v2.15.0/assets/documenter.js @@ -0,0 +1,889 @@ +// Generated by Documenter.jl +requirejs.config({ + paths: { + 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', + 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', + 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', + 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', + 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', + 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', + 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', + 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min', + 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min', + 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia-repl.min', + }, + shim: { + "highlight-julia": { + "deps": [ + "highlight" + ] + }, + "katex-auto-render": { + "deps": [ + "katex" + ] + }, + "headroom-jquery": { + "deps": [ + "jquery", + "headroom" + ] + }, + "highlight-julia-repl": { + "deps": [ + "highlight" + ] + } +} +}); +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'katex', 'katex-auto-render'], function($, katex, renderMathInElement) { +$(document).ready(function() { + renderMathInElement( + document.body, + { + "delimiters": [ + { + "left": "$", + "right": "$", + "display": false + }, + { + "left": "$$", + "right": "$$", + "display": true + }, + { + "left": "\\[", + "right": "\\]", + "display": true + } + ] +} + + ); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'highlight', 'highlight-julia', 'highlight-julia-repl'], function($) { +$(document).ready(function() { + hljs.highlightAll(); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let timer = 0; +var isExpanded = true; + +$(document).on("click", ".docstring header", function () { + let articleToggleTitle = "Expand docstring"; + + debounce(() => { + if ($(this).siblings("section").is(":visible")) { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + } else { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + articleToggleTitle = "Collapse docstring"; + } + + $(this) + .find(".docstring-article-toggle-button") + .prop("title", articleToggleTitle); + $(this).siblings("section").slideToggle(); + }); +}); + +$(document).on("click", ".docs-article-toggle-button", function () { + let articleToggleTitle = "Expand docstring"; + let navArticleToggleTitle = "Expand all docstrings"; + + debounce(() => { + if (isExpanded) { + $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + + isExpanded = false; + + $(".docstring section").slideUp(); + } else { + $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + isExpanded = true; + articleToggleTitle = "Collapse docstring"; + navArticleToggleTitle = "Collapse all docstrings"; + + $(".docstring section").slideDown(); + } + + $(this).prop("title", navArticleToggleTitle); + $(".docstring-article-toggle-button").prop("title", articleToggleTitle); + }); +}); + +function debounce(callback, timeout = 300) { + if (Date.now() - timer > timeout) { + callback(); + } + + clearTimeout(timer); + + timer = Date.now(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require([], function() { +function addCopyButtonCallbacks() { + for (const el of document.getElementsByTagName("pre")) { + const button = document.createElement("button"); + button.classList.add("copy-button", "fa-solid", "fa-copy"); + button.setAttribute("aria-label", "Copy this code block"); + button.setAttribute("title", "Copy"); + + el.appendChild(button); + + const success = function () { + button.classList.add("success", "fa-check"); + button.classList.remove("fa-copy"); + }; + + const failure = function () { + button.classList.add("error", "fa-xmark"); + button.classList.remove("fa-copy"); + }; + + button.addEventListener("click", function () { + copyToClipboard(el.innerText).then(success, failure); + + setTimeout(function () { + button.classList.add("fa-copy"); + button.classList.remove("success", "fa-check", "fa-xmark"); + }, 5000); + }); + } +} + +function copyToClipboard(text) { + // clipboard API is only available in secure contexts + if (window.navigator && window.navigator.clipboard) { + return window.navigator.clipboard.writeText(text); + } else { + return new Promise(function (resolve, reject) { + try { + const el = document.createElement("textarea"); + el.textContent = text; + el.style.position = "fixed"; + el.style.opacity = 0; + document.body.appendChild(el); + el.select(); + document.execCommand("copy"); + + resolve(); + } catch (err) { + reject(err); + } finally { + document.body.removeChild(el); + } + }); + } +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addCopyButtonCallbacks); +} else { + addCopyButtonCallbacks(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'headroom', 'headroom-jquery'], function($, Headroom) { + +// Manages the top navigation bar (hides it when the user starts scrolling down on the +// mobile). +window.Headroom = Headroom; // work around buggy module loading? +$(document).ready(function () { + $("#documenter .docs-navbar").headroom({ + tolerance: { up: 10, down: 10 }, + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'minisearch'], function($, minisearch) { + +// In general, most search related things will have "search" as a prefix. +// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +let results = []; +let timer = undefined; + +let data = documenterSearchIndex["docs"].map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; +}); + +// list below is the lunr 2.1.3 list minus the intersect with names(Base) +// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) +// ideally we'd just filter the original list but it's not available as a variable +const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", +]); + +let index = new minisearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification + tokenize: (string) => string.split(/[\s\-\.]+/), + // options which will be applied during the search + searchOptions: { + boost: { title: 100 }, + fuzzy: 2, + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + tokenize: (string) => string.split(/[\s\-\.]+/), + }, +}); + +index.addAll(data); + +let filters = [...new Set(data.map((x) => x.category))]; +var modal_filters = make_modal_body_filters(filters); +var filter_results = []; + +$(document).on("keyup", ".documenter-search-input", function (event) { + // Adding a debounce to prevent disruptions from super-speed typing! + debounce(() => update_search(filter_results), 300); +}); + +$(document).on("click", ".search-filter", function () { + if ($(this).hasClass("search-filter-selected")) { + $(this).removeClass("search-filter-selected"); + } else { + $(this).addClass("search-filter-selected"); + } + + // Adding a debounce to prevent disruptions from crazy clicking! + debounce(() => get_filters(), 300); +}); + +/** + * A debounce function, takes a function and an optional timeout in milliseconds + * + * @function callback + * @param {number} timeout + */ +function debounce(callback, timeout = 300) { + clearTimeout(timer); + timer = setTimeout(callback, timeout); +} + +/** + * Make/Update the search component + * + * @param {string[]} selected_filters + */ +function update_search(selected_filters = []) { + let initial_search_body = ` +
Type something to get started!
+ `; + + let querystring = $(".documenter-search-input").val(); + + if (querystring.trim()) { + results = index.search(querystring, { + filter: (result) => { + // Filtering results + if (selected_filters.length === 0) { + return result.score >= 1; + } else { + return ( + result.score >= 1 && selected_filters.includes(result.category) + ); + } + }, + }); + + let search_result_container = ``; + let search_divider = `
`; + + if (results.length) { + let links = []; + let count = 0; + let search_results = ""; + + results.forEach(function (result) { + if (result.location) { + // Checking for duplication of results for the same page + if (!links.includes(result.location)) { + search_results += make_search_result(result, querystring); + count++; + } + + links.push(result.location); + } + }); + + let result_count = `
${count} result(s)
`; + + search_result_container = ` +
+ ${modal_filters} + ${search_divider} + ${result_count} +
+ ${search_results} +
+
+ `; + } else { + search_result_container = ` +
+ ${modal_filters} + ${search_divider} +
0 result(s)
+
+
No result found!
+ `; + } + + if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").removeClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(search_result_container); + } else { + filter_results = []; + modal_filters = make_modal_body_filters(filters, filter_results); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(initial_search_body); + } +} + +/** + * Make the modal filter html + * + * @param {string[]} filters + * @param {string[]} selected_filters + * @returns string + */ +function make_modal_body_filters(filters, selected_filters = []) { + let str = ``; + + filters.forEach((val) => { + if (selected_filters.includes(val)) { + str += `${val}`; + } else { + str += `${val}`; + } + }); + + let filter_html = ` +
+ Filters: + ${str} +
+ `; + + return filter_html; +} + +/** + * Make the result component given a minisearch result data object and the value of the search input as queryString. + * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ +function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } + + let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${result.title}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; +} + +/** + * Get selected filters, remake the filter html and lastly update the search modal + */ +function get_filters() { + let ele = $(".search-filters .search-filter-selected").get(); + filter_results = ele.map((x) => $(x).text().toLowerCase()); + modal_filters = make_modal_body_filters(filters, filter_results); + update_search(filter_results); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Modal settings dialog +$(document).ready(function () { + var settings = $("#documenter-settings"); + $("#documenter-settings-button").click(function () { + settings.toggleClass("is-active"); + }); + // Close the dialog if X is clicked + $("#documenter-settings button.delete").click(function () { + settings.removeClass("is-active"); + }); + // Close dialog if ESC is pressed + $(document).keyup(function (e) { + if (e.keyCode == 27) settings.removeClass("is-active"); + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let search_modal_header = ` +
+
+

+ + + + +

+
+
+ +
+
+`; + +let initial_search_body = ` +
Type something to get started!
+`; + +let search_modal_footer = ` +
+ + Ctrl + + / to search + + esc to close +
+`; + +$(document.body).append( + ` + + ` +); + +document.querySelector(".docs-search-query").addEventListener("click", () => { + openModal(); +}); + +document.querySelector(".close-search-modal").addEventListener("click", () => { + closeModal(); +}); + +$(document).on("click", ".search-result-link", function () { + closeModal(); +}); + +document.addEventListener("keydown", (event) => { + if ((event.ctrlKey || event.metaKey) && event.key === "/") { + openModal(); + } else if (event.key === "Escape") { + closeModal(); + } + + return false; +}); + +// Functions to open and close a modal +function openModal() { + let searchModal = document.querySelector("#search-modal"); + + searchModal.classList.add("is-active"); + document.querySelector(".documenter-search-input").focus(); +} + +function closeModal() { + let searchModal = document.querySelector("#search-modal"); + let initial_search_body = ` +
Type something to get started!
+ `; + + searchModal.classList.remove("is-active"); + document.querySelector(".documenter-search-input").blur(); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".documenter-search-input").val(""); + $(".search-modal-card-body").html(initial_search_body); +} + +document + .querySelector("#search-modal .modal-background") + .addEventListener("click", () => { + closeModal(); + }); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Manages the showing and hiding of the sidebar. +$(document).ready(function () { + var sidebar = $("#documenter > .docs-sidebar"); + var sidebar_button = $("#documenter-sidebar-button"); + sidebar_button.click(function (ev) { + ev.preventDefault(); + sidebar.toggleClass("visible"); + if (sidebar.hasClass("visible")) { + // Makes sure that the current menu item is visible in the sidebar. + $("#documenter .docs-menu a.is-active").focus(); + } + }); + $("#documenter > .docs-main").bind("click", function (ev) { + if ($(ev.target).is(sidebar_button)) { + return; + } + if (sidebar.hasClass("visible")) { + sidebar.removeClass("visible"); + } + }); +}); + +// Resizes the package name / sitename in the sidebar if it is too wide. +// Inspired by: https://github.com/davatron5000/FitText.js +$(document).ready(function () { + e = $("#documenter .docs-autofit"); + function resize() { + var L = parseInt(e.css("max-width"), 10); + var L0 = e.width(); + if (L0 > L) { + var h0 = parseInt(e.css("font-size"), 10); + e.css("font-size", (L * h0) / L0); + // TODO: make sure it survives resizes? + } + } + // call once and then register events + resize(); + $(window).resize(resize); + $(window).on("orientationchange", resize); +}); + +// Scroll the navigation bar to the currently selected menu item +$(document).ready(function () { + var sidebar = $("#documenter .docs-menu").get(0); + var active = $("#documenter .docs-menu .is-active").get(0); + if (typeof active !== "undefined") { + sidebar.scrollTop = active.offsetTop - sidebar.offsetTop - 15; + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Theme picker setup +$(document).ready(function () { + // onchange callback + $("#documenter-themepicker").change(function themepick_callback(ev) { + var themename = $("#documenter-themepicker option:selected").attr("value"); + if (themename === "auto") { + // set_theme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'); + window.localStorage.removeItem("documenter-theme"); + } else { + // set_theme(themename); + window.localStorage.setItem("documenter-theme", themename); + } + // We re-use the global function from themeswap.js to actually do the swapping. + set_theme_from_local_storage(); + }); + + // Make sure that the themepicker displays the correct theme when the theme is retrieved + // from localStorage + if (typeof window.localStorage !== "undefined") { + var theme = window.localStorage.getItem("documenter-theme"); + if (theme !== null) { + $("#documenter-themepicker option").each(function (i, e) { + e.selected = e.value === theme; + }); + } + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// update the version selector with info from the siteinfo.js and ../versions.js files +$(document).ready(function () { + // If the version selector is disabled with DOCUMENTER_VERSION_SELECTOR_DISABLED in the + // siteinfo.js file, we just return immediately and not display the version selector. + if ( + typeof DOCUMENTER_VERSION_SELECTOR_DISABLED === "boolean" && + DOCUMENTER_VERSION_SELECTOR_DISABLED + ) { + return; + } + + var version_selector = $("#documenter .docs-version-selector"); + var version_selector_select = $("#documenter .docs-version-selector select"); + + version_selector_select.change(function (x) { + target_href = version_selector_select + .children("option:selected") + .get(0).value; + window.location.href = target_href; + }); + + // add the current version to the selector based on siteinfo.js, but only if the selector is empty + if ( + typeof DOCUMENTER_CURRENT_VERSION !== "undefined" && + $("#version-selector > option").length == 0 + ) { + var option = $( + "" + ); + version_selector_select.append(option); + } + + if (typeof DOC_VERSIONS !== "undefined") { + var existing_versions = version_selector_select.children("option"); + var existing_versions_texts = existing_versions.map(function (i, x) { + return x.text; + }); + DOC_VERSIONS.forEach(function (each) { + var version_url = documenterBaseURL + "/../" + each + "/"; + var existing_id = $.inArray(each, existing_versions_texts); + // if not already in the version selector, add it as a new option, + // otherwise update the old option with the URL and enable it + if (existing_id == -1) { + var option = $( + "" + ); + version_selector_select.append(option); + } else { + var option = existing_versions[existing_id]; + option.value = version_url; + option.disabled = false; + } + }); + } + + // only show the version selector if the selector has been populated + if (version_selector_select.children("option").length > 0) { + version_selector.toggleClass("visible"); + } +}); + +}) diff --git a/v2.15.0/assets/examples/Active Inference Mountain car_4_1.png b/v2.15.0/assets/examples/Active Inference Mountain car_4_1.png new file mode 100644 index 000000000..9394d1730 Binary files /dev/null and b/v2.15.0/assets/examples/Active Inference Mountain car_4_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_12_1.png b/v2.15.0/assets/examples/Autoregressive Models_12_1.png new file mode 100644 index 000000000..34bcb79e9 Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_12_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_13_1.png b/v2.15.0/assets/examples/Autoregressive Models_13_1.png new file mode 100644 index 000000000..8ba298281 Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_13_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_14_1.png b/v2.15.0/assets/examples/Autoregressive Models_14_1.png new file mode 100644 index 000000000..dfff657eb Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_14_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_24_1.png b/v2.15.0/assets/examples/Autoregressive Models_24_1.png new file mode 100644 index 000000000..92d942e95 Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_24_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_32_1.png b/v2.15.0/assets/examples/Autoregressive Models_32_1.png new file mode 100644 index 000000000..9b30d0046 Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_32_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_36_1.png b/v2.15.0/assets/examples/Autoregressive Models_36_1.png new file mode 100644 index 000000000..047100331 Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_36_1.png differ diff --git a/v2.15.0/assets/examples/Autoregressive Models_6_1.png b/v2.15.0/assets/examples/Autoregressive Models_6_1.png new file mode 100644 index 000000000..309eadff5 Binary files /dev/null and b/v2.15.0/assets/examples/Autoregressive Models_6_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_10_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_10_1.png new file mode 100644 index 000000000..4ecb12eef Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_10_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_12_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_12_1.png new file mode 100644 index 000000000..21f2cf9b8 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_12_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_14_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_14_1.png new file mode 100644 index 000000000..d35fb5850 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_14_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_15_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_15_1.png new file mode 100644 index 000000000..8068d76e2 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_15_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_16_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_16_1.png new file mode 100644 index 000000000..2dd3fcb12 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_16_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_17_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_17_1.png new file mode 100644 index 000000000..ddcc56f62 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_17_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_18_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_18_1.png new file mode 100644 index 000000000..6ac6db454 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_18_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_21_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_21_1.png new file mode 100644 index 000000000..157bce417 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_21_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_24_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_24_1.png new file mode 100644 index 000000000..8dbb0d22f Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_24_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_25_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_25_1.png new file mode 100644 index 000000000..da8387995 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_25_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_26_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_26_1.png new file mode 100644 index 000000000..0b3299f1c Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_26_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_27_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_27_1.png new file mode 100644 index 000000000..dc2785db5 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_27_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_34_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_34_1.png new file mode 100644 index 000000000..e935ce86c Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_34_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_40_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_40_1.png new file mode 100644 index 000000000..a7f23a09f Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_40_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_42_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_42_1.png new file mode 100644 index 000000000..5057af239 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_42_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_4_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_4_1.png new file mode 100644 index 000000000..3851d2ea5 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_4_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_51_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_51_1.png new file mode 100644 index 000000000..df1ae996a Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_51_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_54_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_54_1.png new file mode 100644 index 000000000..af1f62c28 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_54_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_55_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_55_1.png new file mode 100644 index 000000000..6e7a17a0c Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_55_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_7_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_7_1.png new file mode 100644 index 000000000..564b04161 Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_7_1.png differ diff --git a/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_8_1.png b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_8_1.png new file mode 100644 index 000000000..b86dc84cd Binary files /dev/null and b/v2.15.0/assets/examples/Bayesian Linear Regression Tutorial_8_1.png differ diff --git a/v2.15.0/assets/examples/Chance Constraints_11_1.png b/v2.15.0/assets/examples/Chance Constraints_11_1.png new file mode 100644 index 000000000..b7b9be536 Binary files /dev/null and b/v2.15.0/assets/examples/Chance Constraints_11_1.png differ diff --git a/v2.15.0/assets/examples/Coin Toss Model_7_1.png b/v2.15.0/assets/examples/Coin Toss Model_7_1.png new file mode 100644 index 000000000..180821d61 Binary files /dev/null and b/v2.15.0/assets/examples/Coin Toss Model_7_1.png differ diff --git a/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png b/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png new file mode 100644 index 000000000..d90df26c0 Binary files /dev/null and b/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png differ diff --git a/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png b/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png new file mode 100644 index 000000000..14f524963 Binary files /dev/null and b/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png differ diff --git a/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png b/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png new file mode 100644 index 000000000..2e19804fb Binary files /dev/null and b/v2.15.0/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png differ diff --git a/v2.15.0/assets/examples/GP Regression by SSM_10_1.png b/v2.15.0/assets/examples/GP Regression by SSM_10_1.png new file mode 100644 index 000000000..2eb40cb1d Binary files /dev/null and b/v2.15.0/assets/examples/GP Regression by SSM_10_1.png differ diff --git a/v2.15.0/assets/examples/GP Regression by SSM_5_1.png b/v2.15.0/assets/examples/GP Regression by SSM_5_1.png new file mode 100644 index 000000000..3246e6256 Binary files /dev/null and b/v2.15.0/assets/examples/GP Regression by SSM_5_1.png differ diff --git a/v2.15.0/assets/examples/Gamma Mixture_10_1.png b/v2.15.0/assets/examples/Gamma Mixture_10_1.png new file mode 100644 index 000000000..490a74e2e Binary files /dev/null and b/v2.15.0/assets/examples/Gamma Mixture_10_1.png differ diff --git a/v2.15.0/assets/examples/Gaussian Mixture_12_1.png b/v2.15.0/assets/examples/Gaussian Mixture_12_1.png new file mode 100644 index 000000000..fc21b9942 Binary files /dev/null and b/v2.15.0/assets/examples/Gaussian Mixture_12_1.png differ diff --git a/v2.15.0/assets/examples/Gaussian Mixture_4_1.png b/v2.15.0/assets/examples/Gaussian Mixture_4_1.png new file mode 100644 index 000000000..aedf37236 Binary files /dev/null and b/v2.15.0/assets/examples/Gaussian Mixture_4_1.png differ diff --git a/v2.15.0/assets/examples/Gaussian Mixture_7_1.png b/v2.15.0/assets/examples/Gaussian Mixture_7_1.png new file mode 100644 index 000000000..338fe2092 Binary files /dev/null and b/v2.15.0/assets/examples/Gaussian Mixture_7_1.png differ diff --git a/v2.15.0/assets/examples/Gaussian Mixture_9_1.png b/v2.15.0/assets/examples/Gaussian Mixture_9_1.png new file mode 100644 index 000000000..64adeef14 Binary files /dev/null and b/v2.15.0/assets/examples/Gaussian Mixture_9_1.png differ diff --git a/v2.15.0/assets/examples/Global Parameter Optimisation_14_1.png b/v2.15.0/assets/examples/Global Parameter Optimisation_14_1.png new file mode 100644 index 000000000..70f61d1cf Binary files /dev/null and b/v2.15.0/assets/examples/Global Parameter Optimisation_14_1.png differ diff --git a/v2.15.0/assets/examples/Global Parameter Optimisation_18_1.png b/v2.15.0/assets/examples/Global Parameter Optimisation_18_1.png new file mode 100644 index 000000000..eac50a682 Binary files /dev/null and b/v2.15.0/assets/examples/Global Parameter Optimisation_18_1.png differ diff --git a/v2.15.0/assets/examples/Global Parameter Optimisation_22_1.png b/v2.15.0/assets/examples/Global Parameter Optimisation_22_1.png new file mode 100644 index 000000000..c24630442 Binary files /dev/null and b/v2.15.0/assets/examples/Global Parameter Optimisation_22_1.png differ diff --git a/v2.15.0/assets/examples/Global Parameter Optimisation_28_1.png b/v2.15.0/assets/examples/Global Parameter Optimisation_28_1.png new file mode 100644 index 000000000..e78ac6eee Binary files /dev/null and b/v2.15.0/assets/examples/Global Parameter Optimisation_28_1.png differ diff --git a/v2.15.0/assets/examples/Global Parameter Optimisation_32_1.png b/v2.15.0/assets/examples/Global Parameter Optimisation_32_1.png new file mode 100644 index 000000000..cf55c8da0 Binary files /dev/null and b/v2.15.0/assets/examples/Global Parameter Optimisation_32_1.png differ diff --git a/v2.15.0/assets/examples/Global Parameter Optimisation_35_1.png b/v2.15.0/assets/examples/Global Parameter Optimisation_35_1.png new file mode 100644 index 000000000..fddb20942 Binary files /dev/null and b/v2.15.0/assets/examples/Global Parameter Optimisation_35_1.png differ diff --git a/v2.15.0/assets/examples/Hidden Markov Model_4_1.png b/v2.15.0/assets/examples/Hidden Markov Model_4_1.png new file mode 100644 index 000000000..a15a96215 Binary files /dev/null and b/v2.15.0/assets/examples/Hidden Markov Model_4_1.png differ diff --git a/v2.15.0/assets/examples/Hidden Markov Model_9_1.png b/v2.15.0/assets/examples/Hidden Markov Model_9_1.png new file mode 100644 index 000000000..32d9bbc46 Binary files /dev/null and b/v2.15.0/assets/examples/Hidden Markov Model_9_1.png differ diff --git a/v2.15.0/assets/examples/Hierarchical Gaussian Filter_10_1.png b/v2.15.0/assets/examples/Hierarchical Gaussian Filter_10_1.png new file mode 100644 index 000000000..6a3b9c9dc Binary files /dev/null and b/v2.15.0/assets/examples/Hierarchical Gaussian Filter_10_1.png differ diff --git a/v2.15.0/assets/examples/Hierarchical Gaussian Filter_5_1.png b/v2.15.0/assets/examples/Hierarchical Gaussian Filter_5_1.png new file mode 100644 index 000000000..2d74bff5a Binary files /dev/null and b/v2.15.0/assets/examples/Hierarchical Gaussian Filter_5_1.png differ diff --git a/v2.15.0/assets/examples/Hierarchical Gaussian Filter_9_1.png b/v2.15.0/assets/examples/Hierarchical Gaussian Filter_9_1.png new file mode 100644 index 000000000..9821f6bc9 Binary files /dev/null and b/v2.15.0/assets/examples/Hierarchical Gaussian Filter_9_1.png differ diff --git a/v2.15.0/assets/examples/Infinite Data Stream_11_1.png b/v2.15.0/assets/examples/Infinite Data Stream_11_1.png new file mode 100644 index 000000000..c0bbb671c Binary files /dev/null and b/v2.15.0/assets/examples/Infinite Data Stream_11_1.png differ diff --git a/v2.15.0/assets/examples/Invertible Neural Network Tutorial_10_1.png b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_10_1.png new file mode 100644 index 000000000..009e76bec Binary files /dev/null and b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_10_1.png differ diff --git a/v2.15.0/assets/examples/Invertible Neural Network Tutorial_14_1.png b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_14_1.png new file mode 100644 index 000000000..95edfacc0 Binary files /dev/null and b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_14_1.png differ diff --git a/v2.15.0/assets/examples/Invertible Neural Network Tutorial_15_1.png b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_15_1.png new file mode 100644 index 000000000..ab077a912 Binary files /dev/null and b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_15_1.png differ diff --git a/v2.15.0/assets/examples/Invertible Neural Network Tutorial_17_1.png b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_17_1.png new file mode 100644 index 000000000..201b882c0 Binary files /dev/null and b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_17_1.png differ diff --git a/v2.15.0/assets/examples/Invertible Neural Network Tutorial_23_1.png b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_23_1.png new file mode 100644 index 000000000..a639d283d Binary files /dev/null and b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_23_1.png differ diff --git a/v2.15.0/assets/examples/Invertible Neural Network Tutorial_24_1.png b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_24_1.png new file mode 100644 index 000000000..b38e5ab4e Binary files /dev/null and b/v2.15.0/assets/examples/Invertible Neural Network Tutorial_24_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_10_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_10_1.png new file mode 100644 index 000000000..404cd2073 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_10_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_15_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_15_1.png new file mode 100644 index 000000000..387f83e00 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_15_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_20_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_20_1.png new file mode 100644 index 000000000..0332168c8 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_20_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_23_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_23_1.png new file mode 100644 index 000000000..3997d6305 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_23_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_25_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_25_1.png new file mode 100644 index 000000000..baae896e0 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_25_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_30_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_30_1.png new file mode 100644 index 000000000..0ca63d89e Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_30_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_33_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_33_1.png new file mode 100644 index 000000000..230f9e497 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_33_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_39_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_39_1.png new file mode 100644 index 000000000..8f7baa554 Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_39_1.png differ diff --git a/v2.15.0/assets/examples/Kalman filtering and smoothing_6_1.png b/v2.15.0/assets/examples/Kalman filtering and smoothing_6_1.png new file mode 100644 index 000000000..868c31a7a Binary files /dev/null and b/v2.15.0/assets/examples/Kalman filtering and smoothing_6_1.png differ diff --git a/v2.15.0/assets/examples/Nonlinear Sensor Fusion_12_1.png b/v2.15.0/assets/examples/Nonlinear Sensor Fusion_12_1.png new file mode 100644 index 000000000..40646c539 Binary files /dev/null and b/v2.15.0/assets/examples/Nonlinear Sensor Fusion_12_1.png differ diff --git a/v2.15.0/assets/examples/Nonlinear Sensor Fusion_17_1.png b/v2.15.0/assets/examples/Nonlinear Sensor Fusion_17_1.png new file mode 100644 index 000000000..2a2429a35 Binary files /dev/null and b/v2.15.0/assets/examples/Nonlinear Sensor Fusion_17_1.png differ diff --git a/v2.15.0/assets/examples/Nonlinear Sensor Fusion_4_1.png b/v2.15.0/assets/examples/Nonlinear Sensor Fusion_4_1.png new file mode 100644 index 000000000..6be9531bf Binary files /dev/null and b/v2.15.0/assets/examples/Nonlinear Sensor Fusion_4_1.png differ diff --git a/v2.15.0/assets/examples/Predicting Bike Rental Demand_17_1.png b/v2.15.0/assets/examples/Predicting Bike Rental Demand_17_1.png new file mode 100644 index 000000000..49ebabbfb Binary files /dev/null and b/v2.15.0/assets/examples/Predicting Bike Rental Demand_17_1.png differ diff --git a/v2.15.0/assets/examples/Predicting Bike Rental Demand_18_1.png b/v2.15.0/assets/examples/Predicting Bike Rental Demand_18_1.png new file mode 100644 index 000000000..76c1cb40b Binary files /dev/null and b/v2.15.0/assets/examples/Predicting Bike Rental Demand_18_1.png differ diff --git a/v2.15.0/assets/examples/Probit Model (EP)_6_1.png b/v2.15.0/assets/examples/Probit Model (EP)_6_1.png new file mode 100644 index 000000000..b9b15d04b Binary files /dev/null and b/v2.15.0/assets/examples/Probit Model (EP)_6_1.png differ diff --git a/v2.15.0/assets/examples/Probit Model (EP)_9_1.png b/v2.15.0/assets/examples/Probit Model (EP)_9_1.png new file mode 100644 index 000000000..baf1f1c80 Binary files /dev/null and b/v2.15.0/assets/examples/Probit Model (EP)_9_1.png differ diff --git a/v2.15.0/assets/examples/RTS vs BIFM Smoothing_11_1.png b/v2.15.0/assets/examples/RTS vs BIFM Smoothing_11_1.png new file mode 100644 index 000000000..3f6042325 Binary files /dev/null and b/v2.15.0/assets/examples/RTS vs BIFM Smoothing_11_1.png differ diff --git a/v2.15.0/assets/examples/RTS vs BIFM Smoothing_12_1.png b/v2.15.0/assets/examples/RTS vs BIFM Smoothing_12_1.png new file mode 100644 index 000000000..ed09f6509 Binary files /dev/null and b/v2.15.0/assets/examples/RTS vs BIFM Smoothing_12_1.png differ diff --git a/v2.15.0/assets/examples/RTS vs BIFM Smoothing_5_1.png b/v2.15.0/assets/examples/RTS vs BIFM Smoothing_5_1.png new file mode 100644 index 000000000..e4e3c87cc Binary files /dev/null and b/v2.15.0/assets/examples/RTS vs BIFM Smoothing_5_1.png differ diff --git a/v2.15.0/assets/examples/Simple Nonlinear Node_14_1.png b/v2.15.0/assets/examples/Simple Nonlinear Node_14_1.png new file mode 100644 index 000000000..f4a0ae3fd Binary files /dev/null and b/v2.15.0/assets/examples/Simple Nonlinear Node_14_1.png differ diff --git a/v2.15.0/assets/examples/Tiny Benchmark_11_1.png b/v2.15.0/assets/examples/Tiny Benchmark_11_1.png new file mode 100644 index 000000000..97ee402ca Binary files /dev/null and b/v2.15.0/assets/examples/Tiny Benchmark_11_1.png differ diff --git a/v2.15.0/assets/examples/Tiny Benchmark_7_1.png b/v2.15.0/assets/examples/Tiny Benchmark_7_1.png new file mode 100644 index 000000000..36c08b460 Binary files /dev/null and b/v2.15.0/assets/examples/Tiny Benchmark_7_1.png differ diff --git a/v2.15.0/assets/examples/Universal Mixtures_10_1.png b/v2.15.0/assets/examples/Universal Mixtures_10_1.png new file mode 100644 index 000000000..fd23f884a Binary files /dev/null and b/v2.15.0/assets/examples/Universal Mixtures_10_1.png differ diff --git a/v2.15.0/assets/examples/Universal Mixtures_13_1.png b/v2.15.0/assets/examples/Universal Mixtures_13_1.png new file mode 100644 index 000000000..cf2c5244c Binary files /dev/null and b/v2.15.0/assets/examples/Universal Mixtures_13_1.png differ diff --git a/v2.15.0/assets/examples/Universal Mixtures_3_1.png b/v2.15.0/assets/examples/Universal Mixtures_3_1.png new file mode 100644 index 000000000..cec0904cc Binary files /dev/null and b/v2.15.0/assets/examples/Universal Mixtures_3_1.png differ diff --git a/v2.15.0/assets/examples/Universal Mixtures_9_1.png b/v2.15.0/assets/examples/Universal Mixtures_9_1.png new file mode 100644 index 000000000..a6c946c8b Binary files /dev/null and b/v2.15.0/assets/examples/Universal Mixtures_9_1.png differ diff --git a/v2.15.0/assets/examples/pics/ai-mountain-car-ai.gif b/v2.15.0/assets/examples/pics/ai-mountain-car-ai.gif new file mode 100644 index 000000000..d0f4a32ac Binary files /dev/null and b/v2.15.0/assets/examples/pics/ai-mountain-car-ai.gif differ diff --git a/v2.15.0/assets/examples/pics/ai-mountain-car-naive.gif b/v2.15.0/assets/examples/pics/ai-mountain-car-naive.gif new file mode 100644 index 000000000..80fdf4e1c Binary files /dev/null and b/v2.15.0/assets/examples/pics/ai-mountain-car-naive.gif differ diff --git a/v2.15.0/assets/examples/pics/hblr-matrix-completion.jpeg b/v2.15.0/assets/examples/pics/hblr-matrix-completion.jpeg new file mode 100644 index 000000000..be0f78e1c Binary files /dev/null and b/v2.15.0/assets/examples/pics/hblr-matrix-completion.jpeg differ diff --git a/v2.15.0/assets/examples/pics/infinite-data-stream-inference.gif b/v2.15.0/assets/examples/pics/infinite-data-stream-inference.gif new file mode 100644 index 000000000..a7a917012 Binary files /dev/null and b/v2.15.0/assets/examples/pics/infinite-data-stream-inference.gif differ diff --git a/v2.15.0/assets/examples/pics/infinite-data-stream.gif b/v2.15.0/assets/examples/pics/infinite-data-stream.gif new file mode 100644 index 000000000..ffd5818a5 Binary files /dev/null and b/v2.15.0/assets/examples/pics/infinite-data-stream.gif differ diff --git a/v2.15.0/assets/examples/pics/online-coin-bias-inference.gif b/v2.15.0/assets/examples/pics/online-coin-bias-inference.gif new file mode 100644 index 000000000..171142858 Binary files /dev/null and b/v2.15.0/assets/examples/pics/online-coin-bias-inference.gif differ diff --git a/v2.15.0/assets/examples/pics/pipeline.png b/v2.15.0/assets/examples/pics/pipeline.png new file mode 100644 index 000000000..d8302e166 Binary files /dev/null and b/v2.15.0/assets/examples/pics/pipeline.png differ diff --git a/v2.15.0/assets/examples/pics/posterior.png b/v2.15.0/assets/examples/pics/posterior.png new file mode 100644 index 000000000..4fa49edff Binary files /dev/null and b/v2.15.0/assets/examples/pics/posterior.png differ diff --git a/v2.15.0/assets/examples/pics/rts_bifm_benchmark.png b/v2.15.0/assets/examples/pics/rts_bifm_benchmark.png new file mode 100644 index 000000000..51a066062 Binary files /dev/null and b/v2.15.0/assets/examples/pics/rts_bifm_benchmark.png differ diff --git a/v2.15.0/assets/examples/pics/sp.png b/v2.15.0/assets/examples/pics/sp.png new file mode 100644 index 000000000..dedc65431 Binary files /dev/null and b/v2.15.0/assets/examples/pics/sp.png differ diff --git a/v2.15.0/assets/examples/pics/vmp.png b/v2.15.0/assets/examples/pics/vmp.png new file mode 100644 index 000000000..0561f27e3 Binary files /dev/null and b/v2.15.0/assets/examples/pics/vmp.png differ diff --git a/v2.15.0/assets/header.css b/v2.15.0/assets/header.css new file mode 100644 index 000000000..155b10a3b --- /dev/null +++ b/v2.15.0/assets/header.css @@ -0,0 +1,138 @@ + +@media all and (max-width: 560px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar { + min-height: 1rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + min-height: 1rem !important; + margin-left: 0.5rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: visible !important; + display: block !important; + margin: 0.5rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + visibility: hidden; + display: none; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a { + visibility: hidden; + display: none; + } + + html:not(.theme--documenter-dark) body #documenter .docs-main { + margin-top: 2rem !important; + } +} + +@media all and (max-width: 1055px) and (min-width: 561px){ + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + width: 80% !important; + } +} + +@media all and (min-width: 1056px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 18rem; + } + +} + +html.theme--documenter-dark header.navigation { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container { + border-bottom: 1px solid #5e6d6f; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: white; + transition: color 100ms; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +html header.navigation { + background-color: white !important; +} + +html header.navigation div.container { + border-bottom: 1px solid #dbdbdb; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: #222; + transition: color 100ms; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +header.navigation { + z-index: 3; +} + +header.navigation div.container nav.navbar ul.navbar-nav { + margin-left: 4rem; + min-height: 3.25rem; + width: 70%; + display: flex; + align-self: auto; + flex-direction: row; + justify-content: space-around; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + align-self: stretch; + align-content: space-around; + justify-content: center; + display: flex; + flex-direction: column; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: hidden; + display: none; +} \ No newline at end of file diff --git a/v2.15.0/assets/header.js b/v2.15.0/assets/header.js new file mode 100644 index 000000000..c3f0edbe4 --- /dev/null +++ b/v2.15.0/assets/header.js @@ -0,0 +1,97 @@ + +// We add a simple `onload` hook to inject the custom header for our `HTML`-generated pages +window.onload = function() { + //
+ const header = document.createElement('header') + header.classList.add("navigation") + header.appendChild((() => { + const container = document.createElement('div') + container.classList.add('container') + container.appendChild((() => { + const nav = document.createElement('nav') + nav.classList.add("navbar") + + nav.appendChild((() => { + const ul = document.createElement("ul") + ul.classList.add("navbar-nav") + + ul.appendChild((() => { + const smalllink = document.createElement('li') + smalllink.classList.add('small-item') + smalllink.appendChild((() => { + const a = document.createElement('a') + a.classList.add("nav-link") + a.href = 'http://www.rxinfer.ml' + a.innerHTML = 'RxInfer.jl' + a.title = 'RxInfer.jl' + return a + })()) + return smalllink + })()) + + const items = [ + { title: "Home", link: "http://www.rxinfer.ml", icon: [ "fas", "fa-diagram-project" ] }, + { title: "Get Started", link: "https://biaslab.github.io/RxInfer.jl/stable/manuals/getting-started/" }, + { title: "Documentation", link: "https://biaslab.github.io/RxInfer.jl/stable/" }, + { title: "Examples", link: "https://biaslab.github.io/RxInfer.jl/stable/examples/overview/" }, + { title: "Papers", link: "https://biaslab.github.io/publication/" }, + { title: "Team", link: "https://biaslab.github.io/team/" }, + // { title: "Contact", link: "http://www.rxinfer.ml/contact/" }, the redirect is broken for now + { title: "GitHub", link: "https://github.com/biaslab/RxInfer.jl", icon: [ "fab", "fa-github" ] }, + ] + + items.forEach((item) => { + ul.appendChild(((item) => { + const li = document.createElement("li") + li.classList.add("nav-item") + li.appendChild((() => { + const a = document.createElement("a") + + if (item.icon !== undefined) { + a.appendChild((() => { + const i = document.createElement("i") + i.classList.add(...(item.icon)) + return i + })()) + } + + a.classList.add("nav-link") + a.href = item.link + a.title = item.title + + a.appendChild((() => { + const span = document.createElement("span") + span.innerHTML = ` ${item.title}` + return span + })()) + + return a + })()) + return li + })(item)) + }) + return ul + })()) + return nav + })()) + return container + })()) + + const documenterTarget = document.querySelector('#documenter'); + + documenterTarget.parentNode.insertBefore(header, documenterTarget); + + // Edit broken links in the examples, see issue #70 + const editOnGithubLinkTarget = document.querySelector('.docs-edit-link'); + + if (editOnGithubLinkTarget) { + const link = editOnGithubLinkTarget.href; + if (link.includes('docs/src/examples')) { + const fixedLink = link.replace('docs/src/', '').replace('.md', '.ipynb'); + editOnGithubLinkTarget.href = fixedLink; + console.log('Fixed link for the example: ', fixedLink) + } + } + +} + diff --git a/v2.15.0/assets/img/bp-message.svg b/v2.15.0/assets/img/bp-message.svg new file mode 100644 index 000000000..259b70803 --- /dev/null +++ b/v2.15.0/assets/img/bp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.15.0/assets/img/coin-flip.png b/v2.15.0/assets/img/coin-flip.png new file mode 100644 index 000000000..2ed0f04c0 Binary files /dev/null and b/v2.15.0/assets/img/coin-flip.png differ diff --git a/v2.15.0/assets/img/coin-flip.svg b/v2.15.0/assets/img/coin-flip.svg new file mode 100644 index 000000000..a85960c12 --- /dev/null +++ b/v2.15.0/assets/img/coin-flip.svg @@ -0,0 +1,794 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/assets/img/debugging_graph.png b/v2.15.0/assets/img/debugging_graph.png new file mode 100644 index 000000000..b97ef1a06 Binary files /dev/null and b/v2.15.0/assets/img/debugging_graph.png differ diff --git a/v2.15.0/assets/img/debugging_messages.png b/v2.15.0/assets/img/debugging_messages.png new file mode 100644 index 000000000..8ec84e778 Binary files /dev/null and b/v2.15.0/assets/img/debugging_messages.png differ diff --git a/v2.15.0/assets/img/release_comment.png b/v2.15.0/assets/img/release_comment.png new file mode 100644 index 000000000..743fe9614 Binary files /dev/null and b/v2.15.0/assets/img/release_comment.png differ diff --git a/v2.15.0/assets/img/vmp-message.svg b/v2.15.0/assets/img/vmp-message.svg new file mode 100644 index 000000000..475cd7f49 --- /dev/null +++ b/v2.15.0/assets/img/vmp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.15.0/assets/logo-dark.svg b/v2.15.0/assets/logo-dark.svg new file mode 100644 index 000000000..63b4f65fa --- /dev/null +++ b/v2.15.0/assets/logo-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + diff --git a/v2.15.0/assets/logo.svg b/v2.15.0/assets/logo.svg new file mode 100644 index 000000000..b799e5beb --- /dev/null +++ b/v2.15.0/assets/logo.svg @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/v2.15.0/assets/theme.css b/v2.15.0/assets/theme.css new file mode 100644 index 000000000..1b060cdef --- /dev/null +++ b/v2.15.0/assets/theme.css @@ -0,0 +1,27 @@ +html body #documenter .docs-main { + margin-top: 4rem; +} + +html body #documenter .docs-sidebar.visible { + margin-top: 0px !important; +} + +html div.light-biglogo { + display: block; +} + +html.theme--documenter-dark div.light-biglogo { + display: none; +} + +html div.dark-biglogo { + display: none; +} + +html.theme--documenter-dark div.dark-biglogo { + display: block; +} + +#documenter .docs-main article.content img { + width: 100%; +} diff --git a/v2.15.0/assets/themes/documenter-dark.css b/v2.15.0/assets/themes/documenter-dark.css new file mode 100644 index 000000000..9f5449f4b --- /dev/null +++ b/v2.15.0/assets/themes/documenter-dark.css @@ -0,0 +1,7 @@ +html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:.4em;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus,html.theme--documenter-dark .pagination-ellipsis:focus,html.theme--documenter-dark .file-cta:focus,html.theme--documenter-dark .file-name:focus,html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .button:focus,html.theme--documenter-dark .is-focused.pagination-previous,html.theme--documenter-dark .is-focused.pagination-next,html.theme--documenter-dark .is-focused.pagination-link,html.theme--documenter-dark .is-focused.pagination-ellipsis,html.theme--documenter-dark .is-focused.file-cta,html.theme--documenter-dark .is-focused.file-name,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-focused.button,html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active,html.theme--documenter-dark .pagination-ellipsis:active,html.theme--documenter-dark .file-cta:active,html.theme--documenter-dark .file-name:active,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .button:active,html.theme--documenter-dark .is-active.pagination-previous,html.theme--documenter-dark .is-active.pagination-next,html.theme--documenter-dark .is-active.pagination-link,html.theme--documenter-dark .is-active.pagination-ellipsis,html.theme--documenter-dark .is-active.file-cta,html.theme--documenter-dark .is-active.file-name,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .is-active.button{outline:none}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-ellipsis[disabled],html.theme--documenter-dark .file-cta[disabled],html.theme--documenter-dark .file-name[disabled],html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark fieldset[disabled] .pagination-previous,fieldset[disabled] html.theme--documenter-dark .pagination-next,html.theme--documenter-dark fieldset[disabled] .pagination-next,fieldset[disabled] html.theme--documenter-dark .pagination-link,html.theme--documenter-dark fieldset[disabled] .pagination-link,fieldset[disabled] html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark fieldset[disabled] .pagination-ellipsis,fieldset[disabled] html.theme--documenter-dark .file-cta,html.theme--documenter-dark fieldset[disabled] .file-cta,fieldset[disabled] html.theme--documenter-dark .file-name,html.theme--documenter-dark fieldset[disabled] .file-name,fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark fieldset[disabled] .select select,html.theme--documenter-dark .select fieldset[disabled] select,html.theme--documenter-dark fieldset[disabled] .textarea,html.theme--documenter-dark fieldset[disabled] .input,html.theme--documenter-dark fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] html.theme--documenter-dark .button,html.theme--documenter-dark fieldset[disabled] .button{cursor:not-allowed}html.theme--documenter-dark .tabs,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .breadcrumb,html.theme--documenter-dark .file,html.theme--documenter-dark .button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after,html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}html.theme--documenter-dark .admonition:not(:last-child),html.theme--documenter-dark .tabs:not(:last-child),html.theme--documenter-dark .pagination:not(:last-child),html.theme--documenter-dark .message:not(:last-child),html.theme--documenter-dark .level:not(:last-child),html.theme--documenter-dark .breadcrumb:not(:last-child),html.theme--documenter-dark .block:not(:last-child),html.theme--documenter-dark .title:not(:last-child),html.theme--documenter-dark .subtitle:not(:last-child),html.theme--documenter-dark .table-container:not(:last-child),html.theme--documenter-dark .table:not(:last-child),html.theme--documenter-dark .progress:not(:last-child),html.theme--documenter-dark .notification:not(:last-child),html.theme--documenter-dark .content:not(:last-child),html.theme--documenter-dark .box:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .modal-close,html.theme--documenter-dark .delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before,html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before{height:2px;width:50%}html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{height:50%;width:2px}html.theme--documenter-dark .modal-close:hover,html.theme--documenter-dark .delete:hover,html.theme--documenter-dark .modal-close:focus,html.theme--documenter-dark .delete:focus{background-color:rgba(10,10,10,0.3)}html.theme--documenter-dark .modal-close:active,html.theme--documenter-dark .delete:active{background-color:rgba(10,10,10,0.4)}html.theme--documenter-dark .is-small.modal-close,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.modal-close,html.theme--documenter-dark .is-small.delete,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}html.theme--documenter-dark .is-medium.modal-close,html.theme--documenter-dark .is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}html.theme--documenter-dark .is-large.modal-close,html.theme--documenter-dark .is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}html.theme--documenter-dark .control.is-loading::after,html.theme--documenter-dark .select.is-loading::after,html.theme--documenter-dark .loader,html.theme--documenter-dark .button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdee0;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}html.theme--documenter-dark .hero-video,html.theme--documenter-dark .modal-background,html.theme--documenter-dark .modal,html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}html.theme--documenter-dark .navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#ecf0f1 !important}a.has-text-light:hover,a.has-text-light:focus{color:#cfd9db !important}.has-background-light{background-color:#ecf0f1 !important}.has-text-dark{color:#282f2f !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#111414 !important}.has-background-dark{background-color:#282f2f !important}.has-text-primary{color:#375a7f !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#28415b !important}.has-background-primary{background-color:#375a7f !important}.has-text-primary-light{color:#f1f5f9 !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#cddbe9 !important}.has-background-primary-light{background-color:#f1f5f9 !important}.has-text-primary-dark{color:#4d7eb2 !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#7198c1 !important}.has-background-primary-dark{background-color:#4d7eb2 !important}.has-text-link{color:#1abc9c !important}a.has-text-link:hover,a.has-text-link:focus{color:#148f77 !important}.has-background-link{background-color:#1abc9c !important}.has-text-link-light{color:#edfdf9 !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c0f6ec !important}.has-background-link-light{background-color:#edfdf9 !important}.has-text-link-dark{color:#15987e !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#1bc5a4 !important}.has-background-link-dark{background-color:#15987e !important}.has-text-info{color:#024c7d !important}a.has-text-info:hover,a.has-text-info:focus{color:#012d4b !important}.has-background-info{background-color:#024c7d !important}.has-text-info-light{color:#ebf7ff !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#b9e2fe !important}.has-background-info-light{background-color:#ebf7ff !important}.has-text-info-dark{color:#0e9dfb !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#40b1fc !important}.has-background-info-dark{background-color:#0e9dfb !important}.has-text-success{color:#008438 !important}a.has-text-success:hover,a.has-text-success:focus{color:#005122 !important}.has-background-success{background-color:#008438 !important}.has-text-success-light{color:#ebfff3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#b8ffd6 !important}.has-background-success-light{background-color:#ebfff3 !important}.has-text-success-dark{color:#00eb64 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#1fff7e !important}.has-background-success-dark{background-color:#00eb64 !important}.has-text-warning{color:#ad8100 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#7a5b00 !important}.has-background-warning{background-color:#ad8100 !important}.has-text-warning-light{color:#fffaeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#ffedb8 !important}.has-background-warning-light{background-color:#fffaeb !important}.has-text-warning-dark{color:#d19c00 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#ffbf05 !important}.has-background-warning-dark{background-color:#d19c00 !important}.has-text-danger{color:#9e1b0d !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#6f1309 !important}.has-background-danger{background-color:#9e1b0d !important}.has-text-danger-light{color:#fdeeec !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#fac3bd !important}.has-background-danger-light{background-color:#fdeeec !important}.has-text-danger-dark{color:#ec311d !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#f05c4c !important}.has-background-danger-dark{background-color:#ec311d !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#282f2f !important}.has-background-grey-darker{background-color:#282f2f !important}.has-text-grey-dark{color:#343c3d !important}.has-background-grey-dark{background-color:#343c3d !important}.has-text-grey{color:#5e6d6f !important}.has-background-grey{background-color:#5e6d6f !important}.has-text-grey-light{color:#8c9b9d !important}.has-background-grey-light{background-color:#8c9b9d !important}.has-text-grey-lighter{color:#dbdee0 !important}.has-background-grey-lighter{background-color:#dbdee0 !important}.has-text-white-ter{color:#ecf0f1 !important}.has-background-white-ter{background-color:#ecf0f1 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}html.theme--documenter-dark{/*! + Theme: a11y-dark + Author: @ericwbailey + Maintainer: @ericwbailey + + Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css +*/}html.theme--documenter-dark html{background-color:#1f2424;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark article,html.theme--documenter-dark aside,html.theme--documenter-dark figure,html.theme--documenter-dark footer,html.theme--documenter-dark header,html.theme--documenter-dark hgroup,html.theme--documenter-dark section{display:block}html.theme--documenter-dark body,html.theme--documenter-dark button,html.theme--documenter-dark input,html.theme--documenter-dark optgroup,html.theme--documenter-dark select,html.theme--documenter-dark textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}html.theme--documenter-dark code,html.theme--documenter-dark pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark body{color:#fff;font-size:1em;font-weight:400;line-height:1.5}html.theme--documenter-dark a{color:#1abc9c;cursor:pointer;text-decoration:none}html.theme--documenter-dark a strong{color:currentColor}html.theme--documenter-dark a:hover{color:#1dd2af}html.theme--documenter-dark code{background-color:rgba(255,255,255,0.05);color:#ececec;font-size:.875em;font-weight:normal;padding:.1em}html.theme--documenter-dark hr{background-color:#282f2f;border:none;display:block;height:2px;margin:1.5rem 0}html.theme--documenter-dark img{height:auto;max-width:100%}html.theme--documenter-dark input[type="checkbox"],html.theme--documenter-dark input[type="radio"]{vertical-align:baseline}html.theme--documenter-dark small{font-size:.875em}html.theme--documenter-dark span{font-style:inherit;font-weight:inherit}html.theme--documenter-dark strong{color:#f2f2f2;font-weight:700}html.theme--documenter-dark fieldset{border:none}html.theme--documenter-dark pre{-webkit-overflow-scrolling:touch;background-color:#282f2f;color:#fff;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}html.theme--documenter-dark pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}html.theme--documenter-dark table td,html.theme--documenter-dark table th{vertical-align:top}html.theme--documenter-dark table td:not([align]),html.theme--documenter-dark table th:not([align]){text-align:inherit}html.theme--documenter-dark table th{color:#f2f2f2}html.theme--documenter-dark .box{background-color:#343c3d;border-radius:8px;box-shadow:none;color:#fff;display:block;padding:1.25rem}html.theme--documenter-dark a.box:hover,html.theme--documenter-dark a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #1abc9c}html.theme--documenter-dark a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #1abc9c}html.theme--documenter-dark .button{background-color:#282f2f;border-color:#4c5759;border-width:1px;color:#375a7f;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}html.theme--documenter-dark .button strong{color:inherit}html.theme--documenter-dark .button .icon,html.theme--documenter-dark .button .icon.is-small,html.theme--documenter-dark .button #documenter .docs-sidebar form.docs-search>input.icon,html.theme--documenter-dark #documenter .docs-sidebar .button form.docs-search>input.icon,html.theme--documenter-dark .button .icon.is-medium,html.theme--documenter-dark .button .icon.is-large{height:1.5em;width:1.5em}html.theme--documenter-dark .button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}html.theme--documenter-dark .button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button:hover,html.theme--documenter-dark .button.is-hovered{border-color:#8c9b9d;color:#f2f2f2}html.theme--documenter-dark .button:focus,html.theme--documenter-dark .button.is-focused{border-color:#8c9b9d;color:#17a689}html.theme--documenter-dark .button:focus:not(:active),html.theme--documenter-dark .button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button:active,html.theme--documenter-dark .button.is-active{border-color:#343c3d;color:#f2f2f2}html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;color:#fff;text-decoration:underline}html.theme--documenter-dark .button.is-text:hover,html.theme--documenter-dark .button.is-text.is-hovered,html.theme--documenter-dark .button.is-text:focus,html.theme--documenter-dark .button.is-text.is-focused{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .button.is-text:active,html.theme--documenter-dark .button.is-text.is-active{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .button.is-text[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}html.theme--documenter-dark .button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#1abc9c;text-decoration:none}html.theme--documenter-dark .button.is-ghost:hover,html.theme--documenter-dark .button.is-ghost.is-hovered{color:#1abc9c;text-decoration:underline}html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:hover,html.theme--documenter-dark .button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus,html.theme--documenter-dark .button.is-white.is-focused{border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus:not(:active),html.theme--documenter-dark .button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-hovered{background-color:#000}html.theme--documenter-dark .button.is-white.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-white.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:hover,html.theme--documenter-dark .button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus,html.theme--documenter-dark .button.is-black.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus:not(:active),html.theme--documenter-dark .button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-black.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:hover,html.theme--documenter-dark .button.is-light.is-hovered{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus,html.theme--documenter-dark .button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus:not(:active),html.theme--documenter-dark .button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light.is-active{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:#ecf0f1;box-shadow:none}html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-outlined.is-focused{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-dark,html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover,html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus:not(:active),html.theme--documenter-dark .content kbd.button:focus:not(:active),html.theme--documenter-dark .button.is-dark.is-focused:not(:active),html.theme--documenter-dark .content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark[disabled],html.theme--documenter-dark .content kbd.button[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark,fieldset[disabled] html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:#282f2f;box-shadow:none}html.theme--documenter-dark .button.is-dark.is-inverted,html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted:hover,html.theme--documenter-dark .content kbd.button.is-inverted:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-dark.is-inverted[disabled],html.theme--documenter-dark .content kbd.button.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-loading::after,html.theme--documenter-dark .content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined,html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-outlined.is-focused{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus:not(:active),html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus:not(:active),html.theme--documenter-dark .button.is-primary.is-focused:not(:active),html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary[disabled],html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;box-shadow:none}html.theme--documenter-dark .button.is-primary.is-inverted,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}html.theme--documenter-dark .button.is-primary.is-inverted[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:hover,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-light.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e8eef5;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:active,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-light.is-active,html.theme--documenter-dark .docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#dfe8f1;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:hover,html.theme--documenter-dark .button.is-link.is-hovered{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus,html.theme--documenter-dark .button.is-link.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus:not(:active),html.theme--documenter-dark .button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link.is-active{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:#1abc9c;box-shadow:none}html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-link.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-outlined.is-focused{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:hover,html.theme--documenter-dark .button.is-link.is-light.is-hovered{background-color:#e2fbf6;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:active,html.theme--documenter-dark .button.is-link.is-light.is-active{background-color:#d7f9f3;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:hover,html.theme--documenter-dark .button.is-info.is-hovered{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus,html.theme--documenter-dark .button.is-info.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus:not(:active),html.theme--documenter-dark .button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info.is-active{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:#024c7d;box-shadow:none}html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-info.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;color:#024c7d}html.theme--documenter-dark .button.is-info.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-outlined.is-focused{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:hover,html.theme--documenter-dark .button.is-info.is-light.is-hovered{background-color:#def2fe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:active,html.theme--documenter-dark .button.is-info.is-light.is-active{background-color:#d2edfe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:hover,html.theme--documenter-dark .button.is-success.is-hovered{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus,html.theme--documenter-dark .button.is-success.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus:not(:active),html.theme--documenter-dark .button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success.is-active{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:#008438;box-shadow:none}html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-success.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;color:#008438}html.theme--documenter-dark .button.is-success.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-outlined.is-focused{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:hover,html.theme--documenter-dark .button.is-success.is-light.is-hovered{background-color:#deffec;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:active,html.theme--documenter-dark .button.is-success.is-light.is-active{background-color:#d1ffe5;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:hover,html.theme--documenter-dark .button.is-warning.is-hovered{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus,html.theme--documenter-dark .button.is-warning.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus:not(:active),html.theme--documenter-dark .button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning.is-active{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:#ad8100;box-shadow:none}html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-warning.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-outlined.is-focused{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-focused{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:hover,html.theme--documenter-dark .button.is-warning.is-light.is-hovered{background-color:#fff7de;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:active,html.theme--documenter-dark .button.is-warning.is-light.is-active{background-color:#fff3d1;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:hover,html.theme--documenter-dark .button.is-danger.is-hovered{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus,html.theme--documenter-dark .button.is-danger.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus:not(:active),html.theme--documenter-dark .button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger.is-active{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;box-shadow:none}html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-danger.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-outlined.is-focused{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:hover,html.theme--documenter-dark .button.is-danger.is-light.is-hovered{background-color:#fce3e0;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:active,html.theme--documenter-dark .button.is-danger.is-light.is-active{background-color:#fcd8d5;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}html.theme--documenter-dark .button.is-small:not(.is-rounded),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:3px}html.theme--documenter-dark .button.is-normal{font-size:1rem}html.theme--documenter-dark .button.is-medium{font-size:1.25rem}html.theme--documenter-dark .button.is-large{font-size:1.5rem}html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .button{background-color:#8c9b9d;border-color:#5e6d6f;box-shadow:none;opacity:.5}html.theme--documenter-dark .button.is-fullwidth{display:flex;width:100%}html.theme--documenter-dark .button.is-loading{color:transparent !important;pointer-events:none}html.theme--documenter-dark .button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}html.theme--documenter-dark .button.is-static{background-color:#282f2f;border-color:#5e6d6f;color:#dbdee0;box-shadow:none;pointer-events:none}html.theme--documenter-dark .button.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}html.theme--documenter-dark .buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .buttons .button{margin-bottom:0.5rem}html.theme--documenter-dark .buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}html.theme--documenter-dark .buttons:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .buttons:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:3px}html.theme--documenter-dark .buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}html.theme--documenter-dark .buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}html.theme--documenter-dark .buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}html.theme--documenter-dark .buttons.has-addons .button:last-child{margin-right:0}html.theme--documenter-dark .buttons.has-addons .button:hover,html.theme--documenter-dark .buttons.has-addons .button.is-hovered{z-index:2}html.theme--documenter-dark .buttons.has-addons .button:focus,html.theme--documenter-dark .buttons.has-addons .button.is-focused,html.theme--documenter-dark .buttons.has-addons .button:active,html.theme--documenter-dark .buttons.has-addons .button.is-active,html.theme--documenter-dark .buttons.has-addons .button.is-selected{z-index:3}html.theme--documenter-dark .buttons.has-addons .button:focus:hover,html.theme--documenter-dark .buttons.has-addons .button.is-focused:hover,html.theme--documenter-dark .buttons.has-addons .button:active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-selected:hover{z-index:4}html.theme--documenter-dark .buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .buttons.is-centered{justify-content:center}html.theme--documenter-dark .buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}html.theme--documenter-dark .buttons.is-right{justify-content:flex-end}html.theme--documenter-dark .buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:1rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1.25rem}}html.theme--documenter-dark .container{flex-grow:1;margin:0 auto;position:relative;width:auto}html.theme--documenter-dark .container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){html.theme--documenter-dark .container{max-width:992px}}@media screen and (max-width: 1215px){html.theme--documenter-dark .container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){html.theme--documenter-dark .container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){html.theme--documenter-dark .container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){html.theme--documenter-dark .container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}html.theme--documenter-dark .content li+li{margin-top:0.25em}html.theme--documenter-dark .content p:not(:last-child),html.theme--documenter-dark .content dl:not(:last-child),html.theme--documenter-dark .content ol:not(:last-child),html.theme--documenter-dark .content ul:not(:last-child),html.theme--documenter-dark .content blockquote:not(:last-child),html.theme--documenter-dark .content pre:not(:last-child),html.theme--documenter-dark .content table:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .content h1,html.theme--documenter-dark .content h2,html.theme--documenter-dark .content h3,html.theme--documenter-dark .content h4,html.theme--documenter-dark .content h5,html.theme--documenter-dark .content h6{color:#f2f2f2;font-weight:600;line-height:1.125}html.theme--documenter-dark .content h1{font-size:2em;margin-bottom:0.5em}html.theme--documenter-dark .content h1:not(:first-child){margin-top:1em}html.theme--documenter-dark .content h2{font-size:1.75em;margin-bottom:0.5714em}html.theme--documenter-dark .content h2:not(:first-child){margin-top:1.1428em}html.theme--documenter-dark .content h3{font-size:1.5em;margin-bottom:0.6666em}html.theme--documenter-dark .content h3:not(:first-child){margin-top:1.3333em}html.theme--documenter-dark .content h4{font-size:1.25em;margin-bottom:0.8em}html.theme--documenter-dark .content h5{font-size:1.125em;margin-bottom:0.8888em}html.theme--documenter-dark .content h6{font-size:1em;margin-bottom:1em}html.theme--documenter-dark .content blockquote{background-color:#282f2f;border-left:5px solid #5e6d6f;padding:1.25em 1.5em}html.theme--documenter-dark .content ol{list-style-position:outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ol:not([type]){list-style-type:decimal}html.theme--documenter-dark .content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}html.theme--documenter-dark .content ol.is-lower-roman:not([type]){list-style-type:lower-roman}html.theme--documenter-dark .content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}html.theme--documenter-dark .content ol.is-upper-roman:not([type]){list-style-type:upper-roman}html.theme--documenter-dark .content ul{list-style:disc outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ul ul{list-style-type:circle;margin-top:0.5em}html.theme--documenter-dark .content ul ul ul{list-style-type:square}html.theme--documenter-dark .content dd{margin-left:2em}html.theme--documenter-dark .content figure{margin-left:2em;margin-right:2em;text-align:center}html.theme--documenter-dark .content figure:not(:first-child){margin-top:2em}html.theme--documenter-dark .content figure:not(:last-child){margin-bottom:2em}html.theme--documenter-dark .content figure img{display:inline-block}html.theme--documenter-dark .content figure figcaption{font-style:italic}html.theme--documenter-dark .content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}html.theme--documenter-dark .content sup,html.theme--documenter-dark .content sub{font-size:75%}html.theme--documenter-dark .content table{width:100%}html.theme--documenter-dark .content table td,html.theme--documenter-dark .content table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .content table th{color:#f2f2f2}html.theme--documenter-dark .content table th:not([align]){text-align:inherit}html.theme--documenter-dark .content table thead td,html.theme--documenter-dark .content table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .content table tfoot td,html.theme--documenter-dark .content table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .content table tbody tr:last-child td,html.theme--documenter-dark .content table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .content .tabs li+li{margin-top:0}html.theme--documenter-dark .content.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}html.theme--documenter-dark .content.is-normal{font-size:1rem}html.theme--documenter-dark .content.is-medium{font-size:1.25rem}html.theme--documenter-dark .content.is-large{font-size:1.5rem}html.theme--documenter-dark .icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}html.theme--documenter-dark .icon.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}html.theme--documenter-dark .icon.is-medium{height:2rem;width:2rem}html.theme--documenter-dark .icon.is-large{height:3rem;width:3rem}html.theme--documenter-dark .icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}html.theme--documenter-dark .icon-text .icon{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .icon-text .icon:not(:last-child){margin-right:.25em}html.theme--documenter-dark .icon-text .icon:not(:first-child){margin-left:.25em}html.theme--documenter-dark div.icon-text{display:flex}html.theme--documenter-dark .image,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{display:block;position:relative}html.theme--documenter-dark .image img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}html.theme--documenter-dark .image img.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}html.theme--documenter-dark .image.is-fullwidth,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}html.theme--documenter-dark .image.is-square,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square,html.theme--documenter-dark .image.is-1by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}html.theme--documenter-dark .image.is-5by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}html.theme--documenter-dark .image.is-4by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}html.theme--documenter-dark .image.is-3by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}html.theme--documenter-dark .image.is-5by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}html.theme--documenter-dark .image.is-16by9,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}html.theme--documenter-dark .image.is-2by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}html.theme--documenter-dark .image.is-3by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}html.theme--documenter-dark .image.is-4by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}html.theme--documenter-dark .image.is-3by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}html.theme--documenter-dark .image.is-2by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}html.theme--documenter-dark .image.is-3by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}html.theme--documenter-dark .image.is-9by16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}html.theme--documenter-dark .image.is-1by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}html.theme--documenter-dark .image.is-1by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}html.theme--documenter-dark .image.is-16x16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}html.theme--documenter-dark .image.is-24x24,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}html.theme--documenter-dark .image.is-32x32,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}html.theme--documenter-dark .image.is-48x48,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}html.theme--documenter-dark .image.is-64x64,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}html.theme--documenter-dark .image.is-96x96,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}html.theme--documenter-dark .image.is-128x128,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}html.theme--documenter-dark .notification{background-color:#282f2f;border-radius:.4em;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}html.theme--documenter-dark .notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .notification strong{color:currentColor}html.theme--documenter-dark .notification code,html.theme--documenter-dark .notification pre{background:#fff}html.theme--documenter-dark .notification pre code{background:transparent}html.theme--documenter-dark .notification>.delete{right:.5rem;position:absolute;top:0.5rem}html.theme--documenter-dark .notification .title,html.theme--documenter-dark .notification .subtitle,html.theme--documenter-dark .notification .content{color:currentColor}html.theme--documenter-dark .notification.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .notification.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .notification.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .notification.is-dark,html.theme--documenter-dark .content kbd.notification{background-color:#282f2f;color:#fff}html.theme--documenter-dark .notification.is-primary,html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .notification.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.notification.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .notification.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .notification.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .notification.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .notification.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .notification.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .notification.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .notification.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .notification.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .notification.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .notification.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}html.theme--documenter-dark .progress::-webkit-progress-bar{background-color:#343c3d}html.theme--documenter-dark .progress::-webkit-progress-value{background-color:#dbdee0}html.theme--documenter-dark .progress::-moz-progress-bar{background-color:#dbdee0}html.theme--documenter-dark .progress::-ms-fill{background-color:#dbdee0;border:none}html.theme--documenter-dark .progress.is-white::-webkit-progress-value{background-color:#fff}html.theme--documenter-dark .progress.is-white::-moz-progress-bar{background-color:#fff}html.theme--documenter-dark .progress.is-white::-ms-fill{background-color:#fff}html.theme--documenter-dark .progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-black::-webkit-progress-value{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-moz-progress-bar{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-ms-fill{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-light::-webkit-progress-value{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-moz-progress-bar{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-ms-fill{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light:indeterminate{background-image:linear-gradient(to right, #ecf0f1 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-dark::-webkit-progress-value,html.theme--documenter-dark .content kbd.progress::-webkit-progress-value{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-moz-progress-bar,html.theme--documenter-dark .content kbd.progress::-moz-progress-bar{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-ms-fill,html.theme--documenter-dark .content kbd.progress::-ms-fill{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark:indeterminate,html.theme--documenter-dark .content kbd.progress:indeterminate{background-image:linear-gradient(to right, #282f2f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-primary::-webkit-progress-value,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-moz-progress-bar,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-ms-fill,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary:indeterminate,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #375a7f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-link::-webkit-progress-value{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-moz-progress-bar{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-ms-fill{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link:indeterminate{background-image:linear-gradient(to right, #1abc9c 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-info::-webkit-progress-value{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-moz-progress-bar{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-ms-fill{background-color:#024c7d}html.theme--documenter-dark .progress.is-info:indeterminate{background-image:linear-gradient(to right, #024c7d 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-success::-webkit-progress-value{background-color:#008438}html.theme--documenter-dark .progress.is-success::-moz-progress-bar{background-color:#008438}html.theme--documenter-dark .progress.is-success::-ms-fill{background-color:#008438}html.theme--documenter-dark .progress.is-success:indeterminate{background-image:linear-gradient(to right, #008438 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-warning::-webkit-progress-value{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-moz-progress-bar{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-ms-fill{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ad8100 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-danger::-webkit-progress-value{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-moz-progress-bar{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-ms-fill{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger:indeterminate{background-image:linear-gradient(to right, #9e1b0d 30%, #343c3d 30%)}html.theme--documenter-dark .progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#343c3d;background-image:linear-gradient(to right, #fff 30%, #343c3d 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}html.theme--documenter-dark .progress:indeterminate::-webkit-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-moz-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-ms-fill{animation-name:none}html.theme--documenter-dark .progress.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}html.theme--documenter-dark .progress.is-medium{height:1.25rem}html.theme--documenter-dark .progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}html.theme--documenter-dark .table{background-color:#343c3d;color:#fff}html.theme--documenter-dark .table td,html.theme--documenter-dark .table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .table td.is-white,html.theme--documenter-dark .table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .table td.is-black,html.theme--documenter-dark .table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .table td.is-light,html.theme--documenter-dark .table th.is-light{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .table td.is-dark,html.theme--documenter-dark .table th.is-dark{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .table td.is-primary,html.theme--documenter-dark .table th.is-primary{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-link,html.theme--documenter-dark .table th.is-link{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .table td.is-info,html.theme--documenter-dark .table th.is-info{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .table td.is-success,html.theme--documenter-dark .table th.is-success{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .table td.is-warning,html.theme--documenter-dark .table th.is-warning{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .table td.is-danger,html.theme--documenter-dark .table th.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .table td.is-narrow,html.theme--documenter-dark .table th.is-narrow{white-space:nowrap;width:1%}html.theme--documenter-dark .table td.is-selected,html.theme--documenter-dark .table th.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-selected a,html.theme--documenter-dark .table td.is-selected strong,html.theme--documenter-dark .table th.is-selected a,html.theme--documenter-dark .table th.is-selected strong{color:currentColor}html.theme--documenter-dark .table td.is-vcentered,html.theme--documenter-dark .table th.is-vcentered{vertical-align:middle}html.theme--documenter-dark .table th{color:#f2f2f2}html.theme--documenter-dark .table th:not([align]){text-align:left}html.theme--documenter-dark .table tr.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table tr.is-selected a,html.theme--documenter-dark .table tr.is-selected strong{color:currentColor}html.theme--documenter-dark .table tr.is-selected td,html.theme--documenter-dark .table tr.is-selected th{border-color:#fff;color:currentColor}html.theme--documenter-dark .table thead{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table thead td,html.theme--documenter-dark .table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .table tfoot{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tfoot td,html.theme--documenter-dark .table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .table tbody{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tbody tr:last-child td,html.theme--documenter-dark .table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .table.is-bordered td,html.theme--documenter-dark .table.is-bordered th{border-width:1px}html.theme--documenter-dark .table.is-bordered tr:last-child td,html.theme--documenter-dark .table.is-bordered tr:last-child th{border-bottom-width:1px}html.theme--documenter-dark .table.is-fullwidth{width:100%}html.theme--documenter-dark .table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#2d3435}html.theme--documenter-dark .table.is-narrow td,html.theme--documenter-dark .table.is-narrow th{padding:0.25em 0.5em}html.theme--documenter-dark .table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#282f2f}html.theme--documenter-dark .table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}html.theme--documenter-dark .tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .tags .tag,html.theme--documenter-dark .tags .content kbd,html.theme--documenter-dark .content .tags kbd,html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}html.theme--documenter-dark .tags .tag:not(:last-child),html.theme--documenter-dark .tags .content kbd:not(:last-child),html.theme--documenter-dark .content .tags kbd:not(:last-child),html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}html.theme--documenter-dark .tags:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .tags:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .tags.are-medium .tag:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .content kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .content .tags.are-medium kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}html.theme--documenter-dark .tags.are-large .tag:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .content kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .content .tags.are-large kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}html.theme--documenter-dark .tags.is-centered{justify-content:center}html.theme--documenter-dark .tags.is-centered .tag,html.theme--documenter-dark .tags.is-centered .content kbd,html.theme--documenter-dark .content .tags.is-centered kbd,html.theme--documenter-dark .tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}html.theme--documenter-dark .tags.is-right{justify-content:flex-end}html.theme--documenter-dark .tags.is-right .tag:not(:first-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:first-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}html.theme--documenter-dark .tags.is-right .tag:not(:last-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:last-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}html.theme--documenter-dark .tags.has-addons .tag,html.theme--documenter-dark .tags.has-addons .content kbd,html.theme--documenter-dark .content .tags.has-addons kbd,html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}html.theme--documenter-dark .tags.has-addons .tag:not(:first-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:first-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}html.theme--documenter-dark .tags.has-addons .tag:not(:last-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:last-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}html.theme--documenter-dark .tag:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#282f2f;border-radius:.4em;color:#fff;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}html.theme--documenter-dark .tag:not(body) .delete,html.theme--documenter-dark .content kbd:not(body) .delete,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}html.theme--documenter-dark .tag.is-white:not(body),html.theme--documenter-dark .content kbd.is-white:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .tag.is-black:not(body),html.theme--documenter-dark .content kbd.is-black:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .tag.is-light:not(body),html.theme--documenter-dark .content kbd.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .tag.is-dark:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-dark:not(body),html.theme--documenter-dark .content .docstring>section>kbd:not(body){background-color:#282f2f;color:#fff}html.theme--documenter-dark .tag.is-primary:not(body),html.theme--documenter-dark .content kbd.is-primary:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){background-color:#375a7f;color:#fff}html.theme--documenter-dark .tag.is-primary.is-light:not(body),html.theme--documenter-dark .content kbd.is-primary.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .tag.is-link:not(body),html.theme--documenter-dark .content kbd.is-link:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#1abc9c;color:#fff}html.theme--documenter-dark .tag.is-link.is-light:not(body),html.theme--documenter-dark .content kbd.is-link.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .tag.is-info:not(body),html.theme--documenter-dark .content kbd.is-info:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#024c7d;color:#fff}html.theme--documenter-dark .tag.is-info.is-light:not(body),html.theme--documenter-dark .content kbd.is-info.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .tag.is-success:not(body),html.theme--documenter-dark .content kbd.is-success:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#008438;color:#fff}html.theme--documenter-dark .tag.is-success.is-light:not(body),html.theme--documenter-dark .content kbd.is-success.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .tag.is-warning:not(body),html.theme--documenter-dark .content kbd.is-warning:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ad8100;color:#fff}html.theme--documenter-dark .tag.is-warning.is-light:not(body),html.theme--documenter-dark .content kbd.is-warning.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .tag.is-danger:not(body),html.theme--documenter-dark .content kbd.is-danger:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .tag.is-danger.is-light:not(body),html.theme--documenter-dark .content kbd.is-danger.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .tag.is-normal:not(body),html.theme--documenter-dark .content kbd.is-normal:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}html.theme--documenter-dark .tag.is-medium:not(body),html.theme--documenter-dark .content kbd.is-medium:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}html.theme--documenter-dark .tag.is-large:not(body),html.theme--documenter-dark .content kbd.is-large:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}html.theme--documenter-dark .tag:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .content kbd:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}html.theme--documenter-dark .tag:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .content kbd:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}html.theme--documenter-dark .tag:not(body) .icon:first-child:last-child,html.theme--documenter-dark .content kbd:not(body) .icon:first-child:last-child,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}html.theme--documenter-dark .tag.is-delete:not(body),html.theme--documenter-dark .content kbd.is-delete:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before,html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}html.theme--documenter-dark .tag.is-delete:not(body):hover,html.theme--documenter-dark .content kbd.is-delete:not(body):hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):hover,html.theme--documenter-dark .tag.is-delete:not(body):focus,html.theme--documenter-dark .content kbd.is-delete:not(body):focus,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#1d2122}html.theme--documenter-dark .tag.is-delete:not(body):active,html.theme--documenter-dark .content kbd.is-delete:not(body):active,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#111414}html.theme--documenter-dark .tag.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:not(body),html.theme--documenter-dark .content kbd.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}html.theme--documenter-dark a.tag:hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:hover{text-decoration:underline}html.theme--documenter-dark .title,html.theme--documenter-dark .subtitle{word-break:break-word}html.theme--documenter-dark .title em,html.theme--documenter-dark .title span,html.theme--documenter-dark .subtitle em,html.theme--documenter-dark .subtitle span{font-weight:inherit}html.theme--documenter-dark .title sub,html.theme--documenter-dark .subtitle sub{font-size:.75em}html.theme--documenter-dark .title sup,html.theme--documenter-dark .subtitle sup{font-size:.75em}html.theme--documenter-dark .title .tag,html.theme--documenter-dark .title .content kbd,html.theme--documenter-dark .content .title kbd,html.theme--documenter-dark .title .docstring>section>a.docs-sourcelink,html.theme--documenter-dark .subtitle .tag,html.theme--documenter-dark .subtitle .content kbd,html.theme--documenter-dark .content .subtitle kbd,html.theme--documenter-dark .subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}html.theme--documenter-dark .title{color:#fff;font-size:2rem;font-weight:500;line-height:1.125}html.theme--documenter-dark .title strong{color:inherit;font-weight:inherit}html.theme--documenter-dark .title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}html.theme--documenter-dark .title.is-1{font-size:3rem}html.theme--documenter-dark .title.is-2{font-size:2.5rem}html.theme--documenter-dark .title.is-3{font-size:2rem}html.theme--documenter-dark .title.is-4{font-size:1.5rem}html.theme--documenter-dark .title.is-5{font-size:1.25rem}html.theme--documenter-dark .title.is-6{font-size:1rem}html.theme--documenter-dark .title.is-7{font-size:.75rem}html.theme--documenter-dark .subtitle{color:#8c9b9d;font-size:1.25rem;font-weight:400;line-height:1.25}html.theme--documenter-dark .subtitle strong{color:#8c9b9d;font-weight:600}html.theme--documenter-dark .subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}html.theme--documenter-dark .subtitle.is-1{font-size:3rem}html.theme--documenter-dark .subtitle.is-2{font-size:2.5rem}html.theme--documenter-dark .subtitle.is-3{font-size:2rem}html.theme--documenter-dark .subtitle.is-4{font-size:1.5rem}html.theme--documenter-dark .subtitle.is-5{font-size:1.25rem}html.theme--documenter-dark .subtitle.is-6{font-size:1rem}html.theme--documenter-dark .subtitle.is-7{font-size:.75rem}html.theme--documenter-dark .heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}html.theme--documenter-dark .number{align-items:center;background-color:#282f2f;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#1f2424;border-color:#5e6d6f;border-radius:.4em;color:#dbdee0}html.theme--documenter-dark .select select::-moz-placeholder,html.theme--documenter-dark .textarea::-moz-placeholder,html.theme--documenter-dark .input::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select::-webkit-input-placeholder,html.theme--documenter-dark .textarea::-webkit-input-placeholder,html.theme--documenter-dark .input::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:-moz-placeholder,html.theme--documenter-dark .textarea:-moz-placeholder,html.theme--documenter-dark .input:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select:-ms-input-placeholder,html.theme--documenter-dark .textarea:-ms-input-placeholder,html.theme--documenter-dark .input:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:hover,html.theme--documenter-dark .textarea:hover,html.theme--documenter-dark .input:hover,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:hover,html.theme--documenter-dark .select select.is-hovered,html.theme--documenter-dark .is-hovered.textarea,html.theme--documenter-dark .is-hovered.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#8c9b9d}html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{border-color:#1abc9c;box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#8c9b9d;border-color:#282f2f;box-shadow:none;color:#fff}html.theme--documenter-dark .select select[disabled]::-moz-placeholder,html.theme--documenter-dark .textarea[disabled]::-moz-placeholder,html.theme--documenter-dark .input[disabled]::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .textarea[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .input[disabled]::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-moz-placeholder,html.theme--documenter-dark .textarea[disabled]:-moz-placeholder,html.theme--documenter-dark .input[disabled]:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-ms-input-placeholder,html.theme--documenter-dark .textarea[disabled]:-ms-input-placeholder,html.theme--documenter-dark .input[disabled]:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}html.theme--documenter-dark .textarea[readonly],html.theme--documenter-dark .input[readonly],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}html.theme--documenter-dark .is-white.textarea,html.theme--documenter-dark .is-white.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}html.theme--documenter-dark .is-white.textarea:focus,html.theme--documenter-dark .is-white.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:focus,html.theme--documenter-dark .is-white.is-focused.textarea,html.theme--documenter-dark .is-white.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-white.textarea:active,html.theme--documenter-dark .is-white.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:active,html.theme--documenter-dark .is-white.is-active.textarea,html.theme--documenter-dark .is-white.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .is-black.textarea,html.theme--documenter-dark .is-black.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}html.theme--documenter-dark .is-black.textarea:focus,html.theme--documenter-dark .is-black.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:focus,html.theme--documenter-dark .is-black.is-focused.textarea,html.theme--documenter-dark .is-black.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-black.textarea:active,html.theme--documenter-dark .is-black.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:active,html.theme--documenter-dark .is-black.is-active.textarea,html.theme--documenter-dark .is-black.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .is-light.textarea,html.theme--documenter-dark .is-light.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light{border-color:#ecf0f1}html.theme--documenter-dark .is-light.textarea:focus,html.theme--documenter-dark .is-light.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:focus,html.theme--documenter-dark .is-light.is-focused.textarea,html.theme--documenter-dark .is-light.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-light.textarea:active,html.theme--documenter-dark .is-light.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:active,html.theme--documenter-dark .is-light.is-active.textarea,html.theme--documenter-dark .is-light.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .is-dark.textarea,html.theme--documenter-dark .content kbd.textarea,html.theme--documenter-dark .is-dark.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark,html.theme--documenter-dark .content kbd.input{border-color:#282f2f}html.theme--documenter-dark .is-dark.textarea:focus,html.theme--documenter-dark .content kbd.textarea:focus,html.theme--documenter-dark .is-dark.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:focus,html.theme--documenter-dark .content kbd.input:focus,html.theme--documenter-dark .is-dark.is-focused.textarea,html.theme--documenter-dark .content kbd.is-focused.textarea,html.theme--documenter-dark .is-dark.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .content kbd.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-focused,html.theme--documenter-dark .is-dark.textarea:active,html.theme--documenter-dark .content kbd.textarea:active,html.theme--documenter-dark .is-dark.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:active,html.theme--documenter-dark .content kbd.input:active,html.theme--documenter-dark .is-dark.is-active.textarea,html.theme--documenter-dark .content kbd.is-active.textarea,html.theme--documenter-dark .is-dark.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .content kbd.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .is-primary.textarea,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink{border-color:#375a7f}html.theme--documenter-dark .is-primary.textarea:focus,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:focus,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.is-focused.textarea,html.theme--documenter-dark .docstring>section>a.is-focused.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .docstring>section>a.is-focused.input.docs-sourcelink,html.theme--documenter-dark .is-primary.textarea:active,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:active,html.theme--documenter-dark .is-primary.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:active,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:active,html.theme--documenter-dark .is-primary.is-active.textarea,html.theme--documenter-dark .docstring>section>a.is-active.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .is-link.textarea,html.theme--documenter-dark .is-link.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link{border-color:#1abc9c}html.theme--documenter-dark .is-link.textarea:focus,html.theme--documenter-dark .is-link.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:focus,html.theme--documenter-dark .is-link.is-focused.textarea,html.theme--documenter-dark .is-link.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-link.textarea:active,html.theme--documenter-dark .is-link.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:active,html.theme--documenter-dark .is-link.is-active.textarea,html.theme--documenter-dark .is-link.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .is-info.textarea,html.theme--documenter-dark .is-info.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info{border-color:#024c7d}html.theme--documenter-dark .is-info.textarea:focus,html.theme--documenter-dark .is-info.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:focus,html.theme--documenter-dark .is-info.is-focused.textarea,html.theme--documenter-dark .is-info.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-info.textarea:active,html.theme--documenter-dark .is-info.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:active,html.theme--documenter-dark .is-info.is-active.textarea,html.theme--documenter-dark .is-info.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .is-success.textarea,html.theme--documenter-dark .is-success.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success{border-color:#008438}html.theme--documenter-dark .is-success.textarea:focus,html.theme--documenter-dark .is-success.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:focus,html.theme--documenter-dark .is-success.is-focused.textarea,html.theme--documenter-dark .is-success.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-success.textarea:active,html.theme--documenter-dark .is-success.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:active,html.theme--documenter-dark .is-success.is-active.textarea,html.theme--documenter-dark .is-success.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .is-warning.textarea,html.theme--documenter-dark .is-warning.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ad8100}html.theme--documenter-dark .is-warning.textarea:focus,html.theme--documenter-dark .is-warning.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:focus,html.theme--documenter-dark .is-warning.is-focused.textarea,html.theme--documenter-dark .is-warning.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-warning.textarea:active,html.theme--documenter-dark .is-warning.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:active,html.theme--documenter-dark .is-warning.is-active.textarea,html.theme--documenter-dark .is-warning.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .is-danger.textarea,html.theme--documenter-dark .is-danger.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#9e1b0d}html.theme--documenter-dark .is-danger.textarea:focus,html.theme--documenter-dark .is-danger.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:focus,html.theme--documenter-dark .is-danger.is-focused.textarea,html.theme--documenter-dark .is-danger.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-danger.textarea:active,html.theme--documenter-dark .is-danger.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:active,html.theme--documenter-dark .is-danger.is-active.textarea,html.theme--documenter-dark .is-danger.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .is-small.textarea,html.theme--documenter-dark .is-small.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .is-medium.textarea,html.theme--documenter-dark .is-medium.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}html.theme--documenter-dark .is-large.textarea,html.theme--documenter-dark .is-large.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}html.theme--documenter-dark .is-fullwidth.textarea,html.theme--documenter-dark .is-fullwidth.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}html.theme--documenter-dark .is-inline.textarea,html.theme--documenter-dark .is-inline.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}html.theme--documenter-dark .input.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}html.theme--documenter-dark .input.is-static,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}html.theme--documenter-dark .textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}html.theme--documenter-dark .textarea:not([rows]){max-height:40em;min-height:8em}html.theme--documenter-dark .textarea[rows]{height:initial}html.theme--documenter-dark .textarea.has-fixed-size{resize:none}html.theme--documenter-dark .radio,html.theme--documenter-dark .checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}html.theme--documenter-dark .radio input,html.theme--documenter-dark .checkbox input{cursor:pointer}html.theme--documenter-dark .radio:hover,html.theme--documenter-dark .checkbox:hover{color:#8c9b9d}html.theme--documenter-dark .radio[disabled],html.theme--documenter-dark .checkbox[disabled],fieldset[disabled] html.theme--documenter-dark .radio,fieldset[disabled] html.theme--documenter-dark .checkbox,html.theme--documenter-dark .radio input[disabled],html.theme--documenter-dark .checkbox input[disabled]{color:#fff;cursor:not-allowed}html.theme--documenter-dark .radio+.radio{margin-left:.5em}html.theme--documenter-dark .select{display:inline-block;max-width:100%;position:relative;vertical-align:top}html.theme--documenter-dark .select:not(.is-multiple){height:2.5em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border-color:#1abc9c;right:1.125em;z-index:4}html.theme--documenter-dark .select.is-rounded select,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}html.theme--documenter-dark .select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}html.theme--documenter-dark .select select::-ms-expand{display:none}html.theme--documenter-dark .select select[disabled]:hover,fieldset[disabled] html.theme--documenter-dark .select select:hover{border-color:#282f2f}html.theme--documenter-dark .select select:not([multiple]){padding-right:2.5em}html.theme--documenter-dark .select select[multiple]{height:auto;padding:0}html.theme--documenter-dark .select select[multiple] option{padding:0.5em 1em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading):hover::after{border-color:#8c9b9d}html.theme--documenter-dark .select.is-white:not(:hover)::after{border-color:#fff}html.theme--documenter-dark .select.is-white select{border-color:#fff}html.theme--documenter-dark .select.is-white select:hover,html.theme--documenter-dark .select.is-white select.is-hovered{border-color:#f2f2f2}html.theme--documenter-dark .select.is-white select:focus,html.theme--documenter-dark .select.is-white select.is-focused,html.theme--documenter-dark .select.is-white select:active,html.theme--documenter-dark .select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .select.is-black:not(:hover)::after{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select:hover,html.theme--documenter-dark .select.is-black select.is-hovered{border-color:#000}html.theme--documenter-dark .select.is-black select:focus,html.theme--documenter-dark .select.is-black select.is-focused,html.theme--documenter-dark .select.is-black select:active,html.theme--documenter-dark .select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .select.is-light:not(:hover)::after{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select:hover,html.theme--documenter-dark .select.is-light select.is-hovered{border-color:#dde4e6}html.theme--documenter-dark .select.is-light select:focus,html.theme--documenter-dark .select.is-light select.is-focused,html.theme--documenter-dark .select.is-light select:active,html.theme--documenter-dark .select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .select.is-dark:not(:hover)::after,html.theme--documenter-dark .content kbd.select:not(:hover)::after{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select,html.theme--documenter-dark .content kbd.select select{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select:hover,html.theme--documenter-dark .content kbd.select select:hover,html.theme--documenter-dark .select.is-dark select.is-hovered,html.theme--documenter-dark .content kbd.select select.is-hovered{border-color:#1d2122}html.theme--documenter-dark .select.is-dark select:focus,html.theme--documenter-dark .content kbd.select select:focus,html.theme--documenter-dark .select.is-dark select.is-focused,html.theme--documenter-dark .content kbd.select select.is-focused,html.theme--documenter-dark .select.is-dark select:active,html.theme--documenter-dark .content kbd.select select:active,html.theme--documenter-dark .select.is-dark select.is-active,html.theme--documenter-dark .content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .select.is-primary:not(:hover)::after,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select:hover,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:hover,html.theme--documenter-dark .select.is-primary select.is-hovered,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#2f4d6d}html.theme--documenter-dark .select.is-primary select:focus,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:focus,html.theme--documenter-dark .select.is-primary select.is-focused,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-focused,html.theme--documenter-dark .select.is-primary select:active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:active,html.theme--documenter-dark .select.is-primary select.is-active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .select.is-link:not(:hover)::after{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select:hover,html.theme--documenter-dark .select.is-link select.is-hovered{border-color:#17a689}html.theme--documenter-dark .select.is-link select:focus,html.theme--documenter-dark .select.is-link select.is-focused,html.theme--documenter-dark .select.is-link select:active,html.theme--documenter-dark .select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select.is-info:not(:hover)::after{border-color:#024c7d}html.theme--documenter-dark .select.is-info select{border-color:#024c7d}html.theme--documenter-dark .select.is-info select:hover,html.theme--documenter-dark .select.is-info select.is-hovered{border-color:#023d64}html.theme--documenter-dark .select.is-info select:focus,html.theme--documenter-dark .select.is-info select.is-focused,html.theme--documenter-dark .select.is-info select:active,html.theme--documenter-dark .select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .select.is-success:not(:hover)::after{border-color:#008438}html.theme--documenter-dark .select.is-success select{border-color:#008438}html.theme--documenter-dark .select.is-success select:hover,html.theme--documenter-dark .select.is-success select.is-hovered{border-color:#006b2d}html.theme--documenter-dark .select.is-success select:focus,html.theme--documenter-dark .select.is-success select.is-focused,html.theme--documenter-dark .select.is-success select:active,html.theme--documenter-dark .select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .select.is-warning:not(:hover)::after{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select:hover,html.theme--documenter-dark .select.is-warning select.is-hovered{border-color:#946e00}html.theme--documenter-dark .select.is-warning select:focus,html.theme--documenter-dark .select.is-warning select.is-focused,html.theme--documenter-dark .select.is-warning select:active,html.theme--documenter-dark .select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .select.is-danger:not(:hover)::after{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select:hover,html.theme--documenter-dark .select.is-danger select.is-hovered{border-color:#86170b}html.theme--documenter-dark .select.is-danger select:focus,html.theme--documenter-dark .select.is-danger select.is-focused,html.theme--documenter-dark .select.is-danger select:active,html.theme--documenter-dark .select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .select.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .select.is-medium{font-size:1.25rem}html.theme--documenter-dark .select.is-large{font-size:1.5rem}html.theme--documenter-dark .select.is-disabled::after{border-color:#fff !important;opacity:0.5}html.theme--documenter-dark .select.is-fullwidth{width:100%}html.theme--documenter-dark .select.is-fullwidth select{width:100%}html.theme--documenter-dark .select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}html.theme--documenter-dark .select.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .select.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .select.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}html.theme--documenter-dark .file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:hover .file-cta,html.theme--documenter-dark .file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:focus .file-cta,html.theme--documenter-dark .file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}html.theme--documenter-dark .file.is-white:active .file-cta,html.theme--documenter-dark .file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:hover .file-cta,html.theme--documenter-dark .file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:focus .file-cta,html.theme--documenter-dark .file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}html.theme--documenter-dark .file.is-black:active .file-cta,html.theme--documenter-dark .file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-light .file-cta{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:hover .file-cta,html.theme--documenter-dark .file.is-light.is-hovered .file-cta{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:focus .file-cta,html.theme--documenter-dark .file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(236,240,241,0.25);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:active .file-cta,html.theme--documenter-dark .file.is-light.is-active .file-cta{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-dark .file-cta,html.theme--documenter-dark .content kbd.file .file-cta{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:hover .file-cta,html.theme--documenter-dark .content kbd.file:hover .file-cta,html.theme--documenter-dark .file.is-dark.is-hovered .file-cta,html.theme--documenter-dark .content kbd.file.is-hovered .file-cta{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:focus .file-cta,html.theme--documenter-dark .content kbd.file:focus .file-cta,html.theme--documenter-dark .file.is-dark.is-focused .file-cta,html.theme--documenter-dark .content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(40,47,47,0.25);color:#fff}html.theme--documenter-dark .file.is-dark:active .file-cta,html.theme--documenter-dark .content kbd.file:active .file-cta,html.theme--documenter-dark .file.is-dark.is-active .file-cta,html.theme--documenter-dark .content kbd.file.is-active .file-cta{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink .file-cta{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:hover .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:hover .file-cta,html.theme--documenter-dark .file.is-primary.is-hovered .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:focus .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:focus .file-cta,html.theme--documenter-dark .file.is-primary.is-focused .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(55,90,127,0.25);color:#fff}html.theme--documenter-dark .file.is-primary:active .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:active .file-cta,html.theme--documenter-dark .file.is-primary.is-active .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link .file-cta{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:hover .file-cta,html.theme--documenter-dark .file.is-link.is-hovered .file-cta{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:focus .file-cta,html.theme--documenter-dark .file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(26,188,156,0.25);color:#fff}html.theme--documenter-dark .file.is-link:active .file-cta,html.theme--documenter-dark .file.is-link.is-active .file-cta{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info .file-cta{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:hover .file-cta,html.theme--documenter-dark .file.is-info.is-hovered .file-cta{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:focus .file-cta,html.theme--documenter-dark .file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(2,76,125,0.25);color:#fff}html.theme--documenter-dark .file.is-info:active .file-cta,html.theme--documenter-dark .file.is-info.is-active .file-cta{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success .file-cta{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:hover .file-cta,html.theme--documenter-dark .file.is-success.is-hovered .file-cta{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:focus .file-cta,html.theme--documenter-dark .file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(0,132,56,0.25);color:#fff}html.theme--documenter-dark .file.is-success:active .file-cta,html.theme--documenter-dark .file.is-success.is-active .file-cta{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning .file-cta{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:hover .file-cta,html.theme--documenter-dark .file.is-warning.is-hovered .file-cta{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:focus .file-cta,html.theme--documenter-dark .file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(173,129,0,0.25);color:#fff}html.theme--documenter-dark .file.is-warning:active .file-cta,html.theme--documenter-dark .file.is-warning.is-active .file-cta{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger .file-cta{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:hover .file-cta,html.theme--documenter-dark .file.is-danger.is-hovered .file-cta{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:focus .file-cta,html.theme--documenter-dark .file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(158,27,13,0.25);color:#fff}html.theme--documenter-dark .file.is-danger:active .file-cta,html.theme--documenter-dark .file.is-danger.is-active .file-cta{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}html.theme--documenter-dark .file.is-normal{font-size:1rem}html.theme--documenter-dark .file.is-medium{font-size:1.25rem}html.theme--documenter-dark .file.is-medium .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-large{font-size:1.5rem}html.theme--documenter-dark .file.is-large .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .file.has-name.is-empty .file-cta{border-radius:.4em}html.theme--documenter-dark .file.has-name.is-empty .file-name{display:none}html.theme--documenter-dark .file.is-boxed .file-label{flex-direction:column}html.theme--documenter-dark .file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}html.theme--documenter-dark .file.is-boxed .file-name{border-width:0 1px 1px}html.theme--documenter-dark .file.is-boxed .file-icon{height:1.5em;width:1.5em}html.theme--documenter-dark .file.is-boxed .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-boxed.is-small .file-icon .fa,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}html.theme--documenter-dark .file.is-boxed.is-medium .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.is-boxed.is-large .file-icon .fa{font-size:35px}html.theme--documenter-dark .file.is-boxed.has-name .file-cta{border-radius:.4em .4em 0 0}html.theme--documenter-dark .file.is-boxed.has-name .file-name{border-radius:0 0 .4em .4em;border-width:0 1px 1px}html.theme--documenter-dark .file.is-centered{justify-content:center}html.theme--documenter-dark .file.is-fullwidth .file-label{width:100%}html.theme--documenter-dark .file.is-fullwidth .file-name{flex-grow:1;max-width:none}html.theme--documenter-dark .file.is-right{justify-content:flex-end}html.theme--documenter-dark .file.is-right .file-cta{border-radius:0 .4em .4em 0}html.theme--documenter-dark .file.is-right .file-name{border-radius:.4em 0 0 .4em;border-width:1px 0 1px 1px;order:-1}html.theme--documenter-dark .file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}html.theme--documenter-dark .file-label:hover .file-cta{background-color:#232829;color:#f2f2f2}html.theme--documenter-dark .file-label:hover .file-name{border-color:#596668}html.theme--documenter-dark .file-label:active .file-cta{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .file-label:active .file-name{border-color:#535f61}html.theme--documenter-dark .file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-radius:.4em;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}html.theme--documenter-dark .file-cta{background-color:#282f2f;color:#fff}html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}html.theme--documenter-dark .file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}html.theme--documenter-dark .file-icon .fa{font-size:14px}html.theme--documenter-dark .label{color:#f2f2f2;display:block;font-size:1rem;font-weight:700}html.theme--documenter-dark .label:not(:last-child){margin-bottom:0.5em}html.theme--documenter-dark .label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}html.theme--documenter-dark .label.is-medium{font-size:1.25rem}html.theme--documenter-dark .label.is-large{font-size:1.5rem}html.theme--documenter-dark .help{display:block;font-size:.75rem;margin-top:0.25rem}html.theme--documenter-dark .help.is-white{color:#fff}html.theme--documenter-dark .help.is-black{color:#0a0a0a}html.theme--documenter-dark .help.is-light{color:#ecf0f1}html.theme--documenter-dark .help.is-dark,html.theme--documenter-dark .content kbd.help{color:#282f2f}html.theme--documenter-dark .help.is-primary,html.theme--documenter-dark .docstring>section>a.help.docs-sourcelink{color:#375a7f}html.theme--documenter-dark .help.is-link{color:#1abc9c}html.theme--documenter-dark .help.is-info{color:#024c7d}html.theme--documenter-dark .help.is-success{color:#008438}html.theme--documenter-dark .help.is-warning{color:#ad8100}html.theme--documenter-dark .help.is-danger{color:#9e1b0d}html.theme--documenter-dark .field:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.has-addons{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.has-addons .control:not(:last-child){margin-right:-1px}html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .button,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]){z-index:3}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}html.theme--documenter-dark .field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.has-addons.has-addons-centered{justify-content:center}html.theme--documenter-dark .field.has-addons.has-addons-right{justify-content:flex-end}html.theme--documenter-dark .field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .field.is-grouped{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.is-grouped>.control{flex-shrink:0}html.theme--documenter-dark .field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.is-grouped.is-grouped-centered{justify-content:center}html.theme--documenter-dark .field.is-grouped.is-grouped-right{justify-content:flex-end}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline{flex-wrap:wrap}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:last-child,html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field.is-horizontal{display:flex}}html.theme--documenter-dark .field-label .label{font-size:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}html.theme--documenter-dark .field-label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-normal{padding-top:0.375em}html.theme--documenter-dark .field-label.is-medium{font-size:1.25rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-large{font-size:1.5rem;padding-top:0.375em}}html.theme--documenter-dark .field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}html.theme--documenter-dark .field-body .field{margin-bottom:0}html.theme--documenter-dark .field-body>.field{flex-shrink:1}html.theme--documenter-dark .field-body>.field:not(.is-narrow){flex-grow:1}html.theme--documenter-dark .field-body>.field:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}html.theme--documenter-dark .control.has-icons-left .input:focus~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-left .select:focus~.icon,html.theme--documenter-dark .control.has-icons-right .input:focus~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-right .select:focus~.icon{color:#282f2f}html.theme--documenter-dark .control.has-icons-left .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-small~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-small~.icon{font-size:.75rem}html.theme--documenter-dark .control.has-icons-left .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}html.theme--documenter-dark .control.has-icons-left .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-large~.icon{font-size:1.5rem}html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon{color:#5e6d6f;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}html.theme--documenter-dark .control.has-icons-left .input,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input,html.theme--documenter-dark .control.has-icons-left .select select{padding-left:2.5em}html.theme--documenter-dark .control.has-icons-left .icon.is-left{left:0}html.theme--documenter-dark .control.has-icons-right .input,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input,html.theme--documenter-dark .control.has-icons-right .select select{padding-right:2.5em}html.theme--documenter-dark .control.has-icons-right .icon.is-right{right:0}html.theme--documenter-dark .control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}html.theme--documenter-dark .control.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .control.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .control.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .breadcrumb{font-size:1rem;white-space:nowrap}html.theme--documenter-dark .breadcrumb a{align-items:center;color:#1abc9c;display:flex;justify-content:center;padding:0 .75em}html.theme--documenter-dark .breadcrumb a:hover{color:#1dd2af}html.theme--documenter-dark .breadcrumb li{align-items:center;display:flex}html.theme--documenter-dark .breadcrumb li:first-child a{padding-left:0}html.theme--documenter-dark .breadcrumb li.is-active a{color:#f2f2f2;cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb li+li::before{color:#8c9b9d;content:"\0002f"}html.theme--documenter-dark .breadcrumb ul,html.theme--documenter-dark .breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .breadcrumb .icon:first-child{margin-right:.5em}html.theme--documenter-dark .breadcrumb .icon:last-child{margin-left:.5em}html.theme--documenter-dark .breadcrumb.is-centered ol,html.theme--documenter-dark .breadcrumb.is-centered ul{justify-content:center}html.theme--documenter-dark .breadcrumb.is-right ol,html.theme--documenter-dark .breadcrumb.is-right ul{justify-content:flex-end}html.theme--documenter-dark .breadcrumb.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}html.theme--documenter-dark .breadcrumb.is-medium{font-size:1.25rem}html.theme--documenter-dark .breadcrumb.is-large{font-size:1.5rem}html.theme--documenter-dark .breadcrumb.has-arrow-separator li+li::before{content:"\02192"}html.theme--documenter-dark .breadcrumb.has-bullet-separator li+li::before{content:"\02022"}html.theme--documenter-dark .breadcrumb.has-dot-separator li+li::before{content:"\000b7"}html.theme--documenter-dark .breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}html.theme--documenter-dark .card{background-color:#fff;border-radius:.25rem;box-shadow:#171717;color:#fff;max-width:100%;position:relative}html.theme--documenter-dark .card-footer:first-child,html.theme--documenter-dark .card-content:first-child,html.theme--documenter-dark .card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-footer:last-child,html.theme--documenter-dark .card-content:last-child,html.theme--documenter-dark .card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}html.theme--documenter-dark .card-header-title{align-items:center;color:#f2f2f2;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}html.theme--documenter-dark .card-header-title.is-centered{justify-content:center}html.theme--documenter-dark .card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}html.theme--documenter-dark .card-image{display:block;position:relative}html.theme--documenter-dark .card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-content{background-color:rgba(0,0,0,0);padding:1.5rem}html.theme--documenter-dark .card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}html.theme--documenter-dark .card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}html.theme--documenter-dark .card-footer-item:not(:last-child){border-right:1px solid #ededed}html.theme--documenter-dark .card .media:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .dropdown{display:inline-flex;position:relative;vertical-align:top}html.theme--documenter-dark .dropdown.is-active .dropdown-menu,html.theme--documenter-dark .dropdown.is-hoverable:hover .dropdown-menu{display:block}html.theme--documenter-dark .dropdown.is-right .dropdown-menu{left:auto;right:0}html.theme--documenter-dark .dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}html.theme--documenter-dark .dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .dropdown-content{background-color:#282f2f;border-radius:.4em;box-shadow:#171717;padding-bottom:.5rem;padding-top:.5rem}html.theme--documenter-dark .dropdown-item{color:#fff;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}html.theme--documenter-dark a.dropdown-item,html.theme--documenter-dark button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}html.theme--documenter-dark a.dropdown-item:hover,html.theme--documenter-dark button.dropdown-item:hover{background-color:#282f2f;color:#0a0a0a}html.theme--documenter-dark a.dropdown-item.is-active,html.theme--documenter-dark button.dropdown-item.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}html.theme--documenter-dark .level{align-items:center;justify-content:space-between}html.theme--documenter-dark .level code{border-radius:.4em}html.theme--documenter-dark .level img{display:inline-block;vertical-align:top}html.theme--documenter-dark .level.is-mobile{display:flex}html.theme--documenter-dark .level.is-mobile .level-left,html.theme--documenter-dark .level.is-mobile .level-right{display:flex}html.theme--documenter-dark .level.is-mobile .level-left+.level-right{margin-top:0}html.theme--documenter-dark .level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level{display:flex}html.theme--documenter-dark .level>.level-item:not(.is-narrow){flex-grow:1}}html.theme--documenter-dark .level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}html.theme--documenter-dark .level-item .title,html.theme--documenter-dark .level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){html.theme--documenter-dark .level-item:not(:last-child){margin-bottom:.75rem}}html.theme--documenter-dark .level-left,html.theme--documenter-dark .level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .level-left .level-item.is-flexible,html.theme--documenter-dark .level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left .level-item:not(:last-child),html.theme--documenter-dark .level-right .level-item:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){html.theme--documenter-dark .level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left{display:flex}}html.theme--documenter-dark .level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-right{display:flex}}html.theme--documenter-dark .media{align-items:flex-start;display:flex;text-align:inherit}html.theme--documenter-dark .media .content:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .media .media{border-top:1px solid rgba(94,109,111,0.5);display:flex;padding-top:.75rem}html.theme--documenter-dark .media .media .content:not(:last-child),html.theme--documenter-dark .media .media .control:not(:last-child){margin-bottom:.5rem}html.theme--documenter-dark .media .media .media{padding-top:.5rem}html.theme--documenter-dark .media .media .media+.media{margin-top:.5rem}html.theme--documenter-dark .media+.media{border-top:1px solid rgba(94,109,111,0.5);margin-top:1rem;padding-top:1rem}html.theme--documenter-dark .media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}html.theme--documenter-dark .media-left,html.theme--documenter-dark .media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .media-left{margin-right:1rem}html.theme--documenter-dark .media-right{margin-left:1rem}html.theme--documenter-dark .media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .media-content{overflow-x:auto}}html.theme--documenter-dark .menu{font-size:1rem}html.theme--documenter-dark .menu.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}html.theme--documenter-dark .menu.is-medium{font-size:1.25rem}html.theme--documenter-dark .menu.is-large{font-size:1.5rem}html.theme--documenter-dark .menu-list{line-height:1.25}html.theme--documenter-dark .menu-list a{border-radius:3px;color:#fff;display:block;padding:0.5em 0.75em}html.theme--documenter-dark .menu-list a:hover{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .menu-list a.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .menu-list li ul{border-left:1px solid #5e6d6f;margin:.75em;padding-left:.75em}html.theme--documenter-dark .menu-label{color:#fff;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}html.theme--documenter-dark .menu-label:not(:first-child){margin-top:1em}html.theme--documenter-dark .menu-label:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .message{background-color:#282f2f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .message strong{color:currentColor}html.theme--documenter-dark .message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .message.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}html.theme--documenter-dark .message.is-medium{font-size:1.25rem}html.theme--documenter-dark .message.is-large{font-size:1.5rem}html.theme--documenter-dark .message.is-white{background-color:#fff}html.theme--documenter-dark .message.is-white .message-header{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .message.is-white .message-body{border-color:#fff}html.theme--documenter-dark .message.is-black{background-color:#fafafa}html.theme--documenter-dark .message.is-black .message-header{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .message.is-black .message-body{border-color:#0a0a0a}html.theme--documenter-dark .message.is-light{background-color:#f9fafb}html.theme--documenter-dark .message.is-light .message-header{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .message.is-light .message-body{border-color:#ecf0f1}html.theme--documenter-dark .message.is-dark,html.theme--documenter-dark .content kbd.message{background-color:#f9fafa}html.theme--documenter-dark .message.is-dark .message-header,html.theme--documenter-dark .content kbd.message .message-header{background-color:#282f2f;color:#fff}html.theme--documenter-dark .message.is-dark .message-body,html.theme--documenter-dark .content kbd.message .message-body{border-color:#282f2f}html.theme--documenter-dark .message.is-primary,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink{background-color:#f1f5f9}html.theme--documenter-dark .message.is-primary .message-header,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-header{background-color:#375a7f;color:#fff}html.theme--documenter-dark .message.is-primary .message-body,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-body{border-color:#375a7f;color:#4d7eb2}html.theme--documenter-dark .message.is-link{background-color:#edfdf9}html.theme--documenter-dark .message.is-link .message-header{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .message.is-link .message-body{border-color:#1abc9c;color:#15987e}html.theme--documenter-dark .message.is-info{background-color:#ebf7ff}html.theme--documenter-dark .message.is-info .message-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .message.is-info .message-body{border-color:#024c7d;color:#0e9dfb}html.theme--documenter-dark .message.is-success{background-color:#ebfff3}html.theme--documenter-dark .message.is-success .message-header{background-color:#008438;color:#fff}html.theme--documenter-dark .message.is-success .message-body{border-color:#008438;color:#00eb64}html.theme--documenter-dark .message.is-warning{background-color:#fffaeb}html.theme--documenter-dark .message.is-warning .message-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .message.is-warning .message-body{border-color:#ad8100;color:#d19c00}html.theme--documenter-dark .message.is-danger{background-color:#fdeeec}html.theme--documenter-dark .message.is-danger .message-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .message.is-danger .message-body{border-color:#9e1b0d;color:#ec311d}html.theme--documenter-dark .message-header{align-items:center;background-color:#fff;border-radius:.4em .4em 0 0;color:rgba(0,0,0,0.7);display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}html.theme--documenter-dark .message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}html.theme--documenter-dark .message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}html.theme--documenter-dark .message-body{border-color:#5e6d6f;border-radius:.4em;border-style:solid;border-width:0 0 0 4px;color:#fff;padding:1.25em 1.5em}html.theme--documenter-dark .message-body code,html.theme--documenter-dark .message-body pre{background-color:#fff}html.theme--documenter-dark .message-body pre code{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}html.theme--documenter-dark .modal.is-active{display:flex}html.theme--documenter-dark .modal-background{background-color:rgba(10,10,10,0.86)}html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}html.theme--documenter-dark .modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}html.theme--documenter-dark .modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}html.theme--documenter-dark .modal-card-head,html.theme--documenter-dark .modal-card-foot{align-items:center;background-color:#282f2f;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}html.theme--documenter-dark .modal-card-head{border-bottom:1px solid #5e6d6f;border-top-left-radius:8px;border-top-right-radius:8px}html.theme--documenter-dark .modal-card-title{color:#f2f2f2;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}html.theme--documenter-dark .modal-card-foot{border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid #5e6d6f}html.theme--documenter-dark .modal-card-foot .button:not(:last-child){margin-right:.5em}html.theme--documenter-dark .modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}html.theme--documenter-dark .navbar{background-color:#375a7f;min-height:4rem;position:relative;z-index:30}html.theme--documenter-dark .navbar.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-white .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}html.theme--documenter-dark .navbar.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-black .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}html.theme--documenter-dark .navbar.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-light .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}}html.theme--documenter-dark .navbar.is-dark,html.theme--documenter-dark .content kbd.navbar{background-color:#282f2f;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-burger,html.theme--documenter-dark .content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-dark .navbar-start>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-end>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#282f2f;color:#fff}}html.theme--documenter-dark .navbar.is-primary,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-burger,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-primary .navbar-start>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-end>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#375a7f;color:#fff}}html.theme--documenter-dark .navbar.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-link .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c;color:#fff}}html.theme--documenter-dark .navbar.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-info .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#024c7d;color:#fff}}html.theme--documenter-dark .navbar.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-success .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#008438;color:#fff}}html.theme--documenter-dark .navbar.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-warning .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ad8100;color:#fff}}html.theme--documenter-dark .navbar.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-danger .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#9e1b0d;color:#fff}}html.theme--documenter-dark .navbar>.container{align-items:stretch;display:flex;min-height:4rem;width:100%}html.theme--documenter-dark .navbar.has-shadow{box-shadow:0 2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-bottom,html.theme--documenter-dark .navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-top{top:0}html.theme--documenter-dark html.has-navbar-fixed-top,html.theme--documenter-dark body.has-navbar-fixed-top{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom,html.theme--documenter-dark body.has-navbar-fixed-bottom{padding-bottom:4rem}html.theme--documenter-dark .navbar-brand,html.theme--documenter-dark .navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:4rem}html.theme--documenter-dark .navbar-brand a.navbar-item:focus,html.theme--documenter-dark .navbar-brand a.navbar-item:hover{background-color:transparent}html.theme--documenter-dark .navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}html.theme--documenter-dark .navbar-burger{color:#fff;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:4rem;position:relative;width:4rem;margin-left:auto}html.theme--documenter-dark .navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}html.theme--documenter-dark .navbar-burger span:nth-child(1){top:calc(50% - 6px)}html.theme--documenter-dark .navbar-burger span:nth-child(2){top:calc(50% - 1px)}html.theme--documenter-dark .navbar-burger span:nth-child(3){top:calc(50% + 4px)}html.theme--documenter-dark .navbar-burger:hover{background-color:rgba(0,0,0,0.05)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(2){opacity:0}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}html.theme--documenter-dark .navbar-menu{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{color:#fff;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}html.theme--documenter-dark .navbar-item .icon:only-child,html.theme--documenter-dark .navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}html.theme--documenter-dark a.navbar-item,html.theme--documenter-dark .navbar-link{cursor:pointer}html.theme--documenter-dark a.navbar-item:focus,html.theme--documenter-dark a.navbar-item:focus-within,html.theme--documenter-dark a.navbar-item:hover,html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link:focus,html.theme--documenter-dark .navbar-link:focus-within,html.theme--documenter-dark .navbar-link:hover,html.theme--documenter-dark .navbar-link.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-item{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .navbar-item img{max-height:1.75rem}html.theme--documenter-dark .navbar-item.has-dropdown{padding:0}html.theme--documenter-dark .navbar-item.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-item.is-tab{border-bottom:1px solid transparent;min-height:4rem;padding-bottom:calc(0.5rem - 1px)}html.theme--documenter-dark .navbar-item.is-tab:focus,html.theme--documenter-dark .navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c}html.theme--documenter-dark .navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c;border-bottom-style:solid;border-bottom-width:3px;color:#1abc9c;padding-bottom:calc(0.5rem - 3px)}html.theme--documenter-dark .navbar-content{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-link:not(.is-arrowless){padding-right:2.5em}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after{border-color:#fff;margin-top:-0.375em;right:1.125em}html.theme--documenter-dark .navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}html.theme--documenter-dark .navbar-divider{background-color:rgba(0,0,0,0.2);border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar>.container{display:block}html.theme--documenter-dark .navbar-brand .navbar-item,html.theme--documenter-dark .navbar-tabs .navbar-item{align-items:center;display:flex}html.theme--documenter-dark .navbar-link::after{display:none}html.theme--documenter-dark .navbar-menu{background-color:#375a7f;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}html.theme--documenter-dark .navbar-menu.is-active{display:block}html.theme--documenter-dark .navbar.is-fixed-bottom-touch,html.theme--documenter-dark .navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-touch{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-touch{top:0}html.theme--documenter-dark .navbar.is-fixed-top .navbar-menu,html.theme--documenter-dark .navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 4rem);overflow:auto}html.theme--documenter-dark html.has-navbar-fixed-top-touch,html.theme--documenter-dark body.has-navbar-fixed-top-touch{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-touch,html.theme--documenter-dark body.has-navbar-fixed-bottom-touch{padding-bottom:4rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar,html.theme--documenter-dark .navbar-menu,html.theme--documenter-dark .navbar-start,html.theme--documenter-dark .navbar-end{align-items:stretch;display:flex}html.theme--documenter-dark .navbar{min-height:4rem}html.theme--documenter-dark .navbar.is-spaced{padding:1rem 2rem}html.theme--documenter-dark .navbar.is-spaced .navbar-start,html.theme--documenter-dark .navbar.is-spaced .navbar-end{align-items:center}html.theme--documenter-dark .navbar.is-spaced a.navbar-item,html.theme--documenter-dark .navbar.is-spaced .navbar-link{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent a.navbar-item:hover,html.theme--documenter-dark .navbar.is-transparent a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-transparent .navbar-link:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-link:hover,html.theme--documenter-dark .navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-burger{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{align-items:center;display:flex}html.theme--documenter-dark .navbar-item.has-dropdown{align-items:stretch}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:1px solid rgba(0,0,0,0.2);border-radius:8px 8px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}html.theme--documenter-dark .navbar-menu{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .navbar-start{justify-content:flex-start;margin-right:auto}html.theme--documenter-dark .navbar-end{justify-content:flex-end;margin-left:auto}html.theme--documenter-dark .navbar-dropdown{background-color:#375a7f;border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid rgba(0,0,0,0.2);box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}html.theme--documenter-dark .navbar-dropdown a.navbar-item{padding-right:3rem}html.theme--documenter-dark .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}.navbar.is-spaced html.theme--documenter-dark .navbar-dropdown,html.theme--documenter-dark .navbar-dropdown.is-boxed{border-radius:8px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}html.theme--documenter-dark .navbar-dropdown.is-right{left:auto;right:0}html.theme--documenter-dark .navbar-divider{display:block}html.theme--documenter-dark .navbar>.container .navbar-brand,html.theme--documenter-dark .container>.navbar .navbar-brand{margin-left:-.75rem}html.theme--documenter-dark .navbar>.container .navbar-menu,html.theme--documenter-dark .container>.navbar .navbar-menu{margin-right:-.75rem}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop,html.theme--documenter-dark .navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-desktop{top:0}html.theme--documenter-dark html.has-navbar-fixed-top-desktop,html.theme--documenter-dark body.has-navbar-fixed-top-desktop{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-desktop,html.theme--documenter-dark body.has-navbar-fixed-bottom-desktop{padding-bottom:4rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-top,html.theme--documenter-dark body.has-spaced-navbar-fixed-top{padding-top:6rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-bottom,html.theme--documenter-dark body.has-spaced-navbar-fixed-bottom{padding-bottom:6rem}html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link.is-active{color:#1abc9c}html.theme--documenter-dark a.navbar-item.is-active:not(:focus):not(:hover),html.theme--documenter-dark .navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}html.theme--documenter-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown.is-active .navbar-link{background-color:rgba(0,0,0,0)}}html.theme--documenter-dark .hero.is-fullheight-with-navbar{min-height:calc(100vh - 4rem)}html.theme--documenter-dark .pagination{font-size:1rem;margin:-.25rem}html.theme--documenter-dark .pagination.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}html.theme--documenter-dark .pagination.is-medium{font-size:1.25rem}html.theme--documenter-dark .pagination.is-large{font-size:1.5rem}html.theme--documenter-dark .pagination.is-rounded .pagination-previous,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,html.theme--documenter-dark .pagination.is-rounded .pagination-next,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}html.theme--documenter-dark .pagination.is-rounded .pagination-link,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}html.theme--documenter-dark .pagination,html.theme--documenter-dark .pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link{border-color:#5e6d6f;color:#1abc9c;min-width:2.5em}html.theme--documenter-dark .pagination-previous:hover,html.theme--documenter-dark .pagination-next:hover,html.theme--documenter-dark .pagination-link:hover{border-color:#8c9b9d;color:#1dd2af}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus{border-color:#8c9b9d}html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-previous.is-disabled,html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-next.is-disabled,html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-link.is-disabled{background-color:#5e6d6f;border-color:#5e6d6f;box-shadow:none;color:#fff;opacity:0.5}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}html.theme--documenter-dark .pagination-link.is-current{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .pagination-ellipsis{color:#8c9b9d;pointer-events:none}html.theme--documenter-dark .pagination-list{flex-wrap:wrap}html.theme--documenter-dark .pagination-list li{list-style:none}@media screen and (max-width: 768px){html.theme--documenter-dark .pagination{flex-wrap:wrap}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination-previous{order:2}html.theme--documenter-dark .pagination-next{order:3}html.theme--documenter-dark .pagination{justify-content:space-between;margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination.is-centered .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-centered .pagination-list{justify-content:center;order:2}html.theme--documenter-dark .pagination.is-centered .pagination-next{order:3}html.theme--documenter-dark .pagination.is-right .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-right .pagination-next{order:2}html.theme--documenter-dark .pagination.is-right .pagination-list{justify-content:flex-end;order:3}}html.theme--documenter-dark .panel{border-radius:8px;box-shadow:#171717;font-size:1rem}html.theme--documenter-dark .panel:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}html.theme--documenter-dark .panel.is-white .panel-block.is-active .panel-icon{color:#fff}html.theme--documenter-dark .panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}html.theme--documenter-dark .panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}html.theme--documenter-dark .panel.is-light .panel-heading{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .panel.is-light .panel-tabs a.is-active{border-bottom-color:#ecf0f1}html.theme--documenter-dark .panel.is-light .panel-block.is-active .panel-icon{color:#ecf0f1}html.theme--documenter-dark .panel.is-dark .panel-heading,html.theme--documenter-dark .content kbd.panel .panel-heading{background-color:#282f2f;color:#fff}html.theme--documenter-dark .panel.is-dark .panel-tabs a.is-active,html.theme--documenter-dark .content kbd.panel .panel-tabs a.is-active{border-bottom-color:#282f2f}html.theme--documenter-dark .panel.is-dark .panel-block.is-active .panel-icon,html.theme--documenter-dark .content kbd.panel .panel-block.is-active .panel-icon{color:#282f2f}html.theme--documenter-dark .panel.is-primary .panel-heading,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#375a7f;color:#fff}html.theme--documenter-dark .panel.is-primary .panel-tabs a.is-active,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#375a7f}html.theme--documenter-dark .panel.is-primary .panel-block.is-active .panel-icon,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#375a7f}html.theme--documenter-dark .panel.is-link .panel-heading{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .panel.is-link .panel-tabs a.is-active{border-bottom-color:#1abc9c}html.theme--documenter-dark .panel.is-link .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel.is-info .panel-heading{background-color:#024c7d;color:#fff}html.theme--documenter-dark .panel.is-info .panel-tabs a.is-active{border-bottom-color:#024c7d}html.theme--documenter-dark .panel.is-info .panel-block.is-active .panel-icon{color:#024c7d}html.theme--documenter-dark .panel.is-success .panel-heading{background-color:#008438;color:#fff}html.theme--documenter-dark .panel.is-success .panel-tabs a.is-active{border-bottom-color:#008438}html.theme--documenter-dark .panel.is-success .panel-block.is-active .panel-icon{color:#008438}html.theme--documenter-dark .panel.is-warning .panel-heading{background-color:#ad8100;color:#fff}html.theme--documenter-dark .panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ad8100}html.theme--documenter-dark .panel.is-warning .panel-block.is-active .panel-icon{color:#ad8100}html.theme--documenter-dark .panel.is-danger .panel-heading{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .panel.is-danger .panel-tabs a.is-active{border-bottom-color:#9e1b0d}html.theme--documenter-dark .panel.is-danger .panel-block.is-active .panel-icon{color:#9e1b0d}html.theme--documenter-dark .panel-tabs:not(:last-child),html.theme--documenter-dark .panel-block:not(:last-child){border-bottom:1px solid #ededed}html.theme--documenter-dark .panel-heading{background-color:#343c3d;border-radius:8px 8px 0 0;color:#f2f2f2;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}html.theme--documenter-dark .panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}html.theme--documenter-dark .panel-tabs a{border-bottom:1px solid #5e6d6f;margin-bottom:-1px;padding:0.5em}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#343c3d;color:#17a689}html.theme--documenter-dark .panel-list a{color:#fff}html.theme--documenter-dark .panel-list a:hover{color:#1abc9c}html.theme--documenter-dark .panel-block{align-items:center;color:#f2f2f2;display:flex;justify-content:flex-start;padding:0.5em 0.75em}html.theme--documenter-dark .panel-block input[type="checkbox"]{margin-right:.75em}html.theme--documenter-dark .panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}html.theme--documenter-dark .panel-block.is-wrapped{flex-wrap:wrap}html.theme--documenter-dark .panel-block.is-active{border-left-color:#1abc9c;color:#17a689}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel-block:last-child{border-bottom-left-radius:8px;border-bottom-right-radius:8px}html.theme--documenter-dark a.panel-block,html.theme--documenter-dark label.panel-block{cursor:pointer}html.theme--documenter-dark a.panel-block:hover,html.theme--documenter-dark label.panel-block:hover{background-color:#282f2f}html.theme--documenter-dark .panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#fff;margin-right:.75em}html.theme--documenter-dark .panel-icon .fa{font-size:inherit;line-height:inherit}html.theme--documenter-dark .tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}html.theme--documenter-dark .tabs a{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;color:#fff;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}html.theme--documenter-dark .tabs a:hover{border-bottom-color:#f2f2f2;color:#f2f2f2}html.theme--documenter-dark .tabs li{display:block}html.theme--documenter-dark .tabs li.is-active a{border-bottom-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .tabs ul{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}html.theme--documenter-dark .tabs ul.is-left{padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}html.theme--documenter-dark .tabs .icon:first-child{margin-right:.5em}html.theme--documenter-dark .tabs .icon:last-child{margin-left:.5em}html.theme--documenter-dark .tabs.is-centered ul{justify-content:center}html.theme--documenter-dark .tabs.is-right ul{justify-content:flex-end}html.theme--documenter-dark .tabs.is-boxed a{border:1px solid transparent;border-radius:.4em .4em 0 0}html.theme--documenter-dark .tabs.is-boxed a:hover{background-color:#282f2f;border-bottom-color:#5e6d6f}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#fff;border-color:#5e6d6f;border-bottom-color:rgba(0,0,0,0) !important}html.theme--documenter-dark .tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .tabs.is-toggle a{border-color:#5e6d6f;border-style:solid;border-width:1px;margin-bottom:0;position:relative}html.theme--documenter-dark .tabs.is-toggle a:hover{background-color:#282f2f;border-color:#8c9b9d;z-index:2}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .tabs.is-toggle li:first-child a{border-top-left-radius:.4em;border-bottom-left-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li:last-child a{border-top-right-radius:.4em;border-bottom-right-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li.is-active a{background-color:#1abc9c;border-color:#1abc9c;color:#fff;z-index:1}html.theme--documenter-dark .tabs.is-toggle ul{border-bottom:none}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}html.theme--documenter-dark .tabs.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}html.theme--documenter-dark .tabs.is-medium{font-size:1.25rem}html.theme--documenter-dark .tabs.is-large{font-size:1.5rem}html.theme--documenter-dark .column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>html.theme--documenter-dark .column.is-narrow{flex:none;width:unset}.columns.is-mobile>html.theme--documenter-dark .column.is-full{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-half{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-half{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-0{flex:none;width:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-0{margin-left:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-3{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-3{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-6{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-6{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-9{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-9{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-12{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){html.theme--documenter-dark .column.is-narrow-mobile{flex:none;width:unset}html.theme--documenter-dark .column.is-full-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-mobile{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-mobile{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-mobile{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-mobile{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-mobile{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-mobile{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-mobile{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-mobile{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-mobile{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-mobile{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-mobile{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-mobile{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-mobile{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-mobile{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-mobile{margin-left:80%}html.theme--documenter-dark .column.is-0-mobile{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-mobile{margin-left:0%}html.theme--documenter-dark .column.is-1-mobile{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-mobile{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-mobile{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-mobile{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-mobile{margin-left:25%}html.theme--documenter-dark .column.is-4-mobile{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-mobile{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-mobile{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-mobile{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-mobile{margin-left:50%}html.theme--documenter-dark .column.is-7-mobile{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-mobile{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-mobile{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-mobile{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-mobile{margin-left:75%}html.theme--documenter-dark .column.is-10-mobile{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-mobile{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-mobile{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-mobile{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .column.is-narrow,html.theme--documenter-dark .column.is-narrow-tablet{flex:none;width:unset}html.theme--documenter-dark .column.is-full,html.theme--documenter-dark .column.is-full-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters,html.theme--documenter-dark .column.is-three-quarters-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds,html.theme--documenter-dark .column.is-two-thirds-tablet{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half,html.theme--documenter-dark .column.is-half-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third,html.theme--documenter-dark .column.is-one-third-tablet{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter,html.theme--documenter-dark .column.is-one-quarter-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth,html.theme--documenter-dark .column.is-one-fifth-tablet{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths,html.theme--documenter-dark .column.is-two-fifths-tablet{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths,html.theme--documenter-dark .column.is-three-fifths-tablet{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths,html.theme--documenter-dark .column.is-four-fifths-tablet{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters,html.theme--documenter-dark .column.is-offset-three-quarters-tablet{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds,html.theme--documenter-dark .column.is-offset-two-thirds-tablet{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half,html.theme--documenter-dark .column.is-offset-half-tablet{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third,html.theme--documenter-dark .column.is-offset-one-third-tablet{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter,html.theme--documenter-dark .column.is-offset-one-quarter-tablet{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth,html.theme--documenter-dark .column.is-offset-one-fifth-tablet{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths,html.theme--documenter-dark .column.is-offset-two-fifths-tablet{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths,html.theme--documenter-dark .column.is-offset-three-fifths-tablet{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths,html.theme--documenter-dark .column.is-offset-four-fifths-tablet{margin-left:80%}html.theme--documenter-dark .column.is-0,html.theme--documenter-dark .column.is-0-tablet{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0,html.theme--documenter-dark .column.is-offset-0-tablet{margin-left:0%}html.theme--documenter-dark .column.is-1,html.theme--documenter-dark .column.is-1-tablet{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1,html.theme--documenter-dark .column.is-offset-1-tablet{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2,html.theme--documenter-dark .column.is-2-tablet{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2,html.theme--documenter-dark .column.is-offset-2-tablet{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3,html.theme--documenter-dark .column.is-3-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3,html.theme--documenter-dark .column.is-offset-3-tablet{margin-left:25%}html.theme--documenter-dark .column.is-4,html.theme--documenter-dark .column.is-4-tablet{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4,html.theme--documenter-dark .column.is-offset-4-tablet{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5,html.theme--documenter-dark .column.is-5-tablet{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5,html.theme--documenter-dark .column.is-offset-5-tablet{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6,html.theme--documenter-dark .column.is-6-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6,html.theme--documenter-dark .column.is-offset-6-tablet{margin-left:50%}html.theme--documenter-dark .column.is-7,html.theme--documenter-dark .column.is-7-tablet{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7,html.theme--documenter-dark .column.is-offset-7-tablet{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8,html.theme--documenter-dark .column.is-8-tablet{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8,html.theme--documenter-dark .column.is-offset-8-tablet{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9,html.theme--documenter-dark .column.is-9-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9,html.theme--documenter-dark .column.is-offset-9-tablet{margin-left:75%}html.theme--documenter-dark .column.is-10,html.theme--documenter-dark .column.is-10-tablet{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10,html.theme--documenter-dark .column.is-offset-10-tablet{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11,html.theme--documenter-dark .column.is-11-tablet{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11,html.theme--documenter-dark .column.is-offset-11-tablet{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12,html.theme--documenter-dark .column.is-12-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12,html.theme--documenter-dark .column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){html.theme--documenter-dark .column.is-narrow-touch{flex:none;width:unset}html.theme--documenter-dark .column.is-full-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-touch{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-touch{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-touch{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-touch{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-touch{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-touch{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-touch{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-touch{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-touch{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-touch{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-touch{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-touch{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-touch{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-touch{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-touch{margin-left:80%}html.theme--documenter-dark .column.is-0-touch{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-touch{margin-left:0%}html.theme--documenter-dark .column.is-1-touch{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-touch{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-touch{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-touch{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-touch{margin-left:25%}html.theme--documenter-dark .column.is-4-touch{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-touch{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-touch{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-touch{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-touch{margin-left:50%}html.theme--documenter-dark .column.is-7-touch{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-touch{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-touch{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-touch{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-touch{margin-left:75%}html.theme--documenter-dark .column.is-10-touch{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-touch{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-touch{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-touch{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){html.theme--documenter-dark .column.is-narrow-desktop{flex:none;width:unset}html.theme--documenter-dark .column.is-full-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-desktop{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-desktop{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-desktop{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-desktop{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-desktop{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-desktop{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-desktop{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-desktop{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-desktop{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-desktop{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-desktop{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-desktop{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-desktop{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-desktop{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-desktop{margin-left:80%}html.theme--documenter-dark .column.is-0-desktop{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-desktop{margin-left:0%}html.theme--documenter-dark .column.is-1-desktop{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-desktop{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-desktop{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-desktop{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-desktop{margin-left:25%}html.theme--documenter-dark .column.is-4-desktop{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-desktop{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-desktop{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-desktop{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-desktop{margin-left:50%}html.theme--documenter-dark .column.is-7-desktop{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-desktop{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-desktop{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-desktop{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-desktop{margin-left:75%}html.theme--documenter-dark .column.is-10-desktop{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-desktop{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-desktop{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-desktop{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){html.theme--documenter-dark .column.is-narrow-widescreen{flex:none;width:unset}html.theme--documenter-dark .column.is-full-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-widescreen{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-widescreen{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-widescreen{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-widescreen{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-widescreen{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-widescreen{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-widescreen{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-widescreen{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-widescreen{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-widescreen{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-widescreen{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-widescreen{margin-left:80%}html.theme--documenter-dark .column.is-0-widescreen{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-widescreen{margin-left:0%}html.theme--documenter-dark .column.is-1-widescreen{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-widescreen{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-widescreen{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-widescreen{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-4-widescreen{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-widescreen{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-widescreen{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-widescreen{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-7-widescreen{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-widescreen{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-widescreen{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-widescreen{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-10-widescreen{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-widescreen{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-widescreen{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-widescreen{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){html.theme--documenter-dark .column.is-narrow-fullhd{flex:none;width:unset}html.theme--documenter-dark .column.is-full-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-fullhd{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-fullhd{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-fullhd{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-fullhd{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-fullhd{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-fullhd{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-fullhd{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-fullhd{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-fullhd{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-fullhd{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-fullhd{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-fullhd{margin-left:80%}html.theme--documenter-dark .column.is-0-fullhd{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-fullhd{margin-left:0%}html.theme--documenter-dark .column.is-1-fullhd{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-fullhd{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-fullhd{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-fullhd{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-4-fullhd{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-fullhd{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-fullhd{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-fullhd{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-7-fullhd{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-fullhd{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-fullhd{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-fullhd{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-10-fullhd{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-fullhd{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-fullhd{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-fullhd{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-fullhd{margin-left:100%}}html.theme--documenter-dark .columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .columns:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}html.theme--documenter-dark .columns.is-centered{justify-content:center}html.theme--documenter-dark .columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}html.theme--documenter-dark .columns.is-gapless>.column{margin:0;padding:0 !important}html.theme--documenter-dark .columns.is-gapless:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .columns.is-gapless:last-child{margin-bottom:0}html.theme--documenter-dark .columns.is-mobile{display:flex}html.theme--documenter-dark .columns.is-multiline{flex-wrap:wrap}html.theme--documenter-dark .columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-desktop{display:flex}}html.theme--documenter-dark .columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}html.theme--documenter-dark .columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}html.theme--documenter-dark .columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-0-fullhd{--columnGap: 0rem}}html.theme--documenter-dark .columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-1-fullhd{--columnGap: .25rem}}html.theme--documenter-dark .columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-2-fullhd{--columnGap: .5rem}}html.theme--documenter-dark .columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-3-fullhd{--columnGap: .75rem}}html.theme--documenter-dark .columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-4-fullhd{--columnGap: 1rem}}html.theme--documenter-dark .columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}html.theme--documenter-dark .columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}html.theme--documenter-dark .columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}html.theme--documenter-dark .columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-8-fullhd{--columnGap: 2rem}}html.theme--documenter-dark .tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}html.theme--documenter-dark .tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .tile.is-ancestor:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .tile.is-ancestor:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .tile.is-child{margin:0 !important}html.theme--documenter-dark .tile.is-parent{padding:.75rem}html.theme--documenter-dark .tile.is-vertical{flex-direction:column}html.theme--documenter-dark .tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{html.theme--documenter-dark .tile:not(.is-child){display:flex}html.theme--documenter-dark .tile.is-1{flex:none;width:8.33333337%}html.theme--documenter-dark .tile.is-2{flex:none;width:16.66666674%}html.theme--documenter-dark .tile.is-3{flex:none;width:25%}html.theme--documenter-dark .tile.is-4{flex:none;width:33.33333337%}html.theme--documenter-dark .tile.is-5{flex:none;width:41.66666674%}html.theme--documenter-dark .tile.is-6{flex:none;width:50%}html.theme--documenter-dark .tile.is-7{flex:none;width:58.33333337%}html.theme--documenter-dark .tile.is-8{flex:none;width:66.66666674%}html.theme--documenter-dark .tile.is-9{flex:none;width:75%}html.theme--documenter-dark .tile.is-10{flex:none;width:83.33333337%}html.theme--documenter-dark .tile.is-11{flex:none;width:91.66666674%}html.theme--documenter-dark .tile.is-12{flex:none;width:100%}}html.theme--documenter-dark .hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}html.theme--documenter-dark .hero .navbar{background:none}html.theme--documenter-dark .hero .tabs ul{border-bottom:none}html.theme--documenter-dark .hero.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-white strong{color:inherit}html.theme--documenter-dark .hero.is-white .title{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .subtitle{color:rgba(10,10,10,0.9)}html.theme--documenter-dark .hero.is-white .subtitle a:not(.button),html.theme--documenter-dark .hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-white .navbar-menu{background-color:#fff}}html.theme--documenter-dark .hero.is-white .navbar-item,html.theme--documenter-dark .hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}html.theme--documenter-dark .hero.is-white a.navbar-item:hover,html.theme--documenter-dark .hero.is-white a.navbar-item.is-active,html.theme--documenter-dark .hero.is-white .navbar-link:hover,html.theme--documenter-dark .hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}html.theme--documenter-dark .hero.is-white .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}html.theme--documenter-dark .hero.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-black strong{color:inherit}html.theme--documenter-dark .hero.is-black .title{color:#fff}html.theme--documenter-dark .hero.is-black .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-black .subtitle a:not(.button),html.theme--documenter-dark .hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-black .navbar-menu{background-color:#0a0a0a}}html.theme--documenter-dark .hero.is-black .navbar-item,html.theme--documenter-dark .hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-black a.navbar-item:hover,html.theme--documenter-dark .hero.is-black a.navbar-item.is-active,html.theme--documenter-dark .hero.is-black .navbar-link:hover,html.theme--documenter-dark .hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .hero.is-black .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-black .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}html.theme--documenter-dark .hero.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-light strong{color:inherit}html.theme--documenter-dark .hero.is-light .title{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .subtitle{color:rgba(0,0,0,0.9)}html.theme--documenter-dark .hero.is-light .subtitle a:not(.button),html.theme--documenter-dark .hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-light .navbar-menu{background-color:#ecf0f1}}html.theme--documenter-dark .hero.is-light .navbar-item,html.theme--documenter-dark .hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a.navbar-item:hover,html.theme--documenter-dark .hero.is-light a.navbar-item.is-active,html.theme--documenter-dark .hero.is-light .navbar-link:hover,html.theme--documenter-dark .hero.is-light .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}html.theme--documenter-dark .hero.is-light .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-light .tabs li.is-active a{color:#ecf0f1 !important;opacity:1}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .hero.is-light.is-bold{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}}html.theme--documenter-dark .hero.is-dark,html.theme--documenter-dark .content kbd.hero{background-color:#282f2f;color:#fff}html.theme--documenter-dark .hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-dark strong,html.theme--documenter-dark .content kbd.hero strong{color:inherit}html.theme--documenter-dark .hero.is-dark .title,html.theme--documenter-dark .content kbd.hero .title{color:#fff}html.theme--documenter-dark .hero.is-dark .subtitle,html.theme--documenter-dark .content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-dark .subtitle a:not(.button),html.theme--documenter-dark .content kbd.hero .subtitle a:not(.button),html.theme--documenter-dark .hero.is-dark .subtitle strong,html.theme--documenter-dark .content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-dark .navbar-menu,html.theme--documenter-dark .content kbd.hero .navbar-menu{background-color:#282f2f}}html.theme--documenter-dark .hero.is-dark .navbar-item,html.theme--documenter-dark .content kbd.hero .navbar-item,html.theme--documenter-dark .hero.is-dark .navbar-link,html.theme--documenter-dark .content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-dark a.navbar-item:hover,html.theme--documenter-dark .content kbd.hero a.navbar-item:hover,html.theme--documenter-dark .hero.is-dark a.navbar-item.is-active,html.theme--documenter-dark .content kbd.hero a.navbar-item.is-active,html.theme--documenter-dark .hero.is-dark .navbar-link:hover,html.theme--documenter-dark .content kbd.hero .navbar-link:hover,html.theme--documenter-dark .hero.is-dark .navbar-link.is-active,html.theme--documenter-dark .content kbd.hero .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .hero.is-dark .tabs a,html.theme--documenter-dark .content kbd.hero .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-dark .tabs a:hover,html.theme--documenter-dark .content kbd.hero .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-dark .tabs li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs li.is-active a{color:#282f2f !important;opacity:1}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#282f2f}html.theme--documenter-dark .hero.is-dark.is-bold,html.theme--documenter-dark .content kbd.hero.is-bold{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-dark.is-bold .navbar-menu,html.theme--documenter-dark .content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}}html.theme--documenter-dark .hero.is-primary,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-primary strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink strong{color:inherit}html.theme--documenter-dark .hero.is-primary .title,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .title{color:#fff}html.theme--documenter-dark .hero.is-primary .subtitle,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-primary .subtitle a:not(.button),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),html.theme--documenter-dark .hero.is-primary .subtitle strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-primary .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#375a7f}}html.theme--documenter-dark .hero.is-primary .navbar-item,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-item,html.theme--documenter-dark .hero.is-primary .navbar-link,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-primary a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,html.theme--documenter-dark .hero.is-primary a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,html.theme--documenter-dark .hero.is-primary .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link:hover,html.theme--documenter-dark .hero.is-primary .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .hero.is-primary .tabs a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-primary .tabs a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-primary .tabs li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#375a7f !important;opacity:1}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#375a7f}html.theme--documenter-dark .hero.is-primary.is-bold,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-primary.is-bold .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}}html.theme--documenter-dark .hero.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-link strong{color:inherit}html.theme--documenter-dark .hero.is-link .title{color:#fff}html.theme--documenter-dark .hero.is-link .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-link .subtitle a:not(.button),html.theme--documenter-dark .hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-link .navbar-menu{background-color:#1abc9c}}html.theme--documenter-dark .hero.is-link .navbar-item,html.theme--documenter-dark .hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-link a.navbar-item:hover,html.theme--documenter-dark .hero.is-link a.navbar-item.is-active,html.theme--documenter-dark .hero.is-link .navbar-link:hover,html.theme--documenter-dark .hero.is-link .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .hero.is-link .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-link .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-link .tabs li.is-active a{color:#1abc9c !important;opacity:1}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#1abc9c}html.theme--documenter-dark .hero.is-link.is-bold{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}}html.theme--documenter-dark .hero.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-info strong{color:inherit}html.theme--documenter-dark .hero.is-info .title{color:#fff}html.theme--documenter-dark .hero.is-info .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-info .subtitle a:not(.button),html.theme--documenter-dark .hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-info .navbar-menu{background-color:#024c7d}}html.theme--documenter-dark .hero.is-info .navbar-item,html.theme--documenter-dark .hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-info a.navbar-item:hover,html.theme--documenter-dark .hero.is-info a.navbar-item.is-active,html.theme--documenter-dark .hero.is-info .navbar-link:hover,html.theme--documenter-dark .hero.is-info .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .hero.is-info .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-info .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-info .tabs li.is-active a{color:#024c7d !important;opacity:1}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#024c7d}html.theme--documenter-dark .hero.is-info.is-bold{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}}html.theme--documenter-dark .hero.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-success strong{color:inherit}html.theme--documenter-dark .hero.is-success .title{color:#fff}html.theme--documenter-dark .hero.is-success .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-success .subtitle a:not(.button),html.theme--documenter-dark .hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-success .navbar-menu{background-color:#008438}}html.theme--documenter-dark .hero.is-success .navbar-item,html.theme--documenter-dark .hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-success a.navbar-item:hover,html.theme--documenter-dark .hero.is-success a.navbar-item.is-active,html.theme--documenter-dark .hero.is-success .navbar-link:hover,html.theme--documenter-dark .hero.is-success .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .hero.is-success .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-success .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-success .tabs li.is-active a{color:#008438 !important;opacity:1}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#008438}html.theme--documenter-dark .hero.is-success.is-bold{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}}html.theme--documenter-dark .hero.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-warning strong{color:inherit}html.theme--documenter-dark .hero.is-warning .title{color:#fff}html.theme--documenter-dark .hero.is-warning .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-warning .subtitle a:not(.button),html.theme--documenter-dark .hero.is-warning .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-warning .navbar-menu{background-color:#ad8100}}html.theme--documenter-dark .hero.is-warning .navbar-item,html.theme--documenter-dark .hero.is-warning .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-warning a.navbar-item:hover,html.theme--documenter-dark .hero.is-warning a.navbar-item.is-active,html.theme--documenter-dark .hero.is-warning .navbar-link:hover,html.theme--documenter-dark .hero.is-warning .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .hero.is-warning .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-warning .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-warning .tabs li.is-active a{color:#ad8100 !important;opacity:1}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#ad8100}html.theme--documenter-dark .hero.is-warning.is-bold{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}}html.theme--documenter-dark .hero.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-danger strong{color:inherit}html.theme--documenter-dark .hero.is-danger .title{color:#fff}html.theme--documenter-dark .hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-danger .subtitle a:not(.button),html.theme--documenter-dark .hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-danger .navbar-menu{background-color:#9e1b0d}}html.theme--documenter-dark .hero.is-danger .navbar-item,html.theme--documenter-dark .hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-danger a.navbar-item:hover,html.theme--documenter-dark .hero.is-danger a.navbar-item.is-active,html.theme--documenter-dark .hero.is-danger .navbar-link:hover,html.theme--documenter-dark .hero.is-danger .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .hero.is-danger .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-danger .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-danger .tabs li.is-active a{color:#9e1b0d !important;opacity:1}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#9e1b0d}html.theme--documenter-dark .hero.is-danger.is-bold{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}}html.theme--documenter-dark .hero.is-small .hero-body,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-large .hero-body{padding:18rem 6rem}}html.theme--documenter-dark .hero.is-halfheight .hero-body,html.theme--documenter-dark .hero.is-fullheight .hero-body,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}html.theme--documenter-dark .hero.is-halfheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .hero.is-halfheight{min-height:50vh}html.theme--documenter-dark .hero.is-fullheight{min-height:100vh}html.theme--documenter-dark .hero-video{overflow:hidden}html.theme--documenter-dark .hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}html.theme--documenter-dark .hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-video{display:none}}html.theme--documenter-dark .hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-buttons .button{display:flex}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-buttons{display:flex;justify-content:center}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-right:1.5rem}}html.theme--documenter-dark .hero-head,html.theme--documenter-dark .hero-foot{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-body{padding:3rem 3rem}}html.theme--documenter-dark .section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){html.theme--documenter-dark .section{padding:3rem 3rem}html.theme--documenter-dark .section.is-medium{padding:9rem 4.5rem}html.theme--documenter-dark .section.is-large{padding:18rem 6rem}}html.theme--documenter-dark .footer{background-color:#282f2f;padding:3rem 1.5rem 6rem}html.theme--documenter-dark hr{height:1px}html.theme--documenter-dark h6{text-transform:uppercase;letter-spacing:0.5px}html.theme--documenter-dark .hero{background-color:#343c3d}html.theme--documenter-dark a{transition:all 200ms ease}html.theme--documenter-dark .button{transition:all 200ms ease;border-width:1px;color:#fff}html.theme--documenter-dark .button.is-active,html.theme--documenter-dark .button.is-focused,html.theme--documenter-dark .button:active,html.theme--documenter-dark .button:focus{box-shadow:0 0 0 2px rgba(140,155,157,0.5)}html.theme--documenter-dark .button.is-white.is-hovered,html.theme--documenter-dark .button.is-white:hover{background-color:#fff}html.theme--documenter-dark .button.is-white.is-active,html.theme--documenter-dark .button.is-white.is-focused,html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white:focus{border-color:#fff;box-shadow:0 0 0 2px rgba(255,255,255,0.5)}html.theme--documenter-dark .button.is-black.is-hovered,html.theme--documenter-dark .button.is-black:hover{background-color:#1d1d1d}html.theme--documenter-dark .button.is-black.is-active,html.theme--documenter-dark .button.is-black.is-focused,html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black:focus{border-color:#0a0a0a;box-shadow:0 0 0 2px rgba(10,10,10,0.5)}html.theme--documenter-dark .button.is-light.is-hovered,html.theme--documenter-dark .button.is-light:hover{background-color:#fff}html.theme--documenter-dark .button.is-light.is-active,html.theme--documenter-dark .button.is-light.is-focused,html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light:focus{border-color:#ecf0f1;box-shadow:0 0 0 2px rgba(236,240,241,0.5)}html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered,html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover{background-color:#3a4344}html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused,html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus{border-color:#282f2f;box-shadow:0 0 0 2px rgba(40,47,47,0.5)}html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover{background-color:#436d9a}html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink,html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus{border-color:#375a7f;box-shadow:0 0 0 2px rgba(55,90,127,0.5)}html.theme--documenter-dark .button.is-link.is-hovered,html.theme--documenter-dark .button.is-link:hover{background-color:#1fdeb8}html.theme--documenter-dark .button.is-link.is-active,html.theme--documenter-dark .button.is-link.is-focused,html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link:focus{border-color:#1abc9c;box-shadow:0 0 0 2px rgba(26,188,156,0.5)}html.theme--documenter-dark .button.is-info.is-hovered,html.theme--documenter-dark .button.is-info:hover{background-color:#0363a3}html.theme--documenter-dark .button.is-info.is-active,html.theme--documenter-dark .button.is-info.is-focused,html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info:focus{border-color:#024c7d;box-shadow:0 0 0 2px rgba(2,76,125,0.5)}html.theme--documenter-dark .button.is-success.is-hovered,html.theme--documenter-dark .button.is-success:hover{background-color:#00aa48}html.theme--documenter-dark .button.is-success.is-active,html.theme--documenter-dark .button.is-success.is-focused,html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success:focus{border-color:#008438;box-shadow:0 0 0 2px rgba(0,132,56,0.5)}html.theme--documenter-dark .button.is-warning.is-hovered,html.theme--documenter-dark .button.is-warning:hover{background-color:#d39e00}html.theme--documenter-dark .button.is-warning.is-active,html.theme--documenter-dark .button.is-warning.is-focused,html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning:focus{border-color:#ad8100;box-shadow:0 0 0 2px rgba(173,129,0,0.5)}html.theme--documenter-dark .button.is-danger.is-hovered,html.theme--documenter-dark .button.is-danger:hover{background-color:#c12110}html.theme--documenter-dark .button.is-danger.is-active,html.theme--documenter-dark .button.is-danger.is-focused,html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger:focus{border-color:#9e1b0d;box-shadow:0 0 0 2px rgba(158,27,13,0.5)}html.theme--documenter-dark .label{color:#dbdee0}html.theme--documenter-dark .button,html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .select,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea{height:2.5em}html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .textarea{transition:all 200ms ease;box-shadow:none;border-width:1px;padding-left:1em;padding-right:1em}html.theme--documenter-dark .select:after,html.theme--documenter-dark .select select{border-width:1px}html.theme--documenter-dark .control.has-addons .button,html.theme--documenter-dark .control.has-addons .input,html.theme--documenter-dark .control.has-addons #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-addons form.docs-search>input,html.theme--documenter-dark .control.has-addons .select{margin-right:-1px}html.theme--documenter-dark .notification{background-color:#343c3d}html.theme--documenter-dark .card{box-shadow:none;border:1px solid #343c3d;background-color:#282f2f;border-radius:.4em}html.theme--documenter-dark .card .card-image img{border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-header{box-shadow:none;background-color:rgba(18,18,18,0.2);border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-footer{background-color:rgba(18,18,18,0.2)}html.theme--documenter-dark .card .card-footer,html.theme--documenter-dark .card .card-footer-item{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .notification.is-white a:not(.button){color:#0a0a0a;text-decoration:underline}html.theme--documenter-dark .notification.is-black a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-light a:not(.button){color:rgba(0,0,0,0.7);text-decoration:underline}html.theme--documenter-dark .notification.is-dark a:not(.button),html.theme--documenter-dark .content kbd.notification a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-primary a:not(.button),html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-link a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-info a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-success a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-warning a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-danger a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .tag,html.theme--documenter-dark .content kbd,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{border-radius:.4em}html.theme--documenter-dark .menu-list a{transition:all 300ms ease}html.theme--documenter-dark .modal-card-body{background-color:#282f2f}html.theme--documenter-dark .modal-card-foot,html.theme--documenter-dark .modal-card-head{border-color:#343c3d}html.theme--documenter-dark .message-header{font-weight:700;background-color:#343c3d;color:#fff}html.theme--documenter-dark .message-body{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .navbar{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent{background:none}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar .navbar-menu{background-color:#375a7f;border-radius:0 0 .4em .4em}}html.theme--documenter-dark .hero .navbar,html.theme--documenter-dark body>.navbar{border-radius:0}html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous{border-width:1px}html.theme--documenter-dark .panel-block,html.theme--documenter-dark .panel-heading,html.theme--documenter-dark .panel-tabs{border-width:1px}html.theme--documenter-dark .panel-block:first-child,html.theme--documenter-dark .panel-heading:first-child,html.theme--documenter-dark .panel-tabs:first-child{border-top-width:1px}html.theme--documenter-dark .panel-heading{font-weight:700}html.theme--documenter-dark .panel-tabs a{border-width:1px;margin-bottom:-1px}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#17a689}html.theme--documenter-dark .panel-block:hover{color:#1dd2af}html.theme--documenter-dark .panel-block:hover .panel-icon{color:#1dd2af}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#17a689}html.theme--documenter-dark .tabs a{border-bottom-width:1px;margin-bottom:-1px}html.theme--documenter-dark .tabs ul{border-bottom-width:1px}html.theme--documenter-dark .tabs.is-boxed a{border-width:1px}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#1f2424}html.theme--documenter-dark .tabs.is-toggle li a{border-width:1px;margin-bottom:0}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .hero.is-white .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-black .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-light .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-dark .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .content kbd.hero .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-primary .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-link .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-info .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-success .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-warning .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-danger .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark h1 .docs-heading-anchor,html.theme--documenter-dark h1 .docs-heading-anchor:hover,html.theme--documenter-dark h1 .docs-heading-anchor:visited,html.theme--documenter-dark h2 .docs-heading-anchor,html.theme--documenter-dark h2 .docs-heading-anchor:hover,html.theme--documenter-dark h2 .docs-heading-anchor:visited,html.theme--documenter-dark h3 .docs-heading-anchor,html.theme--documenter-dark h3 .docs-heading-anchor:hover,html.theme--documenter-dark h3 .docs-heading-anchor:visited,html.theme--documenter-dark h4 .docs-heading-anchor,html.theme--documenter-dark h4 .docs-heading-anchor:hover,html.theme--documenter-dark h4 .docs-heading-anchor:visited,html.theme--documenter-dark h5 .docs-heading-anchor,html.theme--documenter-dark h5 .docs-heading-anchor:hover,html.theme--documenter-dark h5 .docs-heading-anchor:visited,html.theme--documenter-dark h6 .docs-heading-anchor,html.theme--documenter-dark h6 .docs-heading-anchor:hover,html.theme--documenter-dark h6 .docs-heading-anchor:visited{color:#f2f2f2}html.theme--documenter-dark h1 .docs-heading-anchor-permalink,html.theme--documenter-dark h2 .docs-heading-anchor-permalink,html.theme--documenter-dark h3 .docs-heading-anchor-permalink,html.theme--documenter-dark h4 .docs-heading-anchor-permalink,html.theme--documenter-dark h5 .docs-heading-anchor-permalink,html.theme--documenter-dark h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}html.theme--documenter-dark h1 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h2 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h3 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h4 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h5 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}html.theme--documenter-dark h1:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h2:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h3:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h4:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h5:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h6:hover .docs-heading-anchor-permalink{visibility:visible}html.theme--documenter-dark .docs-light-only{display:none !important}html.theme--documenter-dark pre{position:relative;overflow:hidden}html.theme--documenter-dark pre code,html.theme--documenter-dark pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}html.theme--documenter-dark pre code:first-of-type,html.theme--documenter-dark pre code.hljs:first-of-type{padding-top:0.5rem !important}html.theme--documenter-dark pre code:last-of-type,html.theme--documenter-dark pre code.hljs:last-of-type{padding-bottom:0.5rem !important}html.theme--documenter-dark pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#fff;cursor:pointer;text-align:center}html.theme--documenter-dark pre .copy-button:focus,html.theme--documenter-dark pre .copy-button:hover{opacity:1;background:rgba(255,255,255,0.1);color:#1abc9c}html.theme--documenter-dark pre .copy-button.success{color:#259a12;opacity:1}html.theme--documenter-dark pre .copy-button.error{color:#cb3c33;opacity:1}html.theme--documenter-dark pre:hover .copy-button{opacity:1}html.theme--documenter-dark .admonition{background-color:#282f2f;border-style:solid;border-width:1px;border-color:#5e6d6f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .admonition strong{color:currentColor}html.theme--documenter-dark .admonition.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}html.theme--documenter-dark .admonition.is-medium{font-size:1.25rem}html.theme--documenter-dark .admonition.is-large{font-size:1.5rem}html.theme--documenter-dark .admonition.is-default{background-color:#282f2f;border-color:#5e6d6f}html.theme--documenter-dark .admonition.is-default>.admonition-header{background-color:#5e6d6f;color:#fff}html.theme--documenter-dark .admonition.is-default>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-info{background-color:#282f2f;border-color:#024c7d}html.theme--documenter-dark .admonition.is-info>.admonition-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .admonition.is-info>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-success{background-color:#282f2f;border-color:#008438}html.theme--documenter-dark .admonition.is-success>.admonition-header{background-color:#008438;color:#fff}html.theme--documenter-dark .admonition.is-success>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-warning{background-color:#282f2f;border-color:#ad8100}html.theme--documenter-dark .admonition.is-warning>.admonition-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .admonition.is-warning>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-danger{background-color:#282f2f;border-color:#9e1b0d}html.theme--documenter-dark .admonition.is-danger>.admonition-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .admonition.is-danger>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-compat{background-color:#282f2f;border-color:#137886}html.theme--documenter-dark .admonition.is-compat>.admonition-header{background-color:#137886;color:#fff}html.theme--documenter-dark .admonition.is-compat>.admonition-body{color:#fff}html.theme--documenter-dark .admonition-header{color:#fff;background-color:#5e6d6f;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}html.theme--documenter-dark .admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}html.theme--documenter-dark details.admonition.is-details>.admonition-header{list-style:none}html.theme--documenter-dark details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}html.theme--documenter-dark details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}html.theme--documenter-dark .admonition-body{color:#fff;padding:0.5rem .75rem}html.theme--documenter-dark .admonition-body pre{background-color:#282f2f}html.theme--documenter-dark .admonition-body code{background-color:rgba(255,255,255,0.05)}html.theme--documenter-dark .docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #5e6d6f;box-shadow:none;max-width:100%}html.theme--documenter-dark .docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#282f2f;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #5e6d6f;overflow:auto}html.theme--documenter-dark .docstring>header code{background-color:transparent}html.theme--documenter-dark .docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}html.theme--documenter-dark .docstring>header .docstring-binding{margin-right:0.3em}html.theme--documenter-dark .docstring>header .docstring-category{margin-left:0.3em}html.theme--documenter-dark .docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .docstring>section:last-child{border-bottom:none}html.theme--documenter-dark .docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}html.theme--documenter-dark .docstring>section>a.docs-sourcelink:focus{opacity:1 !important}html.theme--documenter-dark .docstring:hover>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring>section:hover a.docs-sourcelink{opacity:1}html.theme--documenter-dark .documenter-example-output{background-color:#1f2424}html.theme--documenter-dark .outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#282f2f;color:#fff;border-bottom:3px solid #9e1b0d;padding:10px 35px;text-align:center;font-size:15px}html.theme--documenter-dark .outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}html.theme--documenter-dark .outdated-warning-overlay a{color:#1abc9c}html.theme--documenter-dark .outdated-warning-overlay a:hover{color:#1dd2af}html.theme--documenter-dark .content pre{border:1px solid #5e6d6f}html.theme--documenter-dark .content code{font-weight:inherit}html.theme--documenter-dark .content a code{color:#1abc9c}html.theme--documenter-dark .content h1 code,html.theme--documenter-dark .content h2 code,html.theme--documenter-dark .content h3 code,html.theme--documenter-dark .content h4 code,html.theme--documenter-dark .content h5 code,html.theme--documenter-dark .content h6 code{color:#f2f2f2}html.theme--documenter-dark .content table{display:block;width:initial;max-width:100%;overflow-x:auto}html.theme--documenter-dark .content blockquote>ul:first-child,html.theme--documenter-dark .content blockquote>ol:first-child,html.theme--documenter-dark .content .admonition-body>ul:first-child,html.theme--documenter-dark .content .admonition-body>ol:first-child{margin-top:0}html.theme--documenter-dark pre,html.theme--documenter-dark code{font-variant-ligatures:no-contextual}html.theme--documenter-dark .breadcrumb a.is-disabled{cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb a.is-disabled,html.theme--documenter-dark .breadcrumb a.is-disabled:hover{color:#f2f2f2}html.theme--documenter-dark .hljs{background:initial !important}html.theme--documenter-dark .katex .katex-mathml{top:0;right:0}html.theme--documenter-dark .katex-display,html.theme--documenter-dark mjx-container,html.theme--documenter-dark .MathJax_Display{margin:0.5em 0 !important}html.theme--documenter-dark html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}html.theme--documenter-dark li.no-marker{list-style:none}html.theme--documenter-dark #documenter .docs-main>article{overflow-wrap:break-word}html.theme--documenter-dark #documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main{width:100%}html.theme--documenter-dark #documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-main>header,html.theme--documenter-dark #documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar{background-color:#1f2424;border-bottom:1px solid #5e6d6f;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-icon,html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #171717;transition-duration:0.7s;-webkit-transition-duration:0.7s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}html.theme--documenter-dark #documenter .docs-main section.footnotes{border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-main section.footnotes li .tag:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .content kbd:first-child,html.theme--documenter-dark .content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}html.theme--documenter-dark #documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #5e6d6f;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage,html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}html.theme--documenter-dark #documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}html.theme--documenter-dark #documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}html.theme--documenter-dark #documenter .docs-sidebar{display:flex;flex-direction:column;color:#fff;background-color:#282f2f;border-right:1px solid #5e6d6f;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}html.theme--documenter-dark #documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #171717}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar{left:0;top:0}}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a,html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a:hover{color:#fff}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector{border-top:1px solid #5e6d6f;display:none;padding:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector.visible{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #5e6d6f;padding-bottom:1.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#fff;background:#282f2f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu a.tocitem:hover,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#fff;background-color:#32393a}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #5e6d6f;border-bottom:1px solid #5e6d6f;background-color:#1f2424}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#1f2424;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#32393a;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{width:14.4rem}html.theme--documenter-dark #documenter .docs-sidebar #documenter-search-query{color:#868c98;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}html.theme--documenter-dark kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(245,245,245,0.6);box-shadow:0 2px 0 1px rgba(245,245,245,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}html.theme--documenter-dark .search-min-width-50{min-width:50%}html.theme--documenter-dark .search-min-height-100{min-height:100%}html.theme--documenter-dark .search-modal-card-body{max-height:calc(100vh - 15rem)}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333;background-color:#f1f5f9}html.theme--documenter-dark .search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}html.theme--documenter-dark .search-filter:hover,html.theme--documenter-dark .search-filter:focus{color:#333}html.theme--documenter-dark .search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}html.theme--documenter-dark .search-filter-selected:hover,html.theme--documenter-dark .search-filter-selected:focus{color:#f5f5f5}html.theme--documenter-dark .search-result-highlight{background-color:#ffdd57;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .search-result-title{width:85%;color:#f5f5f5}html.theme--documenter-dark .search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-thumb,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-track,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem}html.theme--documenter-dark .gap-8{gap:2rem}html.theme--documenter-dark{background-color:#1f2424;font-size:16px;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark .ansi span.sgr1{font-weight:bolder}html.theme--documenter-dark .ansi span.sgr2{font-weight:lighter}html.theme--documenter-dark .ansi span.sgr3{font-style:italic}html.theme--documenter-dark .ansi span.sgr4{text-decoration:underline}html.theme--documenter-dark .ansi span.sgr7{color:#1f2424;background-color:#fff}html.theme--documenter-dark .ansi span.sgr8{color:transparent}html.theme--documenter-dark .ansi span.sgr8 span{color:transparent}html.theme--documenter-dark .ansi span.sgr9{text-decoration:line-through}html.theme--documenter-dark .ansi span.sgr30{color:#242424}html.theme--documenter-dark .ansi span.sgr31{color:#f6705f}html.theme--documenter-dark .ansi span.sgr32{color:#4fb43a}html.theme--documenter-dark .ansi span.sgr33{color:#f4c72f}html.theme--documenter-dark .ansi span.sgr34{color:#7587f0}html.theme--documenter-dark .ansi span.sgr35{color:#bc89d3}html.theme--documenter-dark .ansi span.sgr36{color:#49b6ca}html.theme--documenter-dark .ansi span.sgr37{color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr40{background-color:#242424}html.theme--documenter-dark .ansi span.sgr41{background-color:#f6705f}html.theme--documenter-dark .ansi span.sgr42{background-color:#4fb43a}html.theme--documenter-dark .ansi span.sgr43{background-color:#f4c72f}html.theme--documenter-dark .ansi span.sgr44{background-color:#7587f0}html.theme--documenter-dark .ansi span.sgr45{background-color:#bc89d3}html.theme--documenter-dark .ansi span.sgr46{background-color:#49b6ca}html.theme--documenter-dark .ansi span.sgr47{background-color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr90{color:#92a0a2}html.theme--documenter-dark .ansi span.sgr91{color:#ff8674}html.theme--documenter-dark .ansi span.sgr92{color:#79d462}html.theme--documenter-dark .ansi span.sgr93{color:#ffe76b}html.theme--documenter-dark .ansi span.sgr94{color:#8a98ff}html.theme--documenter-dark .ansi span.sgr95{color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr96{color:#6bc8db}html.theme--documenter-dark .ansi span.sgr97{color:#ecf0f1}html.theme--documenter-dark .ansi span.sgr100{background-color:#92a0a2}html.theme--documenter-dark .ansi span.sgr101{background-color:#ff8674}html.theme--documenter-dark .ansi span.sgr102{background-color:#79d462}html.theme--documenter-dark .ansi span.sgr103{background-color:#ffe76b}html.theme--documenter-dark .ansi span.sgr104{background-color:#8a98ff}html.theme--documenter-dark .ansi span.sgr105{background-color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr106{background-color:#6bc8db}html.theme--documenter-dark .ansi span.sgr107{background-color:#ecf0f1}html.theme--documenter-dark code.language-julia-repl>span.hljs-meta{color:#4fb43a;font-weight:bolder}html.theme--documenter-dark .hljs{background:#2b2b2b;color:#f8f8f2}html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-quote{color:#d4d0ab}html.theme--documenter-dark .hljs-variable,html.theme--documenter-dark .hljs-template-variable,html.theme--documenter-dark .hljs-tag,html.theme--documenter-dark .hljs-name,html.theme--documenter-dark .hljs-selector-id,html.theme--documenter-dark .hljs-selector-class,html.theme--documenter-dark .hljs-regexp,html.theme--documenter-dark .hljs-deletion{color:#ffa07a}html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-link{color:#f5ab35}html.theme--documenter-dark .hljs-attribute{color:#ffd700}html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-addition{color:#abe338}html.theme--documenter-dark .hljs-title,html.theme--documenter-dark .hljs-section{color:#00e0e0}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{color:#dcc6e0}html.theme--documenter-dark .hljs-emphasis{font-style:italic}html.theme--documenter-dark .hljs-strong{font-weight:bold}@media screen and (-ms-high-contrast: active){html.theme--documenter-dark .hljs-addition,html.theme--documenter-dark .hljs-attribute,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-link,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-quote{color:highlight}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{font-weight:bold}}html.theme--documenter-dark .hljs-subst{color:#f8f8f2}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333 !important;background-color:#f1f5f9 !important}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:whitesmoke;background-color:#33415580;border-radius:0.6rem}html.theme--documenter-dark .search-result-title{color:whitesmoke}html.theme--documenter-dark .search-result-highlight{background-color:greenyellow;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f50}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem} diff --git a/v2.15.0/assets/themes/documenter-light.css b/v2.15.0/assets/themes/documenter-light.css new file mode 100644 index 000000000..2f168c77b --- /dev/null +++ b/v2.15.0/assets/themes/documenter-light.css @@ -0,0 +1,9 @@ +.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.file-cta,.file-name,.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input,.button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:4px;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus,.pagination-ellipsis:focus,.file-cta:focus,.file-name:focus,.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.button:focus,.is-focused.pagination-previous,.is-focused.pagination-next,.is-focused.pagination-link,.is-focused.pagination-ellipsis,.is-focused.file-cta,.is-focused.file-name,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-focused.button,.pagination-previous:active,.pagination-next:active,.pagination-link:active,.pagination-ellipsis:active,.file-cta:active,.file-name:active,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.button:active,.is-active.pagination-previous,.is-active.pagination-next,.is-active.pagination-link,.is-active.pagination-ellipsis,.is-active.file-cta,.is-active.file-name,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.is-active.button{outline:none}.pagination-previous[disabled],.pagination-next[disabled],.pagination-link[disabled],.pagination-ellipsis[disabled],.file-cta[disabled],.file-name[disabled],.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],.button[disabled],fieldset[disabled] .pagination-previous,fieldset[disabled] .pagination-next,fieldset[disabled] .pagination-link,fieldset[disabled] .pagination-ellipsis,fieldset[disabled] .file-cta,fieldset[disabled] .file-name,fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] .button{cursor:not-allowed}.tabs,.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.breadcrumb,.file,.button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.navbar-link:not(.is-arrowless)::after,.select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}.admonition:not(:last-child),.tabs:not(:last-child),.pagination:not(:last-child),.message:not(:last-child),.level:not(:last-child),.breadcrumb:not(:last-child),.block:not(:last-child),.title:not(:last-child),.subtitle:not(:last-child),.table-container:not(:last-child),.table:not(:last-child),.progress:not(:last-child),.notification:not(:last-child),.content:not(:last-child),.box:not(:last-child){margin-bottom:1.5rem}.modal-close,.delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}.modal-close::before,.delete::before,.modal-close::after,.delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.modal-close::before,.delete::before{height:2px;width:50%}.modal-close::after,.delete::after{height:50%;width:2px}.modal-close:hover,.delete:hover,.modal-close:focus,.delete:focus{background-color:rgba(10,10,10,0.3)}.modal-close:active,.delete:active{background-color:rgba(10,10,10,0.4)}.is-small.modal-close,#documenter .docs-sidebar form.docs-search>input.modal-close,.is-small.delete,#documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}.is-medium.modal-close,.is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}.is-large.modal-close,.is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}.control.is-loading::after,.select.is-loading::after,.loader,.button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdbdb;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}.hero-video,.modal-background,.modal,.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}.navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#f5f5f5 !important}a.has-text-light:hover,a.has-text-light:focus{color:#dbdbdb !important}.has-background-light{background-color:#f5f5f5 !important}.has-text-dark{color:#363636 !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#1c1c1c !important}.has-background-dark{background-color:#363636 !important}.has-text-primary{color:#4eb5de !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#27a1d2 !important}.has-background-primary{background-color:#4eb5de !important}.has-text-primary-light{color:#eef8fc !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#c3e6f4 !important}.has-background-primary-light{background-color:#eef8fc !important}.has-text-primary-dark{color:#1a6d8e !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#228eb9 !important}.has-background-primary-dark{background-color:#1a6d8e !important}.has-text-link{color:#2e63b8 !important}a.has-text-link:hover,a.has-text-link:focus{color:#244d8f !important}.has-background-link{background-color:#2e63b8 !important}.has-text-link-light{color:#eff3fb !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c6d6f1 !important}.has-background-link-light{background-color:#eff3fb !important}.has-text-link-dark{color:#3169c4 !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#5485d4 !important}.has-background-link-dark{background-color:#3169c4 !important}.has-text-info{color:#209cee !important}a.has-text-info:hover,a.has-text-info:focus{color:#1081cb !important}.has-background-info{background-color:#209cee !important}.has-text-info-light{color:#ecf7fe !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#bde2fa !important}.has-background-info-light{background-color:#ecf7fe !important}.has-text-info-dark{color:#0e72b4 !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#1190e3 !important}.has-background-info-dark{background-color:#0e72b4 !important}.has-text-success{color:#22c35b !important}a.has-text-success:hover,a.has-text-success:focus{color:#1a9847 !important}.has-background-success{background-color:#22c35b !important}.has-text-success-light{color:#eefcf3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#c2f4d4 !important}.has-background-success-light{background-color:#eefcf3 !important}.has-text-success-dark{color:#198f43 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#21bb57 !important}.has-background-success-dark{background-color:#198f43 !important}.has-text-warning{color:#ffdd57 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#ffd324 !important}.has-background-warning{background-color:#ffdd57 !important}.has-text-warning-light{color:#fffbeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#fff1b8 !important}.has-background-warning-light{background-color:#fffbeb !important}.has-text-warning-dark{color:#947600 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#c79f00 !important}.has-background-warning-dark{background-color:#947600 !important}.has-text-danger{color:#da0b00 !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#a70800 !important}.has-background-danger{background-color:#da0b00 !important}.has-text-danger-light{color:#ffeceb !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#ffbbb8 !important}.has-background-danger-light{background-color:#ffeceb !important}.has-text-danger-dark{color:#f50c00 !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#ff3429 !important}.has-background-danger-dark{background-color:#f50c00 !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#363636 !important}.has-background-grey-darker{background-color:#363636 !important}.has-text-grey-dark{color:#4a4a4a !important}.has-background-grey-dark{background-color:#4a4a4a !important}.has-text-grey{color:#6b6b6b !important}.has-background-grey{background-color:#6b6b6b !important}.has-text-grey-light{color:#b5b5b5 !important}.has-background-grey-light{background-color:#b5b5b5 !important}.has-text-grey-lighter{color:#dbdbdb !important}.has-background-grey-lighter{background-color:#dbdbdb !important}.has-text-white-ter{color:#f5f5f5 !important}.has-background-white-ter{background-color:#f5f5f5 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,.docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}html{background-color:#fff;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}article,aside,figure,footer,header,hgroup,section{display:block}body,button,input,optgroup,select,textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}code,pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}body{color:#222;font-size:1em;font-weight:400;line-height:1.5}a{color:#2e63b8;cursor:pointer;text-decoration:none}a strong{color:currentColor}a:hover{color:#363636}code{background-color:rgba(0,0,0,0.05);color:#000;font-size:.875em;font-weight:normal;padding:.1em}hr{background-color:#f5f5f5;border:none;display:block;height:2px;margin:1.5rem 0}img{height:auto;max-width:100%}input[type="checkbox"],input[type="radio"]{vertical-align:baseline}small{font-size:.875em}span{font-style:inherit;font-weight:inherit}strong{color:#222;font-weight:700}fieldset{border:none}pre{-webkit-overflow-scrolling:touch;background-color:#f5f5f5;color:#222;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}table td,table th{vertical-align:top}table td:not([align]),table th:not([align]){text-align:inherit}table th{color:#222}@keyframes spinAround{from{transform:rotate(0deg)}to{transform:rotate(359deg)}}.box{background-color:#fff;border-radius:6px;box-shadow:#bbb;color:#222;display:block;padding:1.25rem}a.box:hover,a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #2e63b8}a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #2e63b8}.button{background-color:#fff;border-color:#dbdbdb;border-width:1px;color:#222;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}.button strong{color:inherit}.button .icon,.button .icon.is-small,.button #documenter .docs-sidebar form.docs-search>input.icon,#documenter .docs-sidebar .button form.docs-search>input.icon,.button .icon.is-medium,.button .icon.is-large{height:1.5em;width:1.5em}.button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}.button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}.button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}.button:hover,.button.is-hovered{border-color:#b5b5b5;color:#363636}.button:focus,.button.is-focused{border-color:#3c5dcd;color:#363636}.button:focus:not(:active),.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button:active,.button.is-active{border-color:#4a4a4a;color:#363636}.button.is-text{background-color:transparent;border-color:transparent;color:#222;text-decoration:underline}.button.is-text:hover,.button.is-text.is-hovered,.button.is-text:focus,.button.is-text.is-focused{background-color:#f5f5f5;color:#222}.button.is-text:active,.button.is-text.is-active{background-color:#e8e8e8;color:#222}.button.is-text[disabled],fieldset[disabled] .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}.button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#2e63b8;text-decoration:none}.button.is-ghost:hover,.button.is-ghost.is-hovered{color:#2e63b8;text-decoration:underline}.button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}.button.is-white:hover,.button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.button.is-white:focus,.button.is-white.is-focused{border-color:transparent;color:#0a0a0a}.button.is-white:focus:not(:active),.button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.button.is-white:active,.button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.button.is-white[disabled],fieldset[disabled] .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}.button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted:hover,.button.is-white.is-inverted.is-hovered{background-color:#000}.button.is-white.is-inverted[disabled],fieldset[disabled] .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}.button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-white.is-outlined:hover,.button.is-white.is-outlined.is-hovered,.button.is-white.is-outlined:focus,.button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}.button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-outlined.is-loading:hover::after,.button.is-white.is-outlined.is-loading.is-hovered::after,.button.is-white.is-outlined.is-loading:focus::after,.button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined[disabled],fieldset[disabled] .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-white.is-inverted.is-outlined:hover,.button.is-white.is-inverted.is-outlined.is-hovered,.button.is-white.is-inverted.is-outlined:focus,.button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted.is-outlined.is-loading:hover::after,.button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-white.is-inverted.is-outlined.is-loading:focus::after,.button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}.button.is-black:hover,.button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}.button.is-black:focus,.button.is-black.is-focused{border-color:transparent;color:#fff}.button.is-black:focus:not(:active),.button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.button.is-black:active,.button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}.button.is-black[disabled],fieldset[disabled] .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}.button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted:hover,.button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-black.is-inverted[disabled],fieldset[disabled] .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}.button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-black.is-outlined:hover,.button.is-black.is-outlined.is-hovered,.button.is-black.is-outlined:focus,.button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-outlined.is-loading:hover::after,.button.is-black.is-outlined.is-loading.is-hovered::after,.button.is-black.is-outlined.is-loading:focus::after,.button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined[disabled],fieldset[disabled] .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-black.is-inverted.is-outlined:hover,.button.is-black.is-inverted.is-outlined.is-hovered,.button.is-black.is-inverted.is-outlined:focus,.button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted.is-outlined.is-loading:hover::after,.button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-black.is-inverted.is-outlined.is-loading:focus::after,.button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-light{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:hover,.button.is-light.is-hovered{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus,.button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus:not(:active),.button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.button.is-light:active,.button.is-light.is-active{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light[disabled],fieldset[disabled] .button.is-light{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none}.button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted:hover,.button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-light.is-inverted[disabled],fieldset[disabled] .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#f5f5f5}.button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;color:#f5f5f5}.button.is-light.is-outlined:hover,.button.is-light.is-outlined.is-hovered,.button.is-light.is-outlined:focus,.button.is-light.is-outlined.is-focused{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-outlined.is-loading:hover::after,.button.is-light.is-outlined.is-loading.is-hovered::after,.button.is-light.is-outlined.is-loading:focus::after,.button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined[disabled],fieldset[disabled] .button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;box-shadow:none;color:#f5f5f5}.button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-light.is-inverted.is-outlined:hover,.button.is-light.is-inverted.is-outlined.is-hovered,.button.is-light.is-inverted.is-outlined:focus,.button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted.is-outlined.is-loading:hover::after,.button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-light.is-inverted.is-outlined.is-loading:focus::after,.button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-dark,.content kbd.button{background-color:#363636;border-color:transparent;color:#fff}.button.is-dark:hover,.content kbd.button:hover,.button.is-dark.is-hovered,.content kbd.button.is-hovered{background-color:#2f2f2f;border-color:transparent;color:#fff}.button.is-dark:focus,.content kbd.button:focus,.button.is-dark.is-focused,.content kbd.button.is-focused{border-color:transparent;color:#fff}.button.is-dark:focus:not(:active),.content kbd.button:focus:not(:active),.button.is-dark.is-focused:not(:active),.content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.button.is-dark:active,.content kbd.button:active,.button.is-dark.is-active,.content kbd.button.is-active{background-color:#292929;border-color:transparent;color:#fff}.button.is-dark[disabled],.content kbd.button[disabled],fieldset[disabled] .button.is-dark,fieldset[disabled] .content kbd.button,.content fieldset[disabled] kbd.button{background-color:#363636;border-color:#363636;box-shadow:none}.button.is-dark.is-inverted,.content kbd.button.is-inverted{background-color:#fff;color:#363636}.button.is-dark.is-inverted:hover,.content kbd.button.is-inverted:hover,.button.is-dark.is-inverted.is-hovered,.content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-dark.is-inverted[disabled],.content kbd.button.is-inverted[disabled],fieldset[disabled] .button.is-dark.is-inverted,fieldset[disabled] .content kbd.button.is-inverted,.content fieldset[disabled] kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#363636}.button.is-dark.is-loading::after,.content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined,.content kbd.button.is-outlined{background-color:transparent;border-color:#363636;color:#363636}.button.is-dark.is-outlined:hover,.content kbd.button.is-outlined:hover,.button.is-dark.is-outlined.is-hovered,.content kbd.button.is-outlined.is-hovered,.button.is-dark.is-outlined:focus,.content kbd.button.is-outlined:focus,.button.is-dark.is-outlined.is-focused,.content kbd.button.is-outlined.is-focused{background-color:#363636;border-color:#363636;color:#fff}.button.is-dark.is-outlined.is-loading::after,.content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-outlined.is-loading:hover::after,.content kbd.button.is-outlined.is-loading:hover::after,.button.is-dark.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-outlined.is-loading:focus::after,.content kbd.button.is-outlined.is-loading:focus::after,.button.is-dark.is-outlined.is-loading.is-focused::after,.content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined[disabled],.content kbd.button.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-outlined,fieldset[disabled] .content kbd.button.is-outlined,.content fieldset[disabled] kbd.button.is-outlined{background-color:transparent;border-color:#363636;box-shadow:none;color:#363636}.button.is-dark.is-inverted.is-outlined,.content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-dark.is-inverted.is-outlined:hover,.content kbd.button.is-inverted.is-outlined:hover,.button.is-dark.is-inverted.is-outlined.is-hovered,.content kbd.button.is-inverted.is-outlined.is-hovered,.button.is-dark.is-inverted.is-outlined:focus,.content kbd.button.is-inverted.is-outlined:focus,.button.is-dark.is-inverted.is-outlined.is-focused,.content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#363636}.button.is-dark.is-inverted.is-outlined.is-loading:hover::after,.content kbd.button.is-inverted.is-outlined.is-loading:hover::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-inverted.is-outlined.is-loading:focus::after,.content kbd.button.is-inverted.is-outlined.is-loading:focus::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-inverted.is-outlined[disabled],.content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-inverted.is-outlined,fieldset[disabled] .content kbd.button.is-inverted.is-outlined,.content fieldset[disabled] kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary,.docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:transparent;color:#fff}.button.is-primary:hover,.docstring>section>a.button.docs-sourcelink:hover,.button.is-primary.is-hovered,.docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#43b1dc;border-color:transparent;color:#fff}.button.is-primary:focus,.docstring>section>a.button.docs-sourcelink:focus,.button.is-primary.is-focused,.docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}.button.is-primary:focus:not(:active),.docstring>section>a.button.docs-sourcelink:focus:not(:active),.button.is-primary.is-focused:not(:active),.docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.button.is-primary:active,.docstring>section>a.button.docs-sourcelink:active,.button.is-primary.is-active,.docstring>section>a.button.is-active.docs-sourcelink{background-color:#39acda;border-color:transparent;color:#fff}.button.is-primary[disabled],.docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary,fieldset[disabled] .docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;box-shadow:none}.button.is-primary.is-inverted,.docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted:hover,.docstring>section>a.button.is-inverted.docs-sourcelink:hover,.button.is-primary.is-inverted.is-hovered,.docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}.button.is-primary.is-inverted[disabled],.docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted,fieldset[disabled] .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#4eb5de}.button.is-primary.is-loading::after,.docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined,.docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;color:#4eb5de}.button.is-primary.is-outlined:hover,.docstring>section>a.button.is-outlined.docs-sourcelink:hover,.button.is-primary.is-outlined.is-hovered,.docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-outlined:focus,.docstring>section>a.button.is-outlined.docs-sourcelink:focus,.button.is-primary.is-outlined.is-focused,.docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.button.is-primary.is-outlined.is-loading::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined[disabled],.docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-outlined,fieldset[disabled] .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;box-shadow:none;color:#4eb5de}.button.is-primary.is-inverted.is-outlined,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}.button.is-primary.is-inverted.is-outlined:hover,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,.button.is-primary.is-inverted.is-outlined.is-hovered,.docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-inverted.is-outlined:focus,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,.button.is-primary.is-inverted.is-outlined.is-focused,.docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-inverted.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-inverted.is-outlined[disabled],.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted.is-outlined,fieldset[disabled] .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary.is-light,.docstring>section>a.button.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.button.is-primary.is-light:hover,.docstring>section>a.button.is-light.docs-sourcelink:hover,.button.is-primary.is-light.is-hovered,.docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e3f3fa;border-color:transparent;color:#1a6d8e}.button.is-primary.is-light:active,.docstring>section>a.button.is-light.docs-sourcelink:active,.button.is-primary.is-light.is-active,.docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#d8eff8;border-color:transparent;color:#1a6d8e}.button.is-link{background-color:#2e63b8;border-color:transparent;color:#fff}.button.is-link:hover,.button.is-link.is-hovered{background-color:#2b5eae;border-color:transparent;color:#fff}.button.is-link:focus,.button.is-link.is-focused{border-color:transparent;color:#fff}.button.is-link:focus:not(:active),.button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button.is-link:active,.button.is-link.is-active{background-color:#2958a4;border-color:transparent;color:#fff}.button.is-link[disabled],fieldset[disabled] .button.is-link{background-color:#2e63b8;border-color:#2e63b8;box-shadow:none}.button.is-link.is-inverted{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted:hover,.button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-link.is-inverted[disabled],fieldset[disabled] .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#2e63b8}.button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;color:#2e63b8}.button.is-link.is-outlined:hover,.button.is-link.is-outlined.is-hovered,.button.is-link.is-outlined:focus,.button.is-link.is-outlined.is-focused{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-outlined.is-loading:hover::after,.button.is-link.is-outlined.is-loading.is-hovered::after,.button.is-link.is-outlined.is-loading:focus::after,.button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined[disabled],fieldset[disabled] .button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;box-shadow:none;color:#2e63b8}.button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-link.is-inverted.is-outlined:hover,.button.is-link.is-inverted.is-outlined.is-hovered,.button.is-link.is-inverted.is-outlined:focus,.button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted.is-outlined.is-loading:hover::after,.button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-link.is-inverted.is-outlined.is-loading:focus::after,.button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-link.is-light{background-color:#eff3fb;color:#3169c4}.button.is-link.is-light:hover,.button.is-link.is-light.is-hovered{background-color:#e4ecf8;border-color:transparent;color:#3169c4}.button.is-link.is-light:active,.button.is-link.is-light.is-active{background-color:#dae5f6;border-color:transparent;color:#3169c4}.button.is-info{background-color:#209cee;border-color:transparent;color:#fff}.button.is-info:hover,.button.is-info.is-hovered{background-color:#1497ed;border-color:transparent;color:#fff}.button.is-info:focus,.button.is-info.is-focused{border-color:transparent;color:#fff}.button.is-info:focus:not(:active),.button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.button.is-info:active,.button.is-info.is-active{background-color:#1190e3;border-color:transparent;color:#fff}.button.is-info[disabled],fieldset[disabled] .button.is-info{background-color:#209cee;border-color:#209cee;box-shadow:none}.button.is-info.is-inverted{background-color:#fff;color:#209cee}.button.is-info.is-inverted:hover,.button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-info.is-inverted[disabled],fieldset[disabled] .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#209cee}.button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined{background-color:transparent;border-color:#209cee;color:#209cee}.button.is-info.is-outlined:hover,.button.is-info.is-outlined.is-hovered,.button.is-info.is-outlined:focus,.button.is-info.is-outlined.is-focused{background-color:#209cee;border-color:#209cee;color:#fff}.button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-outlined.is-loading:hover::after,.button.is-info.is-outlined.is-loading.is-hovered::after,.button.is-info.is-outlined.is-loading:focus::after,.button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined[disabled],fieldset[disabled] .button.is-info.is-outlined{background-color:transparent;border-color:#209cee;box-shadow:none;color:#209cee}.button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-info.is-inverted.is-outlined:hover,.button.is-info.is-inverted.is-outlined.is-hovered,.button.is-info.is-inverted.is-outlined:focus,.button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#209cee}.button.is-info.is-inverted.is-outlined.is-loading:hover::after,.button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-info.is-inverted.is-outlined.is-loading:focus::after,.button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.button.is-info.is-light:hover,.button.is-info.is-light.is-hovered{background-color:#e0f1fd;border-color:transparent;color:#0e72b4}.button.is-info.is-light:active,.button.is-info.is-light.is-active{background-color:#d4ecfc;border-color:transparent;color:#0e72b4}.button.is-success{background-color:#22c35b;border-color:transparent;color:#fff}.button.is-success:hover,.button.is-success.is-hovered{background-color:#20b856;border-color:transparent;color:#fff}.button.is-success:focus,.button.is-success.is-focused{border-color:transparent;color:#fff}.button.is-success:focus:not(:active),.button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.button.is-success:active,.button.is-success.is-active{background-color:#1ead51;border-color:transparent;color:#fff}.button.is-success[disabled],fieldset[disabled] .button.is-success{background-color:#22c35b;border-color:#22c35b;box-shadow:none}.button.is-success.is-inverted{background-color:#fff;color:#22c35b}.button.is-success.is-inverted:hover,.button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-success.is-inverted[disabled],fieldset[disabled] .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#22c35b}.button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;color:#22c35b}.button.is-success.is-outlined:hover,.button.is-success.is-outlined.is-hovered,.button.is-success.is-outlined:focus,.button.is-success.is-outlined.is-focused{background-color:#22c35b;border-color:#22c35b;color:#fff}.button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-outlined.is-loading:hover::after,.button.is-success.is-outlined.is-loading.is-hovered::after,.button.is-success.is-outlined.is-loading:focus::after,.button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined[disabled],fieldset[disabled] .button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;box-shadow:none;color:#22c35b}.button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-success.is-inverted.is-outlined:hover,.button.is-success.is-inverted.is-outlined.is-hovered,.button.is-success.is-inverted.is-outlined:focus,.button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#22c35b}.button.is-success.is-inverted.is-outlined.is-loading:hover::after,.button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-success.is-inverted.is-outlined.is-loading:focus::after,.button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-success.is-light{background-color:#eefcf3;color:#198f43}.button.is-success.is-light:hover,.button.is-success.is-light.is-hovered{background-color:#e3faeb;border-color:transparent;color:#198f43}.button.is-success.is-light:active,.button.is-success.is-light.is-active{background-color:#d8f8e3;border-color:transparent;color:#198f43}.button.is-warning{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:hover,.button.is-warning.is-hovered{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus,.button.is-warning.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus:not(:active),.button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.button.is-warning:active,.button.is-warning.is-active{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning[disabled],fieldset[disabled] .button.is-warning{background-color:#ffdd57;border-color:#ffdd57;box-shadow:none}.button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted:hover,.button.is-warning.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted[disabled],fieldset[disabled] .button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ffdd57}.button.is-warning.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;color:#ffdd57}.button.is-warning.is-outlined:hover,.button.is-warning.is-outlined.is-hovered,.button.is-warning.is-outlined:focus,.button.is-warning.is-outlined.is-focused{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-outlined.is-loading:hover::after,.button.is-warning.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-outlined.is-loading:focus::after,.button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;box-shadow:none;color:#ffdd57}.button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted.is-outlined:hover,.button.is-warning.is-inverted.is-outlined.is-hovered,.button.is-warning.is-inverted.is-outlined:focus,.button.is-warning.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted.is-outlined.is-loading:hover::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-inverted.is-outlined.is-loading:focus::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-warning.is-light{background-color:#fffbeb;color:#947600}.button.is-warning.is-light:hover,.button.is-warning.is-light.is-hovered{background-color:#fff8de;border-color:transparent;color:#947600}.button.is-warning.is-light:active,.button.is-warning.is-light.is-active{background-color:#fff6d1;border-color:transparent;color:#947600}.button.is-danger{background-color:#da0b00;border-color:transparent;color:#fff}.button.is-danger:hover,.button.is-danger.is-hovered{background-color:#cd0a00;border-color:transparent;color:#fff}.button.is-danger:focus,.button.is-danger.is-focused{border-color:transparent;color:#fff}.button.is-danger:focus:not(:active),.button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.button.is-danger:active,.button.is-danger.is-active{background-color:#c10a00;border-color:transparent;color:#fff}.button.is-danger[disabled],fieldset[disabled] .button.is-danger{background-color:#da0b00;border-color:#da0b00;box-shadow:none}.button.is-danger.is-inverted{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted:hover,.button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-danger.is-inverted[disabled],fieldset[disabled] .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#da0b00}.button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;color:#da0b00}.button.is-danger.is-outlined:hover,.button.is-danger.is-outlined.is-hovered,.button.is-danger.is-outlined:focus,.button.is-danger.is-outlined.is-focused{background-color:#da0b00;border-color:#da0b00;color:#fff}.button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-outlined.is-loading:hover::after,.button.is-danger.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-outlined.is-loading:focus::after,.button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;box-shadow:none;color:#da0b00}.button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-danger.is-inverted.is-outlined:hover,.button.is-danger.is-inverted.is-outlined.is-hovered,.button.is-danger.is-inverted.is-outlined:focus,.button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted.is-outlined.is-loading:hover::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-inverted.is-outlined.is-loading:focus::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.button.is-danger.is-light:hover,.button.is-danger.is-light.is-hovered{background-color:#ffe0de;border-color:transparent;color:#f50c00}.button.is-danger.is-light:active,.button.is-danger.is-light.is-active{background-color:#ffd3d1;border-color:transparent;color:#f50c00}.button.is-small,#documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}.button.is-small:not(.is-rounded),#documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:2px}.button.is-normal{font-size:1rem}.button.is-medium{font-size:1.25rem}.button.is-large{font-size:1.5rem}.button[disabled],fieldset[disabled] .button{background-color:#fff;border-color:#dbdbdb;box-shadow:none;opacity:.5}.button.is-fullwidth{display:flex;width:100%}.button.is-loading{color:transparent !important;pointer-events:none}.button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}.button.is-static{background-color:#f5f5f5;border-color:#dbdbdb;color:#6b6b6b;box-shadow:none;pointer-events:none}.button.is-rounded,#documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}.buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.buttons .button{margin-bottom:0.5rem}.buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}.buttons:last-child{margin-bottom:-0.5rem}.buttons:not(:last-child){margin-bottom:1rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:2px}.buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}.buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}.buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}.buttons.has-addons .button:last-child{margin-right:0}.buttons.has-addons .button:hover,.buttons.has-addons .button.is-hovered{z-index:2}.buttons.has-addons .button:focus,.buttons.has-addons .button.is-focused,.buttons.has-addons .button:active,.buttons.has-addons .button.is-active,.buttons.has-addons .button.is-selected{z-index:3}.buttons.has-addons .button:focus:hover,.buttons.has-addons .button.is-focused:hover,.buttons.has-addons .button:active:hover,.buttons.has-addons .button.is-active:hover,.buttons.has-addons .button.is-selected:hover{z-index:4}.buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}.buttons.is-centered{justify-content:center}.buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}.buttons.is-right{justify-content:flex-end}.buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.65625rem}.button.is-responsive.is-medium{font-size:.75rem}.button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.75rem}.button.is-responsive.is-medium{font-size:1rem}.button.is-responsive.is-large{font-size:1.25rem}}.container{flex-grow:1;margin:0 auto;position:relative;width:auto}.container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){.container{max-width:992px}}@media screen and (max-width: 1215px){.container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){.container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){.container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){.container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}.content li+li{margin-top:0.25em}.content p:not(:last-child),.content dl:not(:last-child),.content ol:not(:last-child),.content ul:not(:last-child),.content blockquote:not(:last-child),.content pre:not(:last-child),.content table:not(:last-child){margin-bottom:1em}.content h1,.content h2,.content h3,.content h4,.content h5,.content h6{color:#222;font-weight:600;line-height:1.125}.content h1{font-size:2em;margin-bottom:0.5em}.content h1:not(:first-child){margin-top:1em}.content h2{font-size:1.75em;margin-bottom:0.5714em}.content h2:not(:first-child){margin-top:1.1428em}.content h3{font-size:1.5em;margin-bottom:0.6666em}.content h3:not(:first-child){margin-top:1.3333em}.content h4{font-size:1.25em;margin-bottom:0.8em}.content h5{font-size:1.125em;margin-bottom:0.8888em}.content h6{font-size:1em;margin-bottom:1em}.content blockquote{background-color:#f5f5f5;border-left:5px solid #dbdbdb;padding:1.25em 1.5em}.content ol{list-style-position:outside;margin-left:2em;margin-top:1em}.content ol:not([type]){list-style-type:decimal}.content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}.content ol.is-lower-roman:not([type]){list-style-type:lower-roman}.content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}.content ol.is-upper-roman:not([type]){list-style-type:upper-roman}.content ul{list-style:disc outside;margin-left:2em;margin-top:1em}.content ul ul{list-style-type:circle;margin-top:0.5em}.content ul ul ul{list-style-type:square}.content dd{margin-left:2em}.content figure{margin-left:2em;margin-right:2em;text-align:center}.content figure:not(:first-child){margin-top:2em}.content figure:not(:last-child){margin-bottom:2em}.content figure img{display:inline-block}.content figure figcaption{font-style:italic}.content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}.content sup,.content sub{font-size:75%}.content table{width:100%}.content table td,.content table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.content table th{color:#222}.content table th:not([align]){text-align:inherit}.content table thead td,.content table thead th{border-width:0 0 2px;color:#222}.content table tfoot td,.content table tfoot th{border-width:2px 0 0;color:#222}.content table tbody tr:last-child td,.content table tbody tr:last-child th{border-bottom-width:0}.content .tabs li+li{margin-top:0}.content.is-small,#documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}.content.is-normal{font-size:1rem}.content.is-medium{font-size:1.25rem}.content.is-large{font-size:1.5rem}.icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}.icon.is-small,#documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}.icon.is-medium{height:2rem;width:2rem}.icon.is-large{height:3rem;width:3rem}.icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}.icon-text .icon{flex-grow:0;flex-shrink:0}.icon-text .icon:not(:last-child){margin-right:.25em}.icon-text .icon:not(:first-child){margin-left:.25em}div.icon-text{display:flex}.image,#documenter .docs-sidebar .docs-logo>img{display:block;position:relative}.image img,#documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}.image img.is-rounded,#documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}.image.is-fullwidth,#documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}.image.is-square,#documenter .docs-sidebar .docs-logo>img.is-square,.image.is-1by1,#documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}.image.is-5by4,#documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}.image.is-4by3,#documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}.image.is-3by2,#documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}.image.is-5by3,#documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}.image.is-16by9,#documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}.image.is-2by1,#documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}.image.is-3by1,#documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}.image.is-4by5,#documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}.image.is-3by4,#documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}.image.is-2by3,#documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}.image.is-3by5,#documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}.image.is-9by16,#documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}.image.is-1by2,#documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}.image.is-1by3,#documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}.image.is-16x16,#documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}.image.is-24x24,#documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}.image.is-32x32,#documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}.image.is-48x48,#documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}.image.is-64x64,#documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}.image.is-96x96,#documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}.image.is-128x128,#documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}.notification{background-color:#f5f5f5;border-radius:4px;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}.notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}.notification strong{color:currentColor}.notification code,.notification pre{background:#fff}.notification pre code{background:transparent}.notification>.delete{right:.5rem;position:absolute;top:0.5rem}.notification .title,.notification .subtitle,.notification .content{color:currentColor}.notification.is-white{background-color:#fff;color:#0a0a0a}.notification.is-black{background-color:#0a0a0a;color:#fff}.notification.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.notification.is-dark,.content kbd.notification{background-color:#363636;color:#fff}.notification.is-primary,.docstring>section>a.notification.docs-sourcelink{background-color:#4eb5de;color:#fff}.notification.is-primary.is-light,.docstring>section>a.notification.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.notification.is-link{background-color:#2e63b8;color:#fff}.notification.is-link.is-light{background-color:#eff3fb;color:#3169c4}.notification.is-info{background-color:#209cee;color:#fff}.notification.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.notification.is-success{background-color:#22c35b;color:#fff}.notification.is-success.is-light{background-color:#eefcf3;color:#198f43}.notification.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.notification.is-warning.is-light{background-color:#fffbeb;color:#947600}.notification.is-danger{background-color:#da0b00;color:#fff}.notification.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}.progress::-webkit-progress-bar{background-color:#ededed}.progress::-webkit-progress-value{background-color:#222}.progress::-moz-progress-bar{background-color:#222}.progress::-ms-fill{background-color:#222;border:none}.progress.is-white::-webkit-progress-value{background-color:#fff}.progress.is-white::-moz-progress-bar{background-color:#fff}.progress.is-white::-ms-fill{background-color:#fff}.progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #ededed 30%)}.progress.is-black::-webkit-progress-value{background-color:#0a0a0a}.progress.is-black::-moz-progress-bar{background-color:#0a0a0a}.progress.is-black::-ms-fill{background-color:#0a0a0a}.progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #ededed 30%)}.progress.is-light::-webkit-progress-value{background-color:#f5f5f5}.progress.is-light::-moz-progress-bar{background-color:#f5f5f5}.progress.is-light::-ms-fill{background-color:#f5f5f5}.progress.is-light:indeterminate{background-image:linear-gradient(to right, #f5f5f5 30%, #ededed 30%)}.progress.is-dark::-webkit-progress-value,.content kbd.progress::-webkit-progress-value{background-color:#363636}.progress.is-dark::-moz-progress-bar,.content kbd.progress::-moz-progress-bar{background-color:#363636}.progress.is-dark::-ms-fill,.content kbd.progress::-ms-fill{background-color:#363636}.progress.is-dark:indeterminate,.content kbd.progress:indeterminate{background-image:linear-gradient(to right, #363636 30%, #ededed 30%)}.progress.is-primary::-webkit-progress-value,.docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#4eb5de}.progress.is-primary::-moz-progress-bar,.docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#4eb5de}.progress.is-primary::-ms-fill,.docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#4eb5de}.progress.is-primary:indeterminate,.docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #4eb5de 30%, #ededed 30%)}.progress.is-link::-webkit-progress-value{background-color:#2e63b8}.progress.is-link::-moz-progress-bar{background-color:#2e63b8}.progress.is-link::-ms-fill{background-color:#2e63b8}.progress.is-link:indeterminate{background-image:linear-gradient(to right, #2e63b8 30%, #ededed 30%)}.progress.is-info::-webkit-progress-value{background-color:#209cee}.progress.is-info::-moz-progress-bar{background-color:#209cee}.progress.is-info::-ms-fill{background-color:#209cee}.progress.is-info:indeterminate{background-image:linear-gradient(to right, #209cee 30%, #ededed 30%)}.progress.is-success::-webkit-progress-value{background-color:#22c35b}.progress.is-success::-moz-progress-bar{background-color:#22c35b}.progress.is-success::-ms-fill{background-color:#22c35b}.progress.is-success:indeterminate{background-image:linear-gradient(to right, #22c35b 30%, #ededed 30%)}.progress.is-warning::-webkit-progress-value{background-color:#ffdd57}.progress.is-warning::-moz-progress-bar{background-color:#ffdd57}.progress.is-warning::-ms-fill{background-color:#ffdd57}.progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ffdd57 30%, #ededed 30%)}.progress.is-danger::-webkit-progress-value{background-color:#da0b00}.progress.is-danger::-moz-progress-bar{background-color:#da0b00}.progress.is-danger::-ms-fill{background-color:#da0b00}.progress.is-danger:indeterminate{background-image:linear-gradient(to right, #da0b00 30%, #ededed 30%)}.progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#ededed;background-image:linear-gradient(to right, #222 30%, #ededed 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}.progress:indeterminate::-webkit-progress-bar{background-color:transparent}.progress:indeterminate::-moz-progress-bar{background-color:transparent}.progress:indeterminate::-ms-fill{animation-name:none}.progress.is-small,#documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}.progress.is-medium{height:1.25rem}.progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}.table{background-color:#fff;color:#222}.table td,.table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.table td.is-white,.table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}.table td.is-black,.table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.table td.is-light,.table th.is-light{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.table td.is-dark,.table th.is-dark{background-color:#363636;border-color:#363636;color:#fff}.table td.is-primary,.table th.is-primary{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.table td.is-link,.table th.is-link{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.table td.is-info,.table th.is-info{background-color:#209cee;border-color:#209cee;color:#fff}.table td.is-success,.table th.is-success{background-color:#22c35b;border-color:#22c35b;color:#fff}.table td.is-warning,.table th.is-warning{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.table td.is-danger,.table th.is-danger{background-color:#da0b00;border-color:#da0b00;color:#fff}.table td.is-narrow,.table th.is-narrow{white-space:nowrap;width:1%}.table td.is-selected,.table th.is-selected{background-color:#4eb5de;color:#fff}.table td.is-selected a,.table td.is-selected strong,.table th.is-selected a,.table th.is-selected strong{color:currentColor}.table td.is-vcentered,.table th.is-vcentered{vertical-align:middle}.table th{color:#222}.table th:not([align]){text-align:left}.table tr.is-selected{background-color:#4eb5de;color:#fff}.table tr.is-selected a,.table tr.is-selected strong{color:currentColor}.table tr.is-selected td,.table tr.is-selected th{border-color:#fff;color:currentColor}.table thead{background-color:rgba(0,0,0,0)}.table thead td,.table thead th{border-width:0 0 2px;color:#222}.table tfoot{background-color:rgba(0,0,0,0)}.table tfoot td,.table tfoot th{border-width:2px 0 0;color:#222}.table tbody{background-color:rgba(0,0,0,0)}.table tbody tr:last-child td,.table tbody tr:last-child th{border-bottom-width:0}.table.is-bordered td,.table.is-bordered th{border-width:1px}.table.is-bordered tr:last-child td,.table.is-bordered tr:last-child th{border-bottom-width:1px}.table.is-fullwidth{width:100%}.table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#f5f5f5}.table.is-narrow td,.table.is-narrow th{padding:0.25em 0.5em}.table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#fafafa}.table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}.tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.tags .tag,.tags .content kbd,.content .tags kbd,.tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}.tags .tag:not(:last-child),.tags .content kbd:not(:last-child),.content .tags kbd:not(:last-child),.tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}.tags:last-child{margin-bottom:-0.5rem}.tags:not(:last-child){margin-bottom:1rem}.tags.are-medium .tag:not(.is-normal):not(.is-large),.tags.are-medium .content kbd:not(.is-normal):not(.is-large),.content .tags.are-medium kbd:not(.is-normal):not(.is-large),.tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}.tags.are-large .tag:not(.is-normal):not(.is-medium),.tags.are-large .content kbd:not(.is-normal):not(.is-medium),.content .tags.are-large kbd:not(.is-normal):not(.is-medium),.tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}.tags.is-centered{justify-content:center}.tags.is-centered .tag,.tags.is-centered .content kbd,.content .tags.is-centered kbd,.tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}.tags.is-right{justify-content:flex-end}.tags.is-right .tag:not(:first-child),.tags.is-right .content kbd:not(:first-child),.content .tags.is-right kbd:not(:first-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}.tags.is-right .tag:not(:last-child),.tags.is-right .content kbd:not(:last-child),.content .tags.is-right kbd:not(:last-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}.tags.has-addons .tag,.tags.has-addons .content kbd,.content .tags.has-addons kbd,.tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}.tags.has-addons .tag:not(:first-child),.tags.has-addons .content kbd:not(:first-child),.content .tags.has-addons kbd:not(:first-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}.tags.has-addons .tag:not(:last-child),.tags.has-addons .content kbd:not(:last-child),.content .tags.has-addons kbd:not(:last-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.tag:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#f5f5f5;border-radius:4px;color:#222;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}.tag:not(body) .delete,.content kbd:not(body) .delete,.docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}.tag.is-white:not(body),.content kbd.is-white:not(body),.docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}.tag.is-black:not(body),.content kbd.is-black:not(body),.docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}.tag.is-light:not(body),.content kbd.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.tag.is-dark:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink.is-dark:not(body),.content .docstring>section>kbd:not(body){background-color:#363636;color:#fff}.tag.is-primary:not(body),.content kbd.is-primary:not(body),.docstring>section>a.docs-sourcelink:not(body){background-color:#4eb5de;color:#fff}.tag.is-primary.is-light:not(body),.content kbd.is-primary.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#eef8fc;color:#1a6d8e}.tag.is-link:not(body),.content kbd.is-link:not(body),.docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#2e63b8;color:#fff}.tag.is-link.is-light:not(body),.content kbd.is-link.is-light:not(body),.docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#eff3fb;color:#3169c4}.tag.is-info:not(body),.content kbd.is-info:not(body),.docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#209cee;color:#fff}.tag.is-info.is-light:not(body),.content kbd.is-info.is-light:not(body),.docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ecf7fe;color:#0e72b4}.tag.is-success:not(body),.content kbd.is-success:not(body),.docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#22c35b;color:#fff}.tag.is-success.is-light:not(body),.content kbd.is-success.is-light:not(body),.docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#eefcf3;color:#198f43}.tag.is-warning:not(body),.content kbd.is-warning:not(body),.docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ffdd57;color:rgba(0,0,0,0.7)}.tag.is-warning.is-light:not(body),.content kbd.is-warning.is-light:not(body),.docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffbeb;color:#947600}.tag.is-danger:not(body),.content kbd.is-danger:not(body),.docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#da0b00;color:#fff}.tag.is-danger.is-light:not(body),.content kbd.is-danger.is-light:not(body),.docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#ffeceb;color:#f50c00}.tag.is-normal:not(body),.content kbd.is-normal:not(body),.docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}.tag.is-medium:not(body),.content kbd.is-medium:not(body),.docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}.tag.is-large:not(body),.content kbd.is-large:not(body),.docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}.tag:not(body) .icon:first-child:not(:last-child),.content kbd:not(body) .icon:first-child:not(:last-child),.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}.tag:not(body) .icon:last-child:not(:first-child),.content kbd:not(body) .icon:last-child:not(:first-child),.docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}.tag:not(body) .icon:first-child:last-child,.content kbd:not(body) .icon:first-child:last-child,.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}.tag.is-delete:not(body),.content kbd.is-delete:not(body),.docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before,.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}.tag.is-delete:not(body):hover,.content kbd.is-delete:not(body):hover,.docstring>section>a.docs-sourcelink.is-delete:not(body):hover,.tag.is-delete:not(body):focus,.content kbd.is-delete:not(body):focus,.docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#e8e8e8}.tag.is-delete:not(body):active,.content kbd.is-delete:not(body):active,.docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#dbdbdb}.tag.is-rounded:not(body),#documenter .docs-sidebar form.docs-search>input:not(body),.content kbd.is-rounded:not(body),#documenter .docs-sidebar .content form.docs-search>input:not(body),.docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}a.tag:hover,.docstring>section>a.docs-sourcelink:hover{text-decoration:underline}.title,.subtitle{word-break:break-word}.title em,.title span,.subtitle em,.subtitle span{font-weight:inherit}.title sub,.subtitle sub{font-size:.75em}.title sup,.subtitle sup{font-size:.75em}.title .tag,.title .content kbd,.content .title kbd,.title .docstring>section>a.docs-sourcelink,.subtitle .tag,.subtitle .content kbd,.content .subtitle kbd,.subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}.title{color:#222;font-size:2rem;font-weight:600;line-height:1.125}.title strong{color:inherit;font-weight:inherit}.title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}.title.is-1{font-size:3rem}.title.is-2{font-size:2.5rem}.title.is-3{font-size:2rem}.title.is-4{font-size:1.5rem}.title.is-5{font-size:1.25rem}.title.is-6{font-size:1rem}.title.is-7{font-size:.75rem}.subtitle{color:#222;font-size:1.25rem;font-weight:400;line-height:1.25}.subtitle strong{color:#222;font-weight:600}.subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}.subtitle.is-1{font-size:3rem}.subtitle.is-2{font-size:2.5rem}.subtitle.is-3{font-size:2rem}.subtitle.is-4{font-size:1.5rem}.subtitle.is-5{font-size:1.25rem}.subtitle.is-6{font-size:1rem}.subtitle.is-7{font-size:.75rem}.heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}.number{align-items:center;background-color:#f5f5f5;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input{background-color:#fff;border-color:#dbdbdb;border-radius:4px;color:#222}.select select::-moz-placeholder,.textarea::-moz-placeholder,.input::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#707070}.select select::-webkit-input-placeholder,.textarea::-webkit-input-placeholder,.input::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#707070}.select select:-moz-placeholder,.textarea:-moz-placeholder,.input:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#707070}.select select:-ms-input-placeholder,.textarea:-ms-input-placeholder,.input:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#707070}.select select:hover,.textarea:hover,.input:hover,#documenter .docs-sidebar form.docs-search>input:hover,.select select.is-hovered,.is-hovered.textarea,.is-hovered.input,#documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#b5b5b5}.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{border-color:#2e63b8;box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none;color:#6b6b6b}.select select[disabled]::-moz-placeholder,.textarea[disabled]::-moz-placeholder,.input[disabled]::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] .select select::-moz-placeholder,.select fieldset[disabled] select::-moz-placeholder,fieldset[disabled] .textarea::-moz-placeholder,fieldset[disabled] .input::-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]::-webkit-input-placeholder,.textarea[disabled]::-webkit-input-placeholder,.input[disabled]::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] .select select::-webkit-input-placeholder,.select fieldset[disabled] select::-webkit-input-placeholder,fieldset[disabled] .textarea::-webkit-input-placeholder,fieldset[disabled] .input::-webkit-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-webkit-input-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-moz-placeholder,.textarea[disabled]:-moz-placeholder,.input[disabled]:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] .select select:-moz-placeholder,.select fieldset[disabled] select:-moz-placeholder,fieldset[disabled] .textarea:-moz-placeholder,fieldset[disabled] .input:-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-ms-input-placeholder,.textarea[disabled]:-ms-input-placeholder,.input[disabled]:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] .select select:-ms-input-placeholder,.select fieldset[disabled] select:-ms-input-placeholder,fieldset[disabled] .textarea:-ms-input-placeholder,fieldset[disabled] .input:-ms-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-ms-input-placeholder{color:rgba(107,107,107,0.3)}.textarea,.input,#documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}.textarea[readonly],.input[readonly],#documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}.is-white.textarea,.is-white.input,#documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}.is-white.textarea:focus,.is-white.input:focus,#documenter .docs-sidebar form.docs-search>input.is-white:focus,.is-white.is-focused.textarea,.is-white.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-white.textarea:active,.is-white.input:active,#documenter .docs-sidebar form.docs-search>input.is-white:active,.is-white.is-active.textarea,.is-white.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.is-black.textarea,.is-black.input,#documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}.is-black.textarea:focus,.is-black.input:focus,#documenter .docs-sidebar form.docs-search>input.is-black:focus,.is-black.is-focused.textarea,.is-black.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-black.textarea:active,.is-black.input:active,#documenter .docs-sidebar form.docs-search>input.is-black:active,.is-black.is-active.textarea,.is-black.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.is-light.textarea,.is-light.input,#documenter .docs-sidebar form.docs-search>input.is-light{border-color:#f5f5f5}.is-light.textarea:focus,.is-light.input:focus,#documenter .docs-sidebar form.docs-search>input.is-light:focus,.is-light.is-focused.textarea,.is-light.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-light.textarea:active,.is-light.input:active,#documenter .docs-sidebar form.docs-search>input.is-light:active,.is-light.is-active.textarea,.is-light.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.is-dark.textarea,.content kbd.textarea,.is-dark.input,#documenter .docs-sidebar form.docs-search>input.is-dark,.content kbd.input{border-color:#363636}.is-dark.textarea:focus,.content kbd.textarea:focus,.is-dark.input:focus,#documenter .docs-sidebar form.docs-search>input.is-dark:focus,.content kbd.input:focus,.is-dark.is-focused.textarea,.content kbd.is-focused.textarea,.is-dark.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.content kbd.is-focused.input,#documenter .docs-sidebar .content form.docs-search>input.is-focused,.is-dark.textarea:active,.content kbd.textarea:active,.is-dark.input:active,#documenter .docs-sidebar form.docs-search>input.is-dark:active,.content kbd.input:active,.is-dark.is-active.textarea,.content kbd.is-active.textarea,.is-dark.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.content kbd.is-active.input,#documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.is-primary.textarea,.docstring>section>a.textarea.docs-sourcelink,.is-primary.input,#documenter .docs-sidebar form.docs-search>input.is-primary,.docstring>section>a.input.docs-sourcelink{border-color:#4eb5de}.is-primary.textarea:focus,.docstring>section>a.textarea.docs-sourcelink:focus,.is-primary.input:focus,#documenter .docs-sidebar form.docs-search>input.is-primary:focus,.docstring>section>a.input.docs-sourcelink:focus,.is-primary.is-focused.textarea,.docstring>section>a.is-focused.textarea.docs-sourcelink,.is-primary.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.docstring>section>a.is-focused.input.docs-sourcelink,.is-primary.textarea:active,.docstring>section>a.textarea.docs-sourcelink:active,.is-primary.input:active,#documenter .docs-sidebar form.docs-search>input.is-primary:active,.docstring>section>a.input.docs-sourcelink:active,.is-primary.is-active.textarea,.docstring>section>a.is-active.textarea.docs-sourcelink,.is-primary.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.is-link.textarea,.is-link.input,#documenter .docs-sidebar form.docs-search>input.is-link{border-color:#2e63b8}.is-link.textarea:focus,.is-link.input:focus,#documenter .docs-sidebar form.docs-search>input.is-link:focus,.is-link.is-focused.textarea,.is-link.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-link.textarea:active,.is-link.input:active,#documenter .docs-sidebar form.docs-search>input.is-link:active,.is-link.is-active.textarea,.is-link.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.is-info.textarea,.is-info.input,#documenter .docs-sidebar form.docs-search>input.is-info{border-color:#209cee}.is-info.textarea:focus,.is-info.input:focus,#documenter .docs-sidebar form.docs-search>input.is-info:focus,.is-info.is-focused.textarea,.is-info.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-info.textarea:active,.is-info.input:active,#documenter .docs-sidebar form.docs-search>input.is-info:active,.is-info.is-active.textarea,.is-info.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.is-success.textarea,.is-success.input,#documenter .docs-sidebar form.docs-search>input.is-success{border-color:#22c35b}.is-success.textarea:focus,.is-success.input:focus,#documenter .docs-sidebar form.docs-search>input.is-success:focus,.is-success.is-focused.textarea,.is-success.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-success.textarea:active,.is-success.input:active,#documenter .docs-sidebar form.docs-search>input.is-success:active,.is-success.is-active.textarea,.is-success.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.is-warning.textarea,.is-warning.input,#documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ffdd57}.is-warning.textarea:focus,.is-warning.input:focus,#documenter .docs-sidebar form.docs-search>input.is-warning:focus,.is-warning.is-focused.textarea,.is-warning.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-warning.textarea:active,.is-warning.input:active,#documenter .docs-sidebar form.docs-search>input.is-warning:active,.is-warning.is-active.textarea,.is-warning.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.is-danger.textarea,.is-danger.input,#documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#da0b00}.is-danger.textarea:focus,.is-danger.input:focus,#documenter .docs-sidebar form.docs-search>input.is-danger:focus,.is-danger.is-focused.textarea,.is-danger.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-danger.textarea:active,.is-danger.input:active,#documenter .docs-sidebar form.docs-search>input.is-danger:active,.is-danger.is-active.textarea,.is-danger.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.is-small.textarea,.is-small.input,#documenter .docs-sidebar form.docs-search>input{border-radius:2px;font-size:.75rem}.is-medium.textarea,.is-medium.input,#documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}.is-large.textarea,.is-large.input,#documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}.is-fullwidth.textarea,.is-fullwidth.input,#documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}.is-inline.textarea,.is-inline.input,#documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}.input.is-rounded,#documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}.input.is-static,#documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}.textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}.textarea:not([rows]){max-height:40em;min-height:8em}.textarea[rows]{height:initial}.textarea.has-fixed-size{resize:none}.radio,.checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}.radio input,.checkbox input{cursor:pointer}.radio:hover,.checkbox:hover{color:#222}.radio[disabled],.checkbox[disabled],fieldset[disabled] .radio,fieldset[disabled] .checkbox,.radio input[disabled],.checkbox input[disabled]{color:#6b6b6b;cursor:not-allowed}.radio+.radio{margin-left:.5em}.select{display:inline-block;max-width:100%;position:relative;vertical-align:top}.select:not(.is-multiple){height:2.5em}.select:not(.is-multiple):not(.is-loading)::after{border-color:#2e63b8;right:1.125em;z-index:4}.select.is-rounded select,#documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}.select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}.select select::-ms-expand{display:none}.select select[disabled]:hover,fieldset[disabled] .select select:hover{border-color:#f5f5f5}.select select:not([multiple]){padding-right:2.5em}.select select[multiple]{height:auto;padding:0}.select select[multiple] option{padding:0.5em 1em}.select:not(.is-multiple):not(.is-loading):hover::after{border-color:#222}.select.is-white:not(:hover)::after{border-color:#fff}.select.is-white select{border-color:#fff}.select.is-white select:hover,.select.is-white select.is-hovered{border-color:#f2f2f2}.select.is-white select:focus,.select.is-white select.is-focused,.select.is-white select:active,.select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.select.is-black:not(:hover)::after{border-color:#0a0a0a}.select.is-black select{border-color:#0a0a0a}.select.is-black select:hover,.select.is-black select.is-hovered{border-color:#000}.select.is-black select:focus,.select.is-black select.is-focused,.select.is-black select:active,.select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.select.is-light:not(:hover)::after{border-color:#f5f5f5}.select.is-light select{border-color:#f5f5f5}.select.is-light select:hover,.select.is-light select.is-hovered{border-color:#e8e8e8}.select.is-light select:focus,.select.is-light select.is-focused,.select.is-light select:active,.select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.select.is-dark:not(:hover)::after,.content kbd.select:not(:hover)::after{border-color:#363636}.select.is-dark select,.content kbd.select select{border-color:#363636}.select.is-dark select:hover,.content kbd.select select:hover,.select.is-dark select.is-hovered,.content kbd.select select.is-hovered{border-color:#292929}.select.is-dark select:focus,.content kbd.select select:focus,.select.is-dark select.is-focused,.content kbd.select select.is-focused,.select.is-dark select:active,.content kbd.select select:active,.select.is-dark select.is-active,.content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.select.is-primary:not(:hover)::after,.docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#4eb5de}.select.is-primary select,.docstring>section>a.select.docs-sourcelink select{border-color:#4eb5de}.select.is-primary select:hover,.docstring>section>a.select.docs-sourcelink select:hover,.select.is-primary select.is-hovered,.docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#39acda}.select.is-primary select:focus,.docstring>section>a.select.docs-sourcelink select:focus,.select.is-primary select.is-focused,.docstring>section>a.select.docs-sourcelink select.is-focused,.select.is-primary select:active,.docstring>section>a.select.docs-sourcelink select:active,.select.is-primary select.is-active,.docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.select.is-link:not(:hover)::after{border-color:#2e63b8}.select.is-link select{border-color:#2e63b8}.select.is-link select:hover,.select.is-link select.is-hovered{border-color:#2958a4}.select.is-link select:focus,.select.is-link select.is-focused,.select.is-link select:active,.select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select.is-info:not(:hover)::after{border-color:#209cee}.select.is-info select{border-color:#209cee}.select.is-info select:hover,.select.is-info select.is-hovered{border-color:#1190e3}.select.is-info select:focus,.select.is-info select.is-focused,.select.is-info select:active,.select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.select.is-success:not(:hover)::after{border-color:#22c35b}.select.is-success select{border-color:#22c35b}.select.is-success select:hover,.select.is-success select.is-hovered{border-color:#1ead51}.select.is-success select:focus,.select.is-success select.is-focused,.select.is-success select:active,.select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.select.is-warning:not(:hover)::after{border-color:#ffdd57}.select.is-warning select{border-color:#ffdd57}.select.is-warning select:hover,.select.is-warning select.is-hovered{border-color:#ffd83e}.select.is-warning select:focus,.select.is-warning select.is-focused,.select.is-warning select:active,.select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.select.is-danger:not(:hover)::after{border-color:#da0b00}.select.is-danger select{border-color:#da0b00}.select.is-danger select:hover,.select.is-danger select.is-hovered{border-color:#c10a00}.select.is-danger select:focus,.select.is-danger select.is-focused,.select.is-danger select:active,.select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.select.is-small,#documenter .docs-sidebar form.docs-search>input.select{border-radius:2px;font-size:.75rem}.select.is-medium{font-size:1.25rem}.select.is-large{font-size:1.5rem}.select.is-disabled::after{border-color:#6b6b6b !important;opacity:0.5}.select.is-fullwidth{width:100%}.select.is-fullwidth select{width:100%}.select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}.select.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.select.is-loading.is-medium:after{font-size:1.25rem}.select.is-loading.is-large:after{font-size:1.5rem}.file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}.file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}.file.is-white:hover .file-cta,.file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.file.is-white:focus .file-cta,.file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}.file.is-white:active .file-cta,.file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}.file.is-black:hover .file-cta,.file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}.file.is-black:focus .file-cta,.file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}.file.is-black:active .file-cta,.file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}.file.is-light .file-cta{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:hover .file-cta,.file.is-light.is-hovered .file-cta{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:focus .file-cta,.file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(245,245,245,0.25);color:rgba(0,0,0,0.7)}.file.is-light:active .file-cta,.file.is-light.is-active .file-cta{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-dark .file-cta,.content kbd.file .file-cta{background-color:#363636;border-color:transparent;color:#fff}.file.is-dark:hover .file-cta,.content kbd.file:hover .file-cta,.file.is-dark.is-hovered .file-cta,.content kbd.file.is-hovered .file-cta{background-color:#2f2f2f;border-color:transparent;color:#fff}.file.is-dark:focus .file-cta,.content kbd.file:focus .file-cta,.file.is-dark.is-focused .file-cta,.content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(54,54,54,0.25);color:#fff}.file.is-dark:active .file-cta,.content kbd.file:active .file-cta,.file.is-dark.is-active .file-cta,.content kbd.file.is-active .file-cta{background-color:#292929;border-color:transparent;color:#fff}.file.is-primary .file-cta,.docstring>section>a.file.docs-sourcelink .file-cta{background-color:#4eb5de;border-color:transparent;color:#fff}.file.is-primary:hover .file-cta,.docstring>section>a.file.docs-sourcelink:hover .file-cta,.file.is-primary.is-hovered .file-cta,.docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#43b1dc;border-color:transparent;color:#fff}.file.is-primary:focus .file-cta,.docstring>section>a.file.docs-sourcelink:focus .file-cta,.file.is-primary.is-focused .file-cta,.docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(78,181,222,0.25);color:#fff}.file.is-primary:active .file-cta,.docstring>section>a.file.docs-sourcelink:active .file-cta,.file.is-primary.is-active .file-cta,.docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#39acda;border-color:transparent;color:#fff}.file.is-link .file-cta{background-color:#2e63b8;border-color:transparent;color:#fff}.file.is-link:hover .file-cta,.file.is-link.is-hovered .file-cta{background-color:#2b5eae;border-color:transparent;color:#fff}.file.is-link:focus .file-cta,.file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(46,99,184,0.25);color:#fff}.file.is-link:active .file-cta,.file.is-link.is-active .file-cta{background-color:#2958a4;border-color:transparent;color:#fff}.file.is-info .file-cta{background-color:#209cee;border-color:transparent;color:#fff}.file.is-info:hover .file-cta,.file.is-info.is-hovered .file-cta{background-color:#1497ed;border-color:transparent;color:#fff}.file.is-info:focus .file-cta,.file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(32,156,238,0.25);color:#fff}.file.is-info:active .file-cta,.file.is-info.is-active .file-cta{background-color:#1190e3;border-color:transparent;color:#fff}.file.is-success .file-cta{background-color:#22c35b;border-color:transparent;color:#fff}.file.is-success:hover .file-cta,.file.is-success.is-hovered .file-cta{background-color:#20b856;border-color:transparent;color:#fff}.file.is-success:focus .file-cta,.file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(34,195,91,0.25);color:#fff}.file.is-success:active .file-cta,.file.is-success.is-active .file-cta{background-color:#1ead51;border-color:transparent;color:#fff}.file.is-warning .file-cta{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:hover .file-cta,.file.is-warning.is-hovered .file-cta{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:focus .file-cta,.file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,221,87,0.25);color:rgba(0,0,0,0.7)}.file.is-warning:active .file-cta,.file.is-warning.is-active .file-cta{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-danger .file-cta{background-color:#da0b00;border-color:transparent;color:#fff}.file.is-danger:hover .file-cta,.file.is-danger.is-hovered .file-cta{background-color:#cd0a00;border-color:transparent;color:#fff}.file.is-danger:focus .file-cta,.file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(218,11,0,0.25);color:#fff}.file.is-danger:active .file-cta,.file.is-danger.is-active .file-cta{background-color:#c10a00;border-color:transparent;color:#fff}.file.is-small,#documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}.file.is-normal{font-size:1rem}.file.is-medium{font-size:1.25rem}.file.is-medium .file-icon .fa{font-size:21px}.file.is-large{font-size:1.5rem}.file.is-large .file-icon .fa{font-size:28px}.file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}.file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}.file.has-name.is-empty .file-cta{border-radius:4px}.file.has-name.is-empty .file-name{display:none}.file.is-boxed .file-label{flex-direction:column}.file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}.file.is-boxed .file-name{border-width:0 1px 1px}.file.is-boxed .file-icon{height:1.5em;width:1.5em}.file.is-boxed .file-icon .fa{font-size:21px}.file.is-boxed.is-small .file-icon .fa,#documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}.file.is-boxed.is-medium .file-icon .fa{font-size:28px}.file.is-boxed.is-large .file-icon .fa{font-size:35px}.file.is-boxed.has-name .file-cta{border-radius:4px 4px 0 0}.file.is-boxed.has-name .file-name{border-radius:0 0 4px 4px;border-width:0 1px 1px}.file.is-centered{justify-content:center}.file.is-fullwidth .file-label{width:100%}.file.is-fullwidth .file-name{flex-grow:1;max-width:none}.file.is-right{justify-content:flex-end}.file.is-right .file-cta{border-radius:0 4px 4px 0}.file.is-right .file-name{border-radius:4px 0 0 4px;border-width:1px 0 1px 1px;order:-1}.file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}.file-label:hover .file-cta{background-color:#eee;color:#222}.file-label:hover .file-name{border-color:#d5d5d5}.file-label:active .file-cta{background-color:#e8e8e8;color:#222}.file-label:active .file-name{border-color:#cfcfcf}.file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}.file-cta,.file-name{border-color:#dbdbdb;border-radius:4px;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}.file-cta{background-color:#f5f5f5;color:#222}.file-name{border-color:#dbdbdb;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}.file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}.file-icon .fa{font-size:14px}.label{color:#222;display:block;font-size:1rem;font-weight:700}.label:not(:last-child){margin-bottom:0.5em}.label.is-small,#documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}.label.is-medium{font-size:1.25rem}.label.is-large{font-size:1.5rem}.help{display:block;font-size:.75rem;margin-top:0.25rem}.help.is-white{color:#fff}.help.is-black{color:#0a0a0a}.help.is-light{color:#f5f5f5}.help.is-dark,.content kbd.help{color:#363636}.help.is-primary,.docstring>section>a.help.docs-sourcelink{color:#4eb5de}.help.is-link{color:#2e63b8}.help.is-info{color:#209cee}.help.is-success{color:#22c35b}.help.is-warning{color:#ffdd57}.help.is-danger{color:#da0b00}.field:not(:last-child){margin-bottom:0.75rem}.field.has-addons{display:flex;justify-content:flex-start}.field.has-addons .control:not(:last-child){margin-right:-1px}.field.has-addons .control:not(:first-child):not(:last-child) .button,.field.has-addons .control:not(:first-child):not(:last-child) .input,.field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,.field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}.field.has-addons .control:first-child:not(:only-child) .button,.field.has-addons .control:first-child:not(:only-child) .input,.field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,.field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}.field.has-addons .control:last-child:not(:only-child) .button,.field.has-addons .control:last-child:not(:only-child) .input,.field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,.field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}.field.has-addons .control .button:not([disabled]):hover,.field.has-addons .control .button.is-hovered:not([disabled]),.field.has-addons .control .input:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,.field.has-addons .control .input.is-hovered:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),.field.has-addons .control .select select:not([disabled]):hover,.field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}.field.has-addons .control .button:not([disabled]):focus,.field.has-addons .control .button.is-focused:not([disabled]),.field.has-addons .control .button:not([disabled]):active,.field.has-addons .control .button.is-active:not([disabled]),.field.has-addons .control .input:not([disabled]):focus,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,.field.has-addons .control .input.is-focused:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),.field.has-addons .control .input:not([disabled]):active,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,.field.has-addons .control .input.is-active:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),.field.has-addons .control .select select:not([disabled]):focus,.field.has-addons .control .select select.is-focused:not([disabled]),.field.has-addons .control .select select:not([disabled]):active,.field.has-addons .control .select select.is-active:not([disabled]){z-index:3}.field.has-addons .control .button:not([disabled]):focus:hover,.field.has-addons .control .button.is-focused:not([disabled]):hover,.field.has-addons .control .button:not([disabled]):active:hover,.field.has-addons .control .button.is-active:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):focus:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,.field.has-addons .control .input.is-focused:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):active:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,.field.has-addons .control .input.is-active:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):focus:hover,.field.has-addons .control .select select.is-focused:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):active:hover,.field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}.field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}.field.has-addons.has-addons-centered{justify-content:center}.field.has-addons.has-addons-right{justify-content:flex-end}.field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}.field.is-grouped{display:flex;justify-content:flex-start}.field.is-grouped>.control{flex-shrink:0}.field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}.field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}.field.is-grouped.is-grouped-centered{justify-content:center}.field.is-grouped.is-grouped-right{justify-content:flex-end}.field.is-grouped.is-grouped-multiline{flex-wrap:wrap}.field.is-grouped.is-grouped-multiline>.control:last-child,.field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}.field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}.field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{.field.is-horizontal{display:flex}}.field-label .label{font-size:inherit}@media screen and (max-width: 768px){.field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{.field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}.field-label.is-small,#documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}.field-label.is-normal{padding-top:0.375em}.field-label.is-medium{font-size:1.25rem;padding-top:0.375em}.field-label.is-large{font-size:1.5rem;padding-top:0.375em}}.field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{.field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}.field-body .field{margin-bottom:0}.field-body>.field{flex-shrink:1}.field-body>.field:not(.is-narrow){flex-grow:1}.field-body>.field:not(:last-child){margin-right:.75rem}}.control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}.control.has-icons-left .input:focus~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,.control.has-icons-left .select:focus~.icon,.control.has-icons-right .input:focus~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,.control.has-icons-right .select:focus~.icon{color:#222}.control.has-icons-left .input.is-small~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,.control.has-icons-left .select.is-small~.icon,.control.has-icons-right .input.is-small~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,.control.has-icons-right .select.is-small~.icon{font-size:.75rem}.control.has-icons-left .input.is-medium~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,.control.has-icons-left .select.is-medium~.icon,.control.has-icons-right .input.is-medium~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,.control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}.control.has-icons-left .input.is-large~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,.control.has-icons-left .select.is-large~.icon,.control.has-icons-right .input.is-large~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,.control.has-icons-right .select.is-large~.icon{font-size:1.5rem}.control.has-icons-left .icon,.control.has-icons-right .icon{color:#dbdbdb;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}.control.has-icons-left .input,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input,.control.has-icons-left .select select{padding-left:2.5em}.control.has-icons-left .icon.is-left{left:0}.control.has-icons-right .input,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input,.control.has-icons-right .select select{padding-right:2.5em}.control.has-icons-right .icon.is-right{right:0}.control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}.control.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.control.is-loading.is-medium:after{font-size:1.25rem}.control.is-loading.is-large:after{font-size:1.5rem}.breadcrumb{font-size:1rem;white-space:nowrap}.breadcrumb a{align-items:center;color:#2e63b8;display:flex;justify-content:center;padding:0 .75em}.breadcrumb a:hover{color:#363636}.breadcrumb li{align-items:center;display:flex}.breadcrumb li:first-child a{padding-left:0}.breadcrumb li.is-active a{color:#222;cursor:default;pointer-events:none}.breadcrumb li+li::before{color:#b5b5b5;content:"\0002f"}.breadcrumb ul,.breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}.breadcrumb .icon:first-child{margin-right:.5em}.breadcrumb .icon:last-child{margin-left:.5em}.breadcrumb.is-centered ol,.breadcrumb.is-centered ul{justify-content:center}.breadcrumb.is-right ol,.breadcrumb.is-right ul{justify-content:flex-end}.breadcrumb.is-small,#documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}.breadcrumb.is-medium{font-size:1.25rem}.breadcrumb.is-large{font-size:1.5rem}.breadcrumb.has-arrow-separator li+li::before{content:"\02192"}.breadcrumb.has-bullet-separator li+li::before{content:"\02022"}.breadcrumb.has-dot-separator li+li::before{content:"\000b7"}.breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}.card{background-color:#fff;border-radius:.25rem;box-shadow:#bbb;color:#222;max-width:100%;position:relative}.card-footer:first-child,.card-content:first-child,.card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-footer:last-child,.card-content:last-child,.card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}.card-header-title{align-items:center;color:#222;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}.card-header-title.is-centered{justify-content:center}.card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}.card-image{display:block;position:relative}.card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-content{background-color:rgba(0,0,0,0);padding:1.5rem}.card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}.card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}.card-footer-item:not(:last-child){border-right:1px solid #ededed}.card .media:not(:last-child){margin-bottom:1.5rem}.dropdown{display:inline-flex;position:relative;vertical-align:top}.dropdown.is-active .dropdown-menu,.dropdown.is-hoverable:hover .dropdown-menu{display:block}.dropdown.is-right .dropdown-menu{left:auto;right:0}.dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}.dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}.dropdown-content{background-color:#fff;border-radius:4px;box-shadow:#bbb;padding-bottom:.5rem;padding-top:.5rem}.dropdown-item{color:#222;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}a.dropdown-item,button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}a.dropdown-item:hover,button.dropdown-item:hover{background-color:#f5f5f5;color:#0a0a0a}a.dropdown-item.is-active,button.dropdown-item.is-active{background-color:#2e63b8;color:#fff}.dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}.level{align-items:center;justify-content:space-between}.level code{border-radius:4px}.level img{display:inline-block;vertical-align:top}.level.is-mobile{display:flex}.level.is-mobile .level-left,.level.is-mobile .level-right{display:flex}.level.is-mobile .level-left+.level-right{margin-top:0}.level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}.level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{.level{display:flex}.level>.level-item:not(.is-narrow){flex-grow:1}}.level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}.level-item .title,.level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){.level-item:not(:last-child){margin-bottom:.75rem}}.level-left,.level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.level-left .level-item.is-flexible,.level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{.level-left .level-item:not(:last-child),.level-right .level-item:not(:last-child){margin-right:.75rem}}.level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){.level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{.level-left{display:flex}}.level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{.level-right{display:flex}}.media{align-items:flex-start;display:flex;text-align:inherit}.media .content:not(:last-child){margin-bottom:.75rem}.media .media{border-top:1px solid rgba(219,219,219,0.5);display:flex;padding-top:.75rem}.media .media .content:not(:last-child),.media .media .control:not(:last-child){margin-bottom:.5rem}.media .media .media{padding-top:.5rem}.media .media .media+.media{margin-top:.5rem}.media+.media{border-top:1px solid rgba(219,219,219,0.5);margin-top:1rem;padding-top:1rem}.media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}.media-left,.media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.media-left{margin-right:1rem}.media-right{margin-left:1rem}.media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){.media-content{overflow-x:auto}}.menu{font-size:1rem}.menu.is-small,#documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}.menu.is-medium{font-size:1.25rem}.menu.is-large{font-size:1.5rem}.menu-list{line-height:1.25}.menu-list a{border-radius:2px;color:#222;display:block;padding:0.5em 0.75em}.menu-list a:hover{background-color:#f5f5f5;color:#222}.menu-list a.is-active{background-color:#2e63b8;color:#fff}.menu-list li ul{border-left:1px solid #dbdbdb;margin:.75em;padding-left:.75em}.menu-label{color:#6b6b6b;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}.menu-label:not(:first-child){margin-top:1em}.menu-label:not(:last-child){margin-bottom:1em}.message{background-color:#f5f5f5;border-radius:4px;font-size:1rem}.message strong{color:currentColor}.message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}.message.is-small,#documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}.message.is-medium{font-size:1.25rem}.message.is-large{font-size:1.5rem}.message.is-white{background-color:#fff}.message.is-white .message-header{background-color:#fff;color:#0a0a0a}.message.is-white .message-body{border-color:#fff}.message.is-black{background-color:#fafafa}.message.is-black .message-header{background-color:#0a0a0a;color:#fff}.message.is-black .message-body{border-color:#0a0a0a}.message.is-light{background-color:#fafafa}.message.is-light .message-header{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.message.is-light .message-body{border-color:#f5f5f5}.message.is-dark,.content kbd.message{background-color:#fafafa}.message.is-dark .message-header,.content kbd.message .message-header{background-color:#363636;color:#fff}.message.is-dark .message-body,.content kbd.message .message-body{border-color:#363636}.message.is-primary,.docstring>section>a.message.docs-sourcelink{background-color:#eef8fc}.message.is-primary .message-header,.docstring>section>a.message.docs-sourcelink .message-header{background-color:#4eb5de;color:#fff}.message.is-primary .message-body,.docstring>section>a.message.docs-sourcelink .message-body{border-color:#4eb5de;color:#1a6d8e}.message.is-link{background-color:#eff3fb}.message.is-link .message-header{background-color:#2e63b8;color:#fff}.message.is-link .message-body{border-color:#2e63b8;color:#3169c4}.message.is-info{background-color:#ecf7fe}.message.is-info .message-header{background-color:#209cee;color:#fff}.message.is-info .message-body{border-color:#209cee;color:#0e72b4}.message.is-success{background-color:#eefcf3}.message.is-success .message-header{background-color:#22c35b;color:#fff}.message.is-success .message-body{border-color:#22c35b;color:#198f43}.message.is-warning{background-color:#fffbeb}.message.is-warning .message-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.message.is-warning .message-body{border-color:#ffdd57;color:#947600}.message.is-danger{background-color:#ffeceb}.message.is-danger .message-header{background-color:#da0b00;color:#fff}.message.is-danger .message-body{border-color:#da0b00;color:#f50c00}.message-header{align-items:center;background-color:#222;border-radius:4px 4px 0 0;color:#fff;display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}.message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}.message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}.message-body{border-color:#dbdbdb;border-radius:4px;border-style:solid;border-width:0 0 0 4px;color:#222;padding:1.25em 1.5em}.message-body code,.message-body pre{background-color:#fff}.message-body pre code{background-color:rgba(0,0,0,0)}.modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}.modal.is-active{display:flex}.modal-background{background-color:rgba(10,10,10,0.86)}.modal-content,.modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){.modal-content,.modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}.modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}.modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}.modal-card-head,.modal-card-foot{align-items:center;background-color:#f5f5f5;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}.modal-card-head{border-bottom:1px solid #dbdbdb;border-top-left-radius:6px;border-top-right-radius:6px}.modal-card-title{color:#222;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}.modal-card-foot{border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:1px solid #dbdbdb}.modal-card-foot .button:not(:last-child){margin-right:.5em}.modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}.navbar{background-color:#fff;min-height:3.25rem;position:relative;z-index:30}.navbar.is-white{background-color:#fff;color:#0a0a0a}.navbar.is-white .navbar-brand>.navbar-item,.navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-brand>a.navbar-item:focus,.navbar.is-white .navbar-brand>a.navbar-item:hover,.navbar.is-white .navbar-brand>a.navbar-item.is-active,.navbar.is-white .navbar-brand .navbar-link:focus,.navbar.is-white .navbar-brand .navbar-link:hover,.navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){.navbar.is-white .navbar-start>.navbar-item,.navbar.is-white .navbar-start .navbar-link,.navbar.is-white .navbar-end>.navbar-item,.navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-start>a.navbar-item:focus,.navbar.is-white .navbar-start>a.navbar-item:hover,.navbar.is-white .navbar-start>a.navbar-item.is-active,.navbar.is-white .navbar-start .navbar-link:focus,.navbar.is-white .navbar-start .navbar-link:hover,.navbar.is-white .navbar-start .navbar-link.is-active,.navbar.is-white .navbar-end>a.navbar-item:focus,.navbar.is-white .navbar-end>a.navbar-item:hover,.navbar.is-white .navbar-end>a.navbar-item.is-active,.navbar.is-white .navbar-end .navbar-link:focus,.navbar.is-white .navbar-end .navbar-link:hover,.navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-start .navbar-link::after,.navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}.navbar.is-black{background-color:#0a0a0a;color:#fff}.navbar.is-black .navbar-brand>.navbar-item,.navbar.is-black .navbar-brand .navbar-link{color:#fff}.navbar.is-black .navbar-brand>a.navbar-item:focus,.navbar.is-black .navbar-brand>a.navbar-item:hover,.navbar.is-black .navbar-brand>a.navbar-item.is-active,.navbar.is-black .navbar-brand .navbar-link:focus,.navbar.is-black .navbar-brand .navbar-link:hover,.navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-black .navbar-start>.navbar-item,.navbar.is-black .navbar-start .navbar-link,.navbar.is-black .navbar-end>.navbar-item,.navbar.is-black .navbar-end .navbar-link{color:#fff}.navbar.is-black .navbar-start>a.navbar-item:focus,.navbar.is-black .navbar-start>a.navbar-item:hover,.navbar.is-black .navbar-start>a.navbar-item.is-active,.navbar.is-black .navbar-start .navbar-link:focus,.navbar.is-black .navbar-start .navbar-link:hover,.navbar.is-black .navbar-start .navbar-link.is-active,.navbar.is-black .navbar-end>a.navbar-item:focus,.navbar.is-black .navbar-end>a.navbar-item:hover,.navbar.is-black .navbar-end>a.navbar-item.is-active,.navbar.is-black .navbar-end .navbar-link:focus,.navbar.is-black .navbar-end .navbar-link:hover,.navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-start .navbar-link::after,.navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}.navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}.navbar.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>.navbar-item,.navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>a.navbar-item:focus,.navbar.is-light .navbar-brand>a.navbar-item:hover,.navbar.is-light .navbar-brand>a.navbar-item.is-active,.navbar.is-light .navbar-brand .navbar-link:focus,.navbar.is-light .navbar-brand .navbar-link:hover,.navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-light .navbar-start>.navbar-item,.navbar.is-light .navbar-start .navbar-link,.navbar.is-light .navbar-end>.navbar-item,.navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start>a.navbar-item:focus,.navbar.is-light .navbar-start>a.navbar-item:hover,.navbar.is-light .navbar-start>a.navbar-item.is-active,.navbar.is-light .navbar-start .navbar-link:focus,.navbar.is-light .navbar-start .navbar-link:hover,.navbar.is-light .navbar-start .navbar-link.is-active,.navbar.is-light .navbar-end>a.navbar-item:focus,.navbar.is-light .navbar-end>a.navbar-item:hover,.navbar.is-light .navbar-end>a.navbar-item.is-active,.navbar.is-light .navbar-end .navbar-link:focus,.navbar.is-light .navbar-end .navbar-link:hover,.navbar.is-light .navbar-end .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start .navbar-link::after,.navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}}.navbar.is-dark,.content kbd.navbar{background-color:#363636;color:#fff}.navbar.is-dark .navbar-brand>.navbar-item,.content kbd.navbar .navbar-brand>.navbar-item,.navbar.is-dark .navbar-brand .navbar-link,.content kbd.navbar .navbar-brand .navbar-link{color:#fff}.navbar.is-dark .navbar-brand>a.navbar-item:focus,.content kbd.navbar .navbar-brand>a.navbar-item:focus,.navbar.is-dark .navbar-brand>a.navbar-item:hover,.content kbd.navbar .navbar-brand>a.navbar-item:hover,.navbar.is-dark .navbar-brand>a.navbar-item.is-active,.content kbd.navbar .navbar-brand>a.navbar-item.is-active,.navbar.is-dark .navbar-brand .navbar-link:focus,.content kbd.navbar .navbar-brand .navbar-link:focus,.navbar.is-dark .navbar-brand .navbar-link:hover,.content kbd.navbar .navbar-brand .navbar-link:hover,.navbar.is-dark .navbar-brand .navbar-link.is-active,.content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-brand .navbar-link::after,.content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-burger,.content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-dark .navbar-start>.navbar-item,.content kbd.navbar .navbar-start>.navbar-item,.navbar.is-dark .navbar-start .navbar-link,.content kbd.navbar .navbar-start .navbar-link,.navbar.is-dark .navbar-end>.navbar-item,.content kbd.navbar .navbar-end>.navbar-item,.navbar.is-dark .navbar-end .navbar-link,.content kbd.navbar .navbar-end .navbar-link{color:#fff}.navbar.is-dark .navbar-start>a.navbar-item:focus,.content kbd.navbar .navbar-start>a.navbar-item:focus,.navbar.is-dark .navbar-start>a.navbar-item:hover,.content kbd.navbar .navbar-start>a.navbar-item:hover,.navbar.is-dark .navbar-start>a.navbar-item.is-active,.content kbd.navbar .navbar-start>a.navbar-item.is-active,.navbar.is-dark .navbar-start .navbar-link:focus,.content kbd.navbar .navbar-start .navbar-link:focus,.navbar.is-dark .navbar-start .navbar-link:hover,.content kbd.navbar .navbar-start .navbar-link:hover,.navbar.is-dark .navbar-start .navbar-link.is-active,.content kbd.navbar .navbar-start .navbar-link.is-active,.navbar.is-dark .navbar-end>a.navbar-item:focus,.content kbd.navbar .navbar-end>a.navbar-item:focus,.navbar.is-dark .navbar-end>a.navbar-item:hover,.content kbd.navbar .navbar-end>a.navbar-item:hover,.navbar.is-dark .navbar-end>a.navbar-item.is-active,.content kbd.navbar .navbar-end>a.navbar-item.is-active,.navbar.is-dark .navbar-end .navbar-link:focus,.content kbd.navbar .navbar-end .navbar-link:focus,.navbar.is-dark .navbar-end .navbar-link:hover,.content kbd.navbar .navbar-end .navbar-link:hover,.navbar.is-dark .navbar-end .navbar-link.is-active,.content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-start .navbar-link::after,.content kbd.navbar .navbar-start .navbar-link::after,.navbar.is-dark .navbar-end .navbar-link::after,.content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,.content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#292929;color:#fff}.navbar.is-dark .navbar-dropdown a.navbar-item.is-active,.content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#363636;color:#fff}}.navbar.is-primary,.docstring>section>a.navbar.docs-sourcelink{background-color:#4eb5de;color:#fff}.navbar.is-primary .navbar-brand>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,.navbar.is-primary .navbar-brand .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}.navbar.is-primary .navbar-brand>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,.navbar.is-primary .navbar-brand>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,.navbar.is-primary .navbar-brand>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,.navbar.is-primary .navbar-brand .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,.navbar.is-primary .navbar-brand .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,.navbar.is-primary .navbar-brand .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-brand .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-burger,.docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-primary .navbar-start>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,.navbar.is-primary .navbar-start .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,.navbar.is-primary .navbar-end>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,.navbar.is-primary .navbar-end .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}.navbar.is-primary .navbar-start>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,.navbar.is-primary .navbar-start>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,.navbar.is-primary .navbar-start>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,.navbar.is-primary .navbar-start .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,.navbar.is-primary .navbar-start .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,.navbar.is-primary .navbar-start .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,.navbar.is-primary .navbar-end>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,.navbar.is-primary .navbar-end>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,.navbar.is-primary .navbar-end>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,.navbar.is-primary .navbar-end .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,.navbar.is-primary .navbar-end .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,.navbar.is-primary .navbar-end .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-start .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,.navbar.is-primary .navbar-end .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-dropdown a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#4eb5de;color:#fff}}.navbar.is-link{background-color:#2e63b8;color:#fff}.navbar.is-link .navbar-brand>.navbar-item,.navbar.is-link .navbar-brand .navbar-link{color:#fff}.navbar.is-link .navbar-brand>a.navbar-item:focus,.navbar.is-link .navbar-brand>a.navbar-item:hover,.navbar.is-link .navbar-brand>a.navbar-item.is-active,.navbar.is-link .navbar-brand .navbar-link:focus,.navbar.is-link .navbar-brand .navbar-link:hover,.navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-link .navbar-start>.navbar-item,.navbar.is-link .navbar-start .navbar-link,.navbar.is-link .navbar-end>.navbar-item,.navbar.is-link .navbar-end .navbar-link{color:#fff}.navbar.is-link .navbar-start>a.navbar-item:focus,.navbar.is-link .navbar-start>a.navbar-item:hover,.navbar.is-link .navbar-start>a.navbar-item.is-active,.navbar.is-link .navbar-start .navbar-link:focus,.navbar.is-link .navbar-start .navbar-link:hover,.navbar.is-link .navbar-start .navbar-link.is-active,.navbar.is-link .navbar-end>a.navbar-item:focus,.navbar.is-link .navbar-end>a.navbar-item:hover,.navbar.is-link .navbar-end>a.navbar-item.is-active,.navbar.is-link .navbar-end .navbar-link:focus,.navbar.is-link .navbar-end .navbar-link:hover,.navbar.is-link .navbar-end .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-start .navbar-link::after,.navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#2e63b8;color:#fff}}.navbar.is-info{background-color:#209cee;color:#fff}.navbar.is-info .navbar-brand>.navbar-item,.navbar.is-info .navbar-brand .navbar-link{color:#fff}.navbar.is-info .navbar-brand>a.navbar-item:focus,.navbar.is-info .navbar-brand>a.navbar-item:hover,.navbar.is-info .navbar-brand>a.navbar-item.is-active,.navbar.is-info .navbar-brand .navbar-link:focus,.navbar.is-info .navbar-brand .navbar-link:hover,.navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-info .navbar-start>.navbar-item,.navbar.is-info .navbar-start .navbar-link,.navbar.is-info .navbar-end>.navbar-item,.navbar.is-info .navbar-end .navbar-link{color:#fff}.navbar.is-info .navbar-start>a.navbar-item:focus,.navbar.is-info .navbar-start>a.navbar-item:hover,.navbar.is-info .navbar-start>a.navbar-item.is-active,.navbar.is-info .navbar-start .navbar-link:focus,.navbar.is-info .navbar-start .navbar-link:hover,.navbar.is-info .navbar-start .navbar-link.is-active,.navbar.is-info .navbar-end>a.navbar-item:focus,.navbar.is-info .navbar-end>a.navbar-item:hover,.navbar.is-info .navbar-end>a.navbar-item.is-active,.navbar.is-info .navbar-end .navbar-link:focus,.navbar.is-info .navbar-end .navbar-link:hover,.navbar.is-info .navbar-end .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-start .navbar-link::after,.navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#209cee;color:#fff}}.navbar.is-success{background-color:#22c35b;color:#fff}.navbar.is-success .navbar-brand>.navbar-item,.navbar.is-success .navbar-brand .navbar-link{color:#fff}.navbar.is-success .navbar-brand>a.navbar-item:focus,.navbar.is-success .navbar-brand>a.navbar-item:hover,.navbar.is-success .navbar-brand>a.navbar-item.is-active,.navbar.is-success .navbar-brand .navbar-link:focus,.navbar.is-success .navbar-brand .navbar-link:hover,.navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-success .navbar-start>.navbar-item,.navbar.is-success .navbar-start .navbar-link,.navbar.is-success .navbar-end>.navbar-item,.navbar.is-success .navbar-end .navbar-link{color:#fff}.navbar.is-success .navbar-start>a.navbar-item:focus,.navbar.is-success .navbar-start>a.navbar-item:hover,.navbar.is-success .navbar-start>a.navbar-item.is-active,.navbar.is-success .navbar-start .navbar-link:focus,.navbar.is-success .navbar-start .navbar-link:hover,.navbar.is-success .navbar-start .navbar-link.is-active,.navbar.is-success .navbar-end>a.navbar-item:focus,.navbar.is-success .navbar-end>a.navbar-item:hover,.navbar.is-success .navbar-end>a.navbar-item.is-active,.navbar.is-success .navbar-end .navbar-link:focus,.navbar.is-success .navbar-end .navbar-link:hover,.navbar.is-success .navbar-end .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-start .navbar-link::after,.navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#22c35b;color:#fff}}.navbar.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>.navbar-item,.navbar.is-warning .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>a.navbar-item:focus,.navbar.is-warning .navbar-brand>a.navbar-item:hover,.navbar.is-warning .navbar-brand>a.navbar-item.is-active,.navbar.is-warning .navbar-brand .navbar-link:focus,.navbar.is-warning .navbar-brand .navbar-link:hover,.navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-warning .navbar-start>.navbar-item,.navbar.is-warning .navbar-start .navbar-link,.navbar.is-warning .navbar-end>.navbar-item,.navbar.is-warning .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start>a.navbar-item:focus,.navbar.is-warning .navbar-start>a.navbar-item:hover,.navbar.is-warning .navbar-start>a.navbar-item.is-active,.navbar.is-warning .navbar-start .navbar-link:focus,.navbar.is-warning .navbar-start .navbar-link:hover,.navbar.is-warning .navbar-start .navbar-link.is-active,.navbar.is-warning .navbar-end>a.navbar-item:focus,.navbar.is-warning .navbar-end>a.navbar-item:hover,.navbar.is-warning .navbar-end>a.navbar-item.is-active,.navbar.is-warning .navbar-end .navbar-link:focus,.navbar.is-warning .navbar-end .navbar-link:hover,.navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start .navbar-link::after,.navbar.is-warning .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ffdd57;color:rgba(0,0,0,0.7)}}.navbar.is-danger{background-color:#da0b00;color:#fff}.navbar.is-danger .navbar-brand>.navbar-item,.navbar.is-danger .navbar-brand .navbar-link{color:#fff}.navbar.is-danger .navbar-brand>a.navbar-item:focus,.navbar.is-danger .navbar-brand>a.navbar-item:hover,.navbar.is-danger .navbar-brand>a.navbar-item.is-active,.navbar.is-danger .navbar-brand .navbar-link:focus,.navbar.is-danger .navbar-brand .navbar-link:hover,.navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-danger .navbar-start>.navbar-item,.navbar.is-danger .navbar-start .navbar-link,.navbar.is-danger .navbar-end>.navbar-item,.navbar.is-danger .navbar-end .navbar-link{color:#fff}.navbar.is-danger .navbar-start>a.navbar-item:focus,.navbar.is-danger .navbar-start>a.navbar-item:hover,.navbar.is-danger .navbar-start>a.navbar-item.is-active,.navbar.is-danger .navbar-start .navbar-link:focus,.navbar.is-danger .navbar-start .navbar-link:hover,.navbar.is-danger .navbar-start .navbar-link.is-active,.navbar.is-danger .navbar-end>a.navbar-item:focus,.navbar.is-danger .navbar-end>a.navbar-item:hover,.navbar.is-danger .navbar-end>a.navbar-item.is-active,.navbar.is-danger .navbar-end .navbar-link:focus,.navbar.is-danger .navbar-end .navbar-link:hover,.navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-start .navbar-link::after,.navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#da0b00;color:#fff}}.navbar>.container{align-items:stretch;display:flex;min-height:3.25rem;width:100%}.navbar.has-shadow{box-shadow:0 2px 0 0 #f5f5f5}.navbar.is-fixed-bottom,.navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom{bottom:0}.navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #f5f5f5}.navbar.is-fixed-top{top:0}html.has-navbar-fixed-top,body.has-navbar-fixed-top{padding-top:3.25rem}html.has-navbar-fixed-bottom,body.has-navbar-fixed-bottom{padding-bottom:3.25rem}.navbar-brand,.navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:3.25rem}.navbar-brand a.navbar-item:focus,.navbar-brand a.navbar-item:hover{background-color:transparent}.navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}.navbar-burger{color:#222;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:3.25rem;position:relative;width:3.25rem;margin-left:auto}.navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}.navbar-burger span:nth-child(1){top:calc(50% - 6px)}.navbar-burger span:nth-child(2){top:calc(50% - 1px)}.navbar-burger span:nth-child(3){top:calc(50% + 4px)}.navbar-burger:hover{background-color:rgba(0,0,0,0.05)}.navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}.navbar-burger.is-active span:nth-child(2){opacity:0}.navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}.navbar-menu{display:none}.navbar-item,.navbar-link{color:#222;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}.navbar-item .icon:only-child,.navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}a.navbar-item,.navbar-link{cursor:pointer}a.navbar-item:focus,a.navbar-item:focus-within,a.navbar-item:hover,a.navbar-item.is-active,.navbar-link:focus,.navbar-link:focus-within,.navbar-link:hover,.navbar-link.is-active{background-color:#fafafa;color:#2e63b8}.navbar-item{flex-grow:0;flex-shrink:0}.navbar-item img{max-height:1.75rem}.navbar-item.has-dropdown{padding:0}.navbar-item.is-expanded{flex-grow:1;flex-shrink:1}.navbar-item.is-tab{border-bottom:1px solid transparent;min-height:3.25rem;padding-bottom:calc(0.5rem - 1px)}.navbar-item.is-tab:focus,.navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8}.navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8;border-bottom-style:solid;border-bottom-width:3px;color:#2e63b8;padding-bottom:calc(0.5rem - 3px)}.navbar-content{flex-grow:1;flex-shrink:1}.navbar-link:not(.is-arrowless){padding-right:2.5em}.navbar-link:not(.is-arrowless)::after{border-color:#2e63b8;margin-top:-0.375em;right:1.125em}.navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}.navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}.navbar-divider{background-color:#f5f5f5;border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){.navbar>.container{display:block}.navbar-brand .navbar-item,.navbar-tabs .navbar-item{align-items:center;display:flex}.navbar-link::after{display:none}.navbar-menu{background-color:#fff;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}.navbar-menu.is-active{display:block}.navbar.is-fixed-bottom-touch,.navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-touch{bottom:0}.navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-touch{top:0}.navbar.is-fixed-top .navbar-menu,.navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 3.25rem);overflow:auto}html.has-navbar-fixed-top-touch,body.has-navbar-fixed-top-touch{padding-top:3.25rem}html.has-navbar-fixed-bottom-touch,body.has-navbar-fixed-bottom-touch{padding-bottom:3.25rem}}@media screen and (min-width: 1056px){.navbar,.navbar-menu,.navbar-start,.navbar-end{align-items:stretch;display:flex}.navbar{min-height:3.25rem}.navbar.is-spaced{padding:1rem 2rem}.navbar.is-spaced .navbar-start,.navbar.is-spaced .navbar-end{align-items:center}.navbar.is-spaced a.navbar-item,.navbar.is-spaced .navbar-link{border-radius:4px}.navbar.is-transparent a.navbar-item:focus,.navbar.is-transparent a.navbar-item:hover,.navbar.is-transparent a.navbar-item.is-active,.navbar.is-transparent .navbar-link:focus,.navbar.is-transparent .navbar-link:hover,.navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}.navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}.navbar.is-transparent .navbar-dropdown a.navbar-item:focus,.navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar-burger{display:none}.navbar-item,.navbar-link{align-items:center;display:flex}.navbar-item.has-dropdown{align-items:stretch}.navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}.navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:2px solid #dbdbdb;border-radius:6px 6px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}.navbar-item.is-active .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced .navbar-item.is-active .navbar-dropdown,.navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:hover .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}.navbar-menu{flex-grow:1;flex-shrink:0}.navbar-start{justify-content:flex-start;margin-right:auto}.navbar-end{justify-content:flex-end;margin-left:auto}.navbar-dropdown{background-color:#fff;border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:2px solid #dbdbdb;box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}.navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}.navbar-dropdown a.navbar-item{padding-right:3rem}.navbar-dropdown a.navbar-item:focus,.navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar.is-spaced .navbar-dropdown,.navbar-dropdown.is-boxed{border-radius:6px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}.navbar-dropdown.is-right{left:auto;right:0}.navbar-divider{display:block}.navbar>.container .navbar-brand,.container>.navbar .navbar-brand{margin-left:-.75rem}.navbar>.container .navbar-menu,.container>.navbar .navbar-menu{margin-right:-.75rem}.navbar.is-fixed-bottom-desktop,.navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-desktop{bottom:0}.navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-desktop{top:0}html.has-navbar-fixed-top-desktop,body.has-navbar-fixed-top-desktop{padding-top:3.25rem}html.has-navbar-fixed-bottom-desktop,body.has-navbar-fixed-bottom-desktop{padding-bottom:3.25rem}html.has-spaced-navbar-fixed-top,body.has-spaced-navbar-fixed-top{padding-top:5.25rem}html.has-spaced-navbar-fixed-bottom,body.has-spaced-navbar-fixed-bottom{padding-bottom:5.25rem}a.navbar-item.is-active,.navbar-link.is-active{color:#0a0a0a}a.navbar-item.is-active:not(:focus):not(:hover),.navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}.navbar-item.has-dropdown:focus .navbar-link,.navbar-item.has-dropdown:hover .navbar-link,.navbar-item.has-dropdown.is-active .navbar-link{background-color:#fafafa}}.hero.is-fullheight-with-navbar{min-height:calc(100vh - 3.25rem)}.pagination{font-size:1rem;margin:-.25rem}.pagination.is-small,#documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}.pagination.is-medium{font-size:1.25rem}.pagination.is-large{font-size:1.5rem}.pagination.is-rounded .pagination-previous,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,.pagination.is-rounded .pagination-next,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}.pagination.is-rounded .pagination-link,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}.pagination,.pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}.pagination-previous,.pagination-next,.pagination-link{border-color:#dbdbdb;color:#222;min-width:2.5em}.pagination-previous:hover,.pagination-next:hover,.pagination-link:hover{border-color:#b5b5b5;color:#363636}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus{border-color:#3c5dcd}.pagination-previous:active,.pagination-next:active,.pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}.pagination-previous[disabled],.pagination-previous.is-disabled,.pagination-next[disabled],.pagination-next.is-disabled,.pagination-link[disabled],.pagination-link.is-disabled{background-color:#dbdbdb;border-color:#dbdbdb;box-shadow:none;color:#6b6b6b;opacity:0.5}.pagination-previous,.pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}.pagination-link.is-current{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.pagination-ellipsis{color:#b5b5b5;pointer-events:none}.pagination-list{flex-wrap:wrap}.pagination-list li{list-style:none}@media screen and (max-width: 768px){.pagination{flex-wrap:wrap}.pagination-previous,.pagination-next{flex-grow:1;flex-shrink:1}.pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{.pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{margin-bottom:0;margin-top:0}.pagination-previous{order:2}.pagination-next{order:3}.pagination{justify-content:space-between;margin-bottom:0;margin-top:0}.pagination.is-centered .pagination-previous{order:1}.pagination.is-centered .pagination-list{justify-content:center;order:2}.pagination.is-centered .pagination-next{order:3}.pagination.is-right .pagination-previous{order:1}.pagination.is-right .pagination-next{order:2}.pagination.is-right .pagination-list{justify-content:flex-end;order:3}}.panel{border-radius:6px;box-shadow:#bbb;font-size:1rem}.panel:not(:last-child){margin-bottom:1.5rem}.panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}.panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}.panel.is-white .panel-block.is-active .panel-icon{color:#fff}.panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}.panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}.panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}.panel.is-light .panel-heading{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.panel.is-light .panel-tabs a.is-active{border-bottom-color:#f5f5f5}.panel.is-light .panel-block.is-active .panel-icon{color:#f5f5f5}.panel.is-dark .panel-heading,.content kbd.panel .panel-heading{background-color:#363636;color:#fff}.panel.is-dark .panel-tabs a.is-active,.content kbd.panel .panel-tabs a.is-active{border-bottom-color:#363636}.panel.is-dark .panel-block.is-active .panel-icon,.content kbd.panel .panel-block.is-active .panel-icon{color:#363636}.panel.is-primary .panel-heading,.docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#4eb5de;color:#fff}.panel.is-primary .panel-tabs a.is-active,.docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#4eb5de}.panel.is-primary .panel-block.is-active .panel-icon,.docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#4eb5de}.panel.is-link .panel-heading{background-color:#2e63b8;color:#fff}.panel.is-link .panel-tabs a.is-active{border-bottom-color:#2e63b8}.panel.is-link .panel-block.is-active .panel-icon{color:#2e63b8}.panel.is-info .panel-heading{background-color:#209cee;color:#fff}.panel.is-info .panel-tabs a.is-active{border-bottom-color:#209cee}.panel.is-info .panel-block.is-active .panel-icon{color:#209cee}.panel.is-success .panel-heading{background-color:#22c35b;color:#fff}.panel.is-success .panel-tabs a.is-active{border-bottom-color:#22c35b}.panel.is-success .panel-block.is-active .panel-icon{color:#22c35b}.panel.is-warning .panel-heading{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ffdd57}.panel.is-warning .panel-block.is-active .panel-icon{color:#ffdd57}.panel.is-danger .panel-heading{background-color:#da0b00;color:#fff}.panel.is-danger .panel-tabs a.is-active{border-bottom-color:#da0b00}.panel.is-danger .panel-block.is-active .panel-icon{color:#da0b00}.panel-tabs:not(:last-child),.panel-block:not(:last-child){border-bottom:1px solid #ededed}.panel-heading{background-color:#ededed;border-radius:6px 6px 0 0;color:#222;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}.panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}.panel-tabs a{border-bottom:1px solid #dbdbdb;margin-bottom:-1px;padding:0.5em}.panel-tabs a.is-active{border-bottom-color:#4a4a4a;color:#363636}.panel-list a{color:#222}.panel-list a:hover{color:#2e63b8}.panel-block{align-items:center;color:#222;display:flex;justify-content:flex-start;padding:0.5em 0.75em}.panel-block input[type="checkbox"]{margin-right:.75em}.panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}.panel-block.is-wrapped{flex-wrap:wrap}.panel-block.is-active{border-left-color:#2e63b8;color:#363636}.panel-block.is-active .panel-icon{color:#2e63b8}.panel-block:last-child{border-bottom-left-radius:6px;border-bottom-right-radius:6px}a.panel-block,label.panel-block{cursor:pointer}a.panel-block:hover,label.panel-block:hover{background-color:#f5f5f5}.panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#6b6b6b;margin-right:.75em}.panel-icon .fa{font-size:inherit;line-height:inherit}.tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}.tabs a{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;color:#222;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}.tabs a:hover{border-bottom-color:#222;color:#222}.tabs li{display:block}.tabs li.is-active a{border-bottom-color:#2e63b8;color:#2e63b8}.tabs ul{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}.tabs ul.is-left{padding-right:0.75em}.tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}.tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}.tabs .icon:first-child{margin-right:.5em}.tabs .icon:last-child{margin-left:.5em}.tabs.is-centered ul{justify-content:center}.tabs.is-right ul{justify-content:flex-end}.tabs.is-boxed a{border:1px solid transparent;border-radius:4px 4px 0 0}.tabs.is-boxed a:hover{background-color:#f5f5f5;border-bottom-color:#dbdbdb}.tabs.is-boxed li.is-active a{background-color:#fff;border-color:#dbdbdb;border-bottom-color:rgba(0,0,0,0) !important}.tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}.tabs.is-toggle a{border-color:#dbdbdb;border-style:solid;border-width:1px;margin-bottom:0;position:relative}.tabs.is-toggle a:hover{background-color:#f5f5f5;border-color:#b5b5b5;z-index:2}.tabs.is-toggle li+li{margin-left:-1px}.tabs.is-toggle li:first-child a{border-top-left-radius:4px;border-bottom-left-radius:4px}.tabs.is-toggle li:last-child a{border-top-right-radius:4px;border-bottom-right-radius:4px}.tabs.is-toggle li.is-active a{background-color:#2e63b8;border-color:#2e63b8;color:#fff;z-index:1}.tabs.is-toggle ul{border-bottom:none}.tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}.tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}.tabs.is-small,#documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}.tabs.is-medium{font-size:1.25rem}.tabs.is-large{font-size:1.5rem}.column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>.column.is-narrow{flex:none;width:unset}.columns.is-mobile>.column.is-full{flex:none;width:100%}.columns.is-mobile>.column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>.column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>.column.is-half{flex:none;width:50%}.columns.is-mobile>.column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>.column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>.column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>.column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>.column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>.column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>.column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>.column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>.column.is-offset-half{margin-left:50%}.columns.is-mobile>.column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>.column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>.column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>.column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>.column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>.column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>.column.is-0{flex:none;width:0%}.columns.is-mobile>.column.is-offset-0{margin-left:0%}.columns.is-mobile>.column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>.column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>.column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>.column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>.column.is-3{flex:none;width:25%}.columns.is-mobile>.column.is-offset-3{margin-left:25%}.columns.is-mobile>.column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>.column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>.column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>.column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>.column.is-6{flex:none;width:50%}.columns.is-mobile>.column.is-offset-6{margin-left:50%}.columns.is-mobile>.column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>.column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>.column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>.column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>.column.is-9{flex:none;width:75%}.columns.is-mobile>.column.is-offset-9{margin-left:75%}.columns.is-mobile>.column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>.column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>.column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>.column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>.column.is-12{flex:none;width:100%}.columns.is-mobile>.column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){.column.is-narrow-mobile{flex:none;width:unset}.column.is-full-mobile{flex:none;width:100%}.column.is-three-quarters-mobile{flex:none;width:75%}.column.is-two-thirds-mobile{flex:none;width:66.6666%}.column.is-half-mobile{flex:none;width:50%}.column.is-one-third-mobile{flex:none;width:33.3333%}.column.is-one-quarter-mobile{flex:none;width:25%}.column.is-one-fifth-mobile{flex:none;width:20%}.column.is-two-fifths-mobile{flex:none;width:40%}.column.is-three-fifths-mobile{flex:none;width:60%}.column.is-four-fifths-mobile{flex:none;width:80%}.column.is-offset-three-quarters-mobile{margin-left:75%}.column.is-offset-two-thirds-mobile{margin-left:66.6666%}.column.is-offset-half-mobile{margin-left:50%}.column.is-offset-one-third-mobile{margin-left:33.3333%}.column.is-offset-one-quarter-mobile{margin-left:25%}.column.is-offset-one-fifth-mobile{margin-left:20%}.column.is-offset-two-fifths-mobile{margin-left:40%}.column.is-offset-three-fifths-mobile{margin-left:60%}.column.is-offset-four-fifths-mobile{margin-left:80%}.column.is-0-mobile{flex:none;width:0%}.column.is-offset-0-mobile{margin-left:0%}.column.is-1-mobile{flex:none;width:8.33333337%}.column.is-offset-1-mobile{margin-left:8.33333337%}.column.is-2-mobile{flex:none;width:16.66666674%}.column.is-offset-2-mobile{margin-left:16.66666674%}.column.is-3-mobile{flex:none;width:25%}.column.is-offset-3-mobile{margin-left:25%}.column.is-4-mobile{flex:none;width:33.33333337%}.column.is-offset-4-mobile{margin-left:33.33333337%}.column.is-5-mobile{flex:none;width:41.66666674%}.column.is-offset-5-mobile{margin-left:41.66666674%}.column.is-6-mobile{flex:none;width:50%}.column.is-offset-6-mobile{margin-left:50%}.column.is-7-mobile{flex:none;width:58.33333337%}.column.is-offset-7-mobile{margin-left:58.33333337%}.column.is-8-mobile{flex:none;width:66.66666674%}.column.is-offset-8-mobile{margin-left:66.66666674%}.column.is-9-mobile{flex:none;width:75%}.column.is-offset-9-mobile{margin-left:75%}.column.is-10-mobile{flex:none;width:83.33333337%}.column.is-offset-10-mobile{margin-left:83.33333337%}.column.is-11-mobile{flex:none;width:91.66666674%}.column.is-offset-11-mobile{margin-left:91.66666674%}.column.is-12-mobile{flex:none;width:100%}.column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{.column.is-narrow,.column.is-narrow-tablet{flex:none;width:unset}.column.is-full,.column.is-full-tablet{flex:none;width:100%}.column.is-three-quarters,.column.is-three-quarters-tablet{flex:none;width:75%}.column.is-two-thirds,.column.is-two-thirds-tablet{flex:none;width:66.6666%}.column.is-half,.column.is-half-tablet{flex:none;width:50%}.column.is-one-third,.column.is-one-third-tablet{flex:none;width:33.3333%}.column.is-one-quarter,.column.is-one-quarter-tablet{flex:none;width:25%}.column.is-one-fifth,.column.is-one-fifth-tablet{flex:none;width:20%}.column.is-two-fifths,.column.is-two-fifths-tablet{flex:none;width:40%}.column.is-three-fifths,.column.is-three-fifths-tablet{flex:none;width:60%}.column.is-four-fifths,.column.is-four-fifths-tablet{flex:none;width:80%}.column.is-offset-three-quarters,.column.is-offset-three-quarters-tablet{margin-left:75%}.column.is-offset-two-thirds,.column.is-offset-two-thirds-tablet{margin-left:66.6666%}.column.is-offset-half,.column.is-offset-half-tablet{margin-left:50%}.column.is-offset-one-third,.column.is-offset-one-third-tablet{margin-left:33.3333%}.column.is-offset-one-quarter,.column.is-offset-one-quarter-tablet{margin-left:25%}.column.is-offset-one-fifth,.column.is-offset-one-fifth-tablet{margin-left:20%}.column.is-offset-two-fifths,.column.is-offset-two-fifths-tablet{margin-left:40%}.column.is-offset-three-fifths,.column.is-offset-three-fifths-tablet{margin-left:60%}.column.is-offset-four-fifths,.column.is-offset-four-fifths-tablet{margin-left:80%}.column.is-0,.column.is-0-tablet{flex:none;width:0%}.column.is-offset-0,.column.is-offset-0-tablet{margin-left:0%}.column.is-1,.column.is-1-tablet{flex:none;width:8.33333337%}.column.is-offset-1,.column.is-offset-1-tablet{margin-left:8.33333337%}.column.is-2,.column.is-2-tablet{flex:none;width:16.66666674%}.column.is-offset-2,.column.is-offset-2-tablet{margin-left:16.66666674%}.column.is-3,.column.is-3-tablet{flex:none;width:25%}.column.is-offset-3,.column.is-offset-3-tablet{margin-left:25%}.column.is-4,.column.is-4-tablet{flex:none;width:33.33333337%}.column.is-offset-4,.column.is-offset-4-tablet{margin-left:33.33333337%}.column.is-5,.column.is-5-tablet{flex:none;width:41.66666674%}.column.is-offset-5,.column.is-offset-5-tablet{margin-left:41.66666674%}.column.is-6,.column.is-6-tablet{flex:none;width:50%}.column.is-offset-6,.column.is-offset-6-tablet{margin-left:50%}.column.is-7,.column.is-7-tablet{flex:none;width:58.33333337%}.column.is-offset-7,.column.is-offset-7-tablet{margin-left:58.33333337%}.column.is-8,.column.is-8-tablet{flex:none;width:66.66666674%}.column.is-offset-8,.column.is-offset-8-tablet{margin-left:66.66666674%}.column.is-9,.column.is-9-tablet{flex:none;width:75%}.column.is-offset-9,.column.is-offset-9-tablet{margin-left:75%}.column.is-10,.column.is-10-tablet{flex:none;width:83.33333337%}.column.is-offset-10,.column.is-offset-10-tablet{margin-left:83.33333337%}.column.is-11,.column.is-11-tablet{flex:none;width:91.66666674%}.column.is-offset-11,.column.is-offset-11-tablet{margin-left:91.66666674%}.column.is-12,.column.is-12-tablet{flex:none;width:100%}.column.is-offset-12,.column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){.column.is-narrow-touch{flex:none;width:unset}.column.is-full-touch{flex:none;width:100%}.column.is-three-quarters-touch{flex:none;width:75%}.column.is-two-thirds-touch{flex:none;width:66.6666%}.column.is-half-touch{flex:none;width:50%}.column.is-one-third-touch{flex:none;width:33.3333%}.column.is-one-quarter-touch{flex:none;width:25%}.column.is-one-fifth-touch{flex:none;width:20%}.column.is-two-fifths-touch{flex:none;width:40%}.column.is-three-fifths-touch{flex:none;width:60%}.column.is-four-fifths-touch{flex:none;width:80%}.column.is-offset-three-quarters-touch{margin-left:75%}.column.is-offset-two-thirds-touch{margin-left:66.6666%}.column.is-offset-half-touch{margin-left:50%}.column.is-offset-one-third-touch{margin-left:33.3333%}.column.is-offset-one-quarter-touch{margin-left:25%}.column.is-offset-one-fifth-touch{margin-left:20%}.column.is-offset-two-fifths-touch{margin-left:40%}.column.is-offset-three-fifths-touch{margin-left:60%}.column.is-offset-four-fifths-touch{margin-left:80%}.column.is-0-touch{flex:none;width:0%}.column.is-offset-0-touch{margin-left:0%}.column.is-1-touch{flex:none;width:8.33333337%}.column.is-offset-1-touch{margin-left:8.33333337%}.column.is-2-touch{flex:none;width:16.66666674%}.column.is-offset-2-touch{margin-left:16.66666674%}.column.is-3-touch{flex:none;width:25%}.column.is-offset-3-touch{margin-left:25%}.column.is-4-touch{flex:none;width:33.33333337%}.column.is-offset-4-touch{margin-left:33.33333337%}.column.is-5-touch{flex:none;width:41.66666674%}.column.is-offset-5-touch{margin-left:41.66666674%}.column.is-6-touch{flex:none;width:50%}.column.is-offset-6-touch{margin-left:50%}.column.is-7-touch{flex:none;width:58.33333337%}.column.is-offset-7-touch{margin-left:58.33333337%}.column.is-8-touch{flex:none;width:66.66666674%}.column.is-offset-8-touch{margin-left:66.66666674%}.column.is-9-touch{flex:none;width:75%}.column.is-offset-9-touch{margin-left:75%}.column.is-10-touch{flex:none;width:83.33333337%}.column.is-offset-10-touch{margin-left:83.33333337%}.column.is-11-touch{flex:none;width:91.66666674%}.column.is-offset-11-touch{margin-left:91.66666674%}.column.is-12-touch{flex:none;width:100%}.column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){.column.is-narrow-desktop{flex:none;width:unset}.column.is-full-desktop{flex:none;width:100%}.column.is-three-quarters-desktop{flex:none;width:75%}.column.is-two-thirds-desktop{flex:none;width:66.6666%}.column.is-half-desktop{flex:none;width:50%}.column.is-one-third-desktop{flex:none;width:33.3333%}.column.is-one-quarter-desktop{flex:none;width:25%}.column.is-one-fifth-desktop{flex:none;width:20%}.column.is-two-fifths-desktop{flex:none;width:40%}.column.is-three-fifths-desktop{flex:none;width:60%}.column.is-four-fifths-desktop{flex:none;width:80%}.column.is-offset-three-quarters-desktop{margin-left:75%}.column.is-offset-two-thirds-desktop{margin-left:66.6666%}.column.is-offset-half-desktop{margin-left:50%}.column.is-offset-one-third-desktop{margin-left:33.3333%}.column.is-offset-one-quarter-desktop{margin-left:25%}.column.is-offset-one-fifth-desktop{margin-left:20%}.column.is-offset-two-fifths-desktop{margin-left:40%}.column.is-offset-three-fifths-desktop{margin-left:60%}.column.is-offset-four-fifths-desktop{margin-left:80%}.column.is-0-desktop{flex:none;width:0%}.column.is-offset-0-desktop{margin-left:0%}.column.is-1-desktop{flex:none;width:8.33333337%}.column.is-offset-1-desktop{margin-left:8.33333337%}.column.is-2-desktop{flex:none;width:16.66666674%}.column.is-offset-2-desktop{margin-left:16.66666674%}.column.is-3-desktop{flex:none;width:25%}.column.is-offset-3-desktop{margin-left:25%}.column.is-4-desktop{flex:none;width:33.33333337%}.column.is-offset-4-desktop{margin-left:33.33333337%}.column.is-5-desktop{flex:none;width:41.66666674%}.column.is-offset-5-desktop{margin-left:41.66666674%}.column.is-6-desktop{flex:none;width:50%}.column.is-offset-6-desktop{margin-left:50%}.column.is-7-desktop{flex:none;width:58.33333337%}.column.is-offset-7-desktop{margin-left:58.33333337%}.column.is-8-desktop{flex:none;width:66.66666674%}.column.is-offset-8-desktop{margin-left:66.66666674%}.column.is-9-desktop{flex:none;width:75%}.column.is-offset-9-desktop{margin-left:75%}.column.is-10-desktop{flex:none;width:83.33333337%}.column.is-offset-10-desktop{margin-left:83.33333337%}.column.is-11-desktop{flex:none;width:91.66666674%}.column.is-offset-11-desktop{margin-left:91.66666674%}.column.is-12-desktop{flex:none;width:100%}.column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){.column.is-narrow-widescreen{flex:none;width:unset}.column.is-full-widescreen{flex:none;width:100%}.column.is-three-quarters-widescreen{flex:none;width:75%}.column.is-two-thirds-widescreen{flex:none;width:66.6666%}.column.is-half-widescreen{flex:none;width:50%}.column.is-one-third-widescreen{flex:none;width:33.3333%}.column.is-one-quarter-widescreen{flex:none;width:25%}.column.is-one-fifth-widescreen{flex:none;width:20%}.column.is-two-fifths-widescreen{flex:none;width:40%}.column.is-three-fifths-widescreen{flex:none;width:60%}.column.is-four-fifths-widescreen{flex:none;width:80%}.column.is-offset-three-quarters-widescreen{margin-left:75%}.column.is-offset-two-thirds-widescreen{margin-left:66.6666%}.column.is-offset-half-widescreen{margin-left:50%}.column.is-offset-one-third-widescreen{margin-left:33.3333%}.column.is-offset-one-quarter-widescreen{margin-left:25%}.column.is-offset-one-fifth-widescreen{margin-left:20%}.column.is-offset-two-fifths-widescreen{margin-left:40%}.column.is-offset-three-fifths-widescreen{margin-left:60%}.column.is-offset-four-fifths-widescreen{margin-left:80%}.column.is-0-widescreen{flex:none;width:0%}.column.is-offset-0-widescreen{margin-left:0%}.column.is-1-widescreen{flex:none;width:8.33333337%}.column.is-offset-1-widescreen{margin-left:8.33333337%}.column.is-2-widescreen{flex:none;width:16.66666674%}.column.is-offset-2-widescreen{margin-left:16.66666674%}.column.is-3-widescreen{flex:none;width:25%}.column.is-offset-3-widescreen{margin-left:25%}.column.is-4-widescreen{flex:none;width:33.33333337%}.column.is-offset-4-widescreen{margin-left:33.33333337%}.column.is-5-widescreen{flex:none;width:41.66666674%}.column.is-offset-5-widescreen{margin-left:41.66666674%}.column.is-6-widescreen{flex:none;width:50%}.column.is-offset-6-widescreen{margin-left:50%}.column.is-7-widescreen{flex:none;width:58.33333337%}.column.is-offset-7-widescreen{margin-left:58.33333337%}.column.is-8-widescreen{flex:none;width:66.66666674%}.column.is-offset-8-widescreen{margin-left:66.66666674%}.column.is-9-widescreen{flex:none;width:75%}.column.is-offset-9-widescreen{margin-left:75%}.column.is-10-widescreen{flex:none;width:83.33333337%}.column.is-offset-10-widescreen{margin-left:83.33333337%}.column.is-11-widescreen{flex:none;width:91.66666674%}.column.is-offset-11-widescreen{margin-left:91.66666674%}.column.is-12-widescreen{flex:none;width:100%}.column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){.column.is-narrow-fullhd{flex:none;width:unset}.column.is-full-fullhd{flex:none;width:100%}.column.is-three-quarters-fullhd{flex:none;width:75%}.column.is-two-thirds-fullhd{flex:none;width:66.6666%}.column.is-half-fullhd{flex:none;width:50%}.column.is-one-third-fullhd{flex:none;width:33.3333%}.column.is-one-quarter-fullhd{flex:none;width:25%}.column.is-one-fifth-fullhd{flex:none;width:20%}.column.is-two-fifths-fullhd{flex:none;width:40%}.column.is-three-fifths-fullhd{flex:none;width:60%}.column.is-four-fifths-fullhd{flex:none;width:80%}.column.is-offset-three-quarters-fullhd{margin-left:75%}.column.is-offset-two-thirds-fullhd{margin-left:66.6666%}.column.is-offset-half-fullhd{margin-left:50%}.column.is-offset-one-third-fullhd{margin-left:33.3333%}.column.is-offset-one-quarter-fullhd{margin-left:25%}.column.is-offset-one-fifth-fullhd{margin-left:20%}.column.is-offset-two-fifths-fullhd{margin-left:40%}.column.is-offset-three-fifths-fullhd{margin-left:60%}.column.is-offset-four-fifths-fullhd{margin-left:80%}.column.is-0-fullhd{flex:none;width:0%}.column.is-offset-0-fullhd{margin-left:0%}.column.is-1-fullhd{flex:none;width:8.33333337%}.column.is-offset-1-fullhd{margin-left:8.33333337%}.column.is-2-fullhd{flex:none;width:16.66666674%}.column.is-offset-2-fullhd{margin-left:16.66666674%}.column.is-3-fullhd{flex:none;width:25%}.column.is-offset-3-fullhd{margin-left:25%}.column.is-4-fullhd{flex:none;width:33.33333337%}.column.is-offset-4-fullhd{margin-left:33.33333337%}.column.is-5-fullhd{flex:none;width:41.66666674%}.column.is-offset-5-fullhd{margin-left:41.66666674%}.column.is-6-fullhd{flex:none;width:50%}.column.is-offset-6-fullhd{margin-left:50%}.column.is-7-fullhd{flex:none;width:58.33333337%}.column.is-offset-7-fullhd{margin-left:58.33333337%}.column.is-8-fullhd{flex:none;width:66.66666674%}.column.is-offset-8-fullhd{margin-left:66.66666674%}.column.is-9-fullhd{flex:none;width:75%}.column.is-offset-9-fullhd{margin-left:75%}.column.is-10-fullhd{flex:none;width:83.33333337%}.column.is-offset-10-fullhd{margin-left:83.33333337%}.column.is-11-fullhd{flex:none;width:91.66666674%}.column.is-offset-11-fullhd{margin-left:91.66666674%}.column.is-12-fullhd{flex:none;width:100%}.column.is-offset-12-fullhd{margin-left:100%}}.columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.columns:last-child{margin-bottom:-.75rem}.columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}.columns.is-centered{justify-content:center}.columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}.columns.is-gapless>.column{margin:0;padding:0 !important}.columns.is-gapless:not(:last-child){margin-bottom:1.5rem}.columns.is-gapless:last-child{margin-bottom:0}.columns.is-mobile{display:flex}.columns.is-multiline{flex-wrap:wrap}.columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{.columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){.columns.is-desktop{display:flex}}.columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}.columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}.columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){.columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-0-fullhd{--columnGap: 0rem}}.columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){.columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-1-fullhd{--columnGap: .25rem}}.columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){.columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-2-fullhd{--columnGap: .5rem}}.columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){.columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-3-fullhd{--columnGap: .75rem}}.columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){.columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-4-fullhd{--columnGap: 1rem}}.columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){.columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}.columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){.columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}.columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){.columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}.columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){.columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-8-fullhd{--columnGap: 2rem}}.tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}.tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.tile.is-ancestor:last-child{margin-bottom:-.75rem}.tile.is-ancestor:not(:last-child){margin-bottom:.75rem}.tile.is-child{margin:0 !important}.tile.is-parent{padding:.75rem}.tile.is-vertical{flex-direction:column}.tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{.tile:not(.is-child){display:flex}.tile.is-1{flex:none;width:8.33333337%}.tile.is-2{flex:none;width:16.66666674%}.tile.is-3{flex:none;width:25%}.tile.is-4{flex:none;width:33.33333337%}.tile.is-5{flex:none;width:41.66666674%}.tile.is-6{flex:none;width:50%}.tile.is-7{flex:none;width:58.33333337%}.tile.is-8{flex:none;width:66.66666674%}.tile.is-9{flex:none;width:75%}.tile.is-10{flex:none;width:83.33333337%}.tile.is-11{flex:none;width:91.66666674%}.tile.is-12{flex:none;width:100%}}.hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}.hero .navbar{background:none}.hero .tabs ul{border-bottom:none}.hero.is-white{background-color:#fff;color:#0a0a0a}.hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-white strong{color:inherit}.hero.is-white .title{color:#0a0a0a}.hero.is-white .subtitle{color:rgba(10,10,10,0.9)}.hero.is-white .subtitle a:not(.button),.hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){.hero.is-white .navbar-menu{background-color:#fff}}.hero.is-white .navbar-item,.hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}.hero.is-white a.navbar-item:hover,.hero.is-white a.navbar-item.is-active,.hero.is-white .navbar-link:hover,.hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}.hero.is-white .tabs a:hover{opacity:1}.hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}.hero.is-white .tabs.is-boxed a,.hero.is-white .tabs.is-toggle a{color:#0a0a0a}.hero.is-white .tabs.is-boxed a:hover,.hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-white .tabs.is-boxed li.is-active a,.hero.is-white .tabs.is-boxed li.is-active a:hover,.hero.is-white .tabs.is-toggle li.is-active a,.hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}.hero.is-black{background-color:#0a0a0a;color:#fff}.hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-black strong{color:inherit}.hero.is-black .title{color:#fff}.hero.is-black .subtitle{color:rgba(255,255,255,0.9)}.hero.is-black .subtitle a:not(.button),.hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-black .navbar-menu{background-color:#0a0a0a}}.hero.is-black .navbar-item,.hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-black a.navbar-item:hover,.hero.is-black a.navbar-item.is-active,.hero.is-black .navbar-link:hover,.hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}.hero.is-black .tabs a{color:#fff;opacity:0.9}.hero.is-black .tabs a:hover{opacity:1}.hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}.hero.is-black .tabs.is-boxed a,.hero.is-black .tabs.is-toggle a{color:#fff}.hero.is-black .tabs.is-boxed a:hover,.hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-black .tabs.is-boxed li.is-active a,.hero.is-black .tabs.is-boxed li.is-active a:hover,.hero.is-black .tabs.is-toggle li.is-active a,.hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}.hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){.hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}.hero.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-light strong{color:inherit}.hero.is-light .title{color:rgba(0,0,0,0.7)}.hero.is-light .subtitle{color:rgba(0,0,0,0.9)}.hero.is-light .subtitle a:not(.button),.hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-light .navbar-menu{background-color:#f5f5f5}}.hero.is-light .navbar-item,.hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-light a.navbar-item:hover,.hero.is-light a.navbar-item.is-active,.hero.is-light .navbar-link:hover,.hero.is-light .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-light .tabs a:hover{opacity:1}.hero.is-light .tabs li.is-active a{color:#f5f5f5 !important;opacity:1}.hero.is-light .tabs.is-boxed a,.hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-light .tabs.is-boxed a:hover,.hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-light .tabs.is-boxed li.is-active a,.hero.is-light .tabs.is-boxed li.is-active a:hover,.hero.is-light .tabs.is-toggle li.is-active a,.hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#f5f5f5}.hero.is-light.is-bold{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}}.hero.is-dark,.content kbd.hero{background-color:#363636;color:#fff}.hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-dark strong,.content kbd.hero strong{color:inherit}.hero.is-dark .title,.content kbd.hero .title{color:#fff}.hero.is-dark .subtitle,.content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}.hero.is-dark .subtitle a:not(.button),.content kbd.hero .subtitle a:not(.button),.hero.is-dark .subtitle strong,.content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-dark .navbar-menu,.content kbd.hero .navbar-menu{background-color:#363636}}.hero.is-dark .navbar-item,.content kbd.hero .navbar-item,.hero.is-dark .navbar-link,.content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-dark a.navbar-item:hover,.content kbd.hero a.navbar-item:hover,.hero.is-dark a.navbar-item.is-active,.content kbd.hero a.navbar-item.is-active,.hero.is-dark .navbar-link:hover,.content kbd.hero .navbar-link:hover,.hero.is-dark .navbar-link.is-active,.content kbd.hero .navbar-link.is-active{background-color:#292929;color:#fff}.hero.is-dark .tabs a,.content kbd.hero .tabs a{color:#fff;opacity:0.9}.hero.is-dark .tabs a:hover,.content kbd.hero .tabs a:hover{opacity:1}.hero.is-dark .tabs li.is-active a,.content kbd.hero .tabs li.is-active a{color:#363636 !important;opacity:1}.hero.is-dark .tabs.is-boxed a,.content kbd.hero .tabs.is-boxed a,.hero.is-dark .tabs.is-toggle a,.content kbd.hero .tabs.is-toggle a{color:#fff}.hero.is-dark .tabs.is-boxed a:hover,.content kbd.hero .tabs.is-boxed a:hover,.hero.is-dark .tabs.is-toggle a:hover,.content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-dark .tabs.is-boxed li.is-active a,.content kbd.hero .tabs.is-boxed li.is-active a,.hero.is-dark .tabs.is-boxed li.is-active a:hover,.hero.is-dark .tabs.is-toggle li.is-active a,.content kbd.hero .tabs.is-toggle li.is-active a,.hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#363636}.hero.is-dark.is-bold,.content kbd.hero.is-bold{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}@media screen and (max-width: 768px){.hero.is-dark.is-bold .navbar-menu,.content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}}.hero.is-primary,.docstring>section>a.hero.docs-sourcelink{background-color:#4eb5de;color:#fff}.hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-primary strong,.docstring>section>a.hero.docs-sourcelink strong{color:inherit}.hero.is-primary .title,.docstring>section>a.hero.docs-sourcelink .title{color:#fff}.hero.is-primary .subtitle,.docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}.hero.is-primary .subtitle a:not(.button),.docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),.hero.is-primary .subtitle strong,.docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-primary .navbar-menu,.docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#4eb5de}}.hero.is-primary .navbar-item,.docstring>section>a.hero.docs-sourcelink .navbar-item,.hero.is-primary .navbar-link,.docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-primary a.navbar-item:hover,.docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,.hero.is-primary a.navbar-item.is-active,.docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,.hero.is-primary .navbar-link:hover,.docstring>section>a.hero.docs-sourcelink .navbar-link:hover,.hero.is-primary .navbar-link.is-active,.docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#39acda;color:#fff}.hero.is-primary .tabs a,.docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}.hero.is-primary .tabs a:hover,.docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}.hero.is-primary .tabs li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#4eb5de !important;opacity:1}.hero.is-primary .tabs.is-boxed a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,.hero.is-primary .tabs.is-toggle a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}.hero.is-primary .tabs.is-boxed a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,.hero.is-primary .tabs.is-toggle a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-primary .tabs.is-boxed li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,.hero.is-primary .tabs.is-boxed li.is-active a:hover,.hero.is-primary .tabs.is-toggle li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,.hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#4eb5de}.hero.is-primary.is-bold,.docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}@media screen and (max-width: 768px){.hero.is-primary.is-bold .navbar-menu,.docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}}.hero.is-link{background-color:#2e63b8;color:#fff}.hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-link strong{color:inherit}.hero.is-link .title{color:#fff}.hero.is-link .subtitle{color:rgba(255,255,255,0.9)}.hero.is-link .subtitle a:not(.button),.hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-link .navbar-menu{background-color:#2e63b8}}.hero.is-link .navbar-item,.hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-link a.navbar-item:hover,.hero.is-link a.navbar-item.is-active,.hero.is-link .navbar-link:hover,.hero.is-link .navbar-link.is-active{background-color:#2958a4;color:#fff}.hero.is-link .tabs a{color:#fff;opacity:0.9}.hero.is-link .tabs a:hover{opacity:1}.hero.is-link .tabs li.is-active a{color:#2e63b8 !important;opacity:1}.hero.is-link .tabs.is-boxed a,.hero.is-link .tabs.is-toggle a{color:#fff}.hero.is-link .tabs.is-boxed a:hover,.hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-link .tabs.is-boxed li.is-active a,.hero.is-link .tabs.is-boxed li.is-active a:hover,.hero.is-link .tabs.is-toggle li.is-active a,.hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#2e63b8}.hero.is-link.is-bold{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}@media screen and (max-width: 768px){.hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}}.hero.is-info{background-color:#209cee;color:#fff}.hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-info strong{color:inherit}.hero.is-info .title{color:#fff}.hero.is-info .subtitle{color:rgba(255,255,255,0.9)}.hero.is-info .subtitle a:not(.button),.hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-info .navbar-menu{background-color:#209cee}}.hero.is-info .navbar-item,.hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-info a.navbar-item:hover,.hero.is-info a.navbar-item.is-active,.hero.is-info .navbar-link:hover,.hero.is-info .navbar-link.is-active{background-color:#1190e3;color:#fff}.hero.is-info .tabs a{color:#fff;opacity:0.9}.hero.is-info .tabs a:hover{opacity:1}.hero.is-info .tabs li.is-active a{color:#209cee !important;opacity:1}.hero.is-info .tabs.is-boxed a,.hero.is-info .tabs.is-toggle a{color:#fff}.hero.is-info .tabs.is-boxed a:hover,.hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-info .tabs.is-boxed li.is-active a,.hero.is-info .tabs.is-boxed li.is-active a:hover,.hero.is-info .tabs.is-toggle li.is-active a,.hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#209cee}.hero.is-info.is-bold{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}@media screen and (max-width: 768px){.hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}}.hero.is-success{background-color:#22c35b;color:#fff}.hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-success strong{color:inherit}.hero.is-success .title{color:#fff}.hero.is-success .subtitle{color:rgba(255,255,255,0.9)}.hero.is-success .subtitle a:not(.button),.hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-success .navbar-menu{background-color:#22c35b}}.hero.is-success .navbar-item,.hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-success a.navbar-item:hover,.hero.is-success a.navbar-item.is-active,.hero.is-success .navbar-link:hover,.hero.is-success .navbar-link.is-active{background-color:#1ead51;color:#fff}.hero.is-success .tabs a{color:#fff;opacity:0.9}.hero.is-success .tabs a:hover{opacity:1}.hero.is-success .tabs li.is-active a{color:#22c35b !important;opacity:1}.hero.is-success .tabs.is-boxed a,.hero.is-success .tabs.is-toggle a{color:#fff}.hero.is-success .tabs.is-boxed a:hover,.hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-success .tabs.is-boxed li.is-active a,.hero.is-success .tabs.is-boxed li.is-active a:hover,.hero.is-success .tabs.is-toggle li.is-active a,.hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#22c35b}.hero.is-success.is-bold{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}@media screen and (max-width: 768px){.hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}}.hero.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-warning strong{color:inherit}.hero.is-warning .title{color:rgba(0,0,0,0.7)}.hero.is-warning .subtitle{color:rgba(0,0,0,0.9)}.hero.is-warning .subtitle a:not(.button),.hero.is-warning .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-warning .navbar-menu{background-color:#ffdd57}}.hero.is-warning .navbar-item,.hero.is-warning .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-warning a.navbar-item:hover,.hero.is-warning a.navbar-item.is-active,.hero.is-warning .navbar-link:hover,.hero.is-warning .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.hero.is-warning .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-warning .tabs a:hover{opacity:1}.hero.is-warning .tabs li.is-active a{color:#ffdd57 !important;opacity:1}.hero.is-warning .tabs.is-boxed a,.hero.is-warning .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-warning .tabs.is-boxed a:hover,.hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-warning .tabs.is-boxed li.is-active a,.hero.is-warning .tabs.is-boxed li.is-active a:hover,.hero.is-warning .tabs.is-toggle li.is-active a,.hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ffdd57}.hero.is-warning.is-bold{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}@media screen and (max-width: 768px){.hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}}.hero.is-danger{background-color:#da0b00;color:#fff}.hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-danger strong{color:inherit}.hero.is-danger .title{color:#fff}.hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}.hero.is-danger .subtitle a:not(.button),.hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-danger .navbar-menu{background-color:#da0b00}}.hero.is-danger .navbar-item,.hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-danger a.navbar-item:hover,.hero.is-danger a.navbar-item.is-active,.hero.is-danger .navbar-link:hover,.hero.is-danger .navbar-link.is-active{background-color:#c10a00;color:#fff}.hero.is-danger .tabs a{color:#fff;opacity:0.9}.hero.is-danger .tabs a:hover{opacity:1}.hero.is-danger .tabs li.is-active a{color:#da0b00 !important;opacity:1}.hero.is-danger .tabs.is-boxed a,.hero.is-danger .tabs.is-toggle a{color:#fff}.hero.is-danger .tabs.is-boxed a:hover,.hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-danger .tabs.is-boxed li.is-active a,.hero.is-danger .tabs.is-boxed li.is-active a:hover,.hero.is-danger .tabs.is-toggle li.is-active a,.hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#da0b00}.hero.is-danger.is-bold{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}@media screen and (max-width: 768px){.hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}}.hero.is-small .hero-body,#documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{.hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{.hero.is-large .hero-body{padding:18rem 6rem}}.hero.is-halfheight .hero-body,.hero.is-fullheight .hero-body,.hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}.hero.is-halfheight .hero-body>.container,.hero.is-fullheight .hero-body>.container,.hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}.hero.is-halfheight{min-height:50vh}.hero.is-fullheight{min-height:100vh}.hero-video{overflow:hidden}.hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}.hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){.hero-video{display:none}}.hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){.hero-buttons .button{display:flex}.hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{.hero-buttons{display:flex;justify-content:center}.hero-buttons .button:not(:last-child){margin-right:1.5rem}}.hero-head,.hero-foot{flex-grow:0;flex-shrink:0}.hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{.hero-body{padding:3rem 3rem}}.section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){.section{padding:3rem 3rem}.section.is-medium{padding:9rem 4.5rem}.section.is-large{padding:18rem 6rem}}.footer{background-color:#fafafa;padding:3rem 1.5rem 6rem}h1 .docs-heading-anchor,h1 .docs-heading-anchor:hover,h1 .docs-heading-anchor:visited,h2 .docs-heading-anchor,h2 .docs-heading-anchor:hover,h2 .docs-heading-anchor:visited,h3 .docs-heading-anchor,h3 .docs-heading-anchor:hover,h3 .docs-heading-anchor:visited,h4 .docs-heading-anchor,h4 .docs-heading-anchor:hover,h4 .docs-heading-anchor:visited,h5 .docs-heading-anchor,h5 .docs-heading-anchor:hover,h5 .docs-heading-anchor:visited,h6 .docs-heading-anchor,h6 .docs-heading-anchor:hover,h6 .docs-heading-anchor:visited{color:#222}h1 .docs-heading-anchor-permalink,h2 .docs-heading-anchor-permalink,h3 .docs-heading-anchor-permalink,h4 .docs-heading-anchor-permalink,h5 .docs-heading-anchor-permalink,h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}h1 .docs-heading-anchor-permalink::before,h2 .docs-heading-anchor-permalink::before,h3 .docs-heading-anchor-permalink::before,h4 .docs-heading-anchor-permalink::before,h5 .docs-heading-anchor-permalink::before,h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}h1:hover .docs-heading-anchor-permalink,h2:hover .docs-heading-anchor-permalink,h3:hover .docs-heading-anchor-permalink,h4:hover .docs-heading-anchor-permalink,h5:hover .docs-heading-anchor-permalink,h6:hover .docs-heading-anchor-permalink{visibility:visible}.docs-dark-only{display:none !important}pre{position:relative;overflow:hidden}pre code,pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}pre code:first-of-type,pre code.hljs:first-of-type{padding-top:0.5rem !important}pre code:last-of-type,pre code.hljs:last-of-type{padding-bottom:0.5rem !important}pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#222;cursor:pointer;text-align:center}pre .copy-button:focus,pre .copy-button:hover{opacity:1;background:rgba(34,34,34,0.1);color:#2e63b8}pre .copy-button.success{color:#259a12;opacity:1}pre .copy-button.error{color:#cb3c33;opacity:1}pre:hover .copy-button{opacity:1}.admonition{background-color:#b5b5b5;border-style:solid;border-width:1px;border-color:#363636;border-radius:4px;font-size:1rem}.admonition strong{color:currentColor}.admonition.is-small,#documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}.admonition.is-medium{font-size:1.25rem}.admonition.is-large{font-size:1.5rem}.admonition.is-default{background-color:#b5b5b5;border-color:#363636}.admonition.is-default>.admonition-header{background-color:#363636;color:#fff}.admonition.is-default>.admonition-body{color:#fff}.admonition.is-info{background-color:#def0fc;border-color:#209cee}.admonition.is-info>.admonition-header{background-color:#209cee;color:#fff}.admonition.is-info>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-success{background-color:#bdf4d1;border-color:#22c35b}.admonition.is-success>.admonition-header{background-color:#22c35b;color:#fff}.admonition.is-success>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-warning{background-color:#fff3c5;border-color:#ffdd57}.admonition.is-warning>.admonition-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.admonition.is-warning>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-danger{background-color:#ffaba7;border-color:#da0b00}.admonition.is-danger>.admonition-header{background-color:#da0b00;color:#fff}.admonition.is-danger>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-compat{background-color:#bdeff5;border-color:#1db5c9}.admonition.is-compat>.admonition-header{background-color:#1db5c9;color:#fff}.admonition.is-compat>.admonition-body{color:rgba(0,0,0,0.7)}.admonition-header{color:#fff;background-color:#363636;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}details.admonition.is-details>.admonition-header{list-style:none}details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}.admonition-body{color:#222;padding:0.5rem .75rem}.admonition-body pre{background-color:#f5f5f5}.admonition-body code{background-color:rgba(0,0,0,0.05)}.docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #dbdbdb;box-shadow:2px 2px 3px rgba(10,10,10,0.1);max-width:100%}.docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#f5f5f5;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #dbdbdb;overflow:auto}.docstring>header code{background-color:transparent}.docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}.docstring>header .docstring-binding{margin-right:0.3em}.docstring>header .docstring-category{margin-left:0.3em}.docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #dbdbdb}.docstring>section:last-child{border-bottom:none}.docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}.docstring>section>a.docs-sourcelink:focus{opacity:1 !important}.docstring:hover>section>a.docs-sourcelink{opacity:0.2}.docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}.docstring>section:hover a.docs-sourcelink{opacity:1}.documenter-example-output{background-color:#fff}.outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#ffaba7;color:rgba(0,0,0,0.7);border-bottom:3px solid #da0b00;padding:10px 35px;text-align:center;font-size:15px}.outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}.outdated-warning-overlay a{color:#2e63b8}.outdated-warning-overlay a:hover{color:#363636}.content pre{border:1px solid #dbdbdb}.content code{font-weight:inherit}.content a code{color:#2e63b8}.content h1 code,.content h2 code,.content h3 code,.content h4 code,.content h5 code,.content h6 code{color:#222}.content table{display:block;width:initial;max-width:100%;overflow-x:auto}.content blockquote>ul:first-child,.content blockquote>ol:first-child,.content .admonition-body>ul:first-child,.content .admonition-body>ol:first-child{margin-top:0}pre,code{font-variant-ligatures:no-contextual}.breadcrumb a.is-disabled{cursor:default;pointer-events:none}.breadcrumb a.is-disabled,.breadcrumb a.is-disabled:hover{color:#222}.hljs{background:initial !important}.katex .katex-mathml{top:0;right:0}.katex-display,mjx-container,.MathJax_Display{margin:0.5em 0 !important}html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}li.no-marker{list-style:none}#documenter .docs-main>article{overflow-wrap:break-word}#documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){#documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){#documenter .docs-main{width:100%}#documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}#documenter .docs-main>header,#documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}#documenter .docs-main header.docs-navbar{background-color:#fff;border-bottom:1px solid #dbdbdb;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}#documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}#documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}#documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}#documenter .docs-main header.docs-navbar .docs-right .docs-icon,#documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}#documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}#documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}#documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #bbb;transition-duration:0.7s;-webkit-transition-duration:0.7s}#documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}#documenter .docs-main section.footnotes{border-top:1px solid #dbdbdb}#documenter .docs-main section.footnotes li .tag:first-child,#documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,#documenter .docs-main section.footnotes li .content kbd:first-child,.content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}#documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #dbdbdb;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){#documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}#documenter .docs-main .docs-footer .docs-footer-nextpage,#documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}#documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}#documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}#documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}#documenter .docs-sidebar{display:flex;flex-direction:column;color:#0a0a0a;background-color:#f5f5f5;border-right:1px solid #dbdbdb;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}#documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #bbb}@media screen and (min-width: 1056px){#documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){#documenter .docs-sidebar{left:0;top:0}}#documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}#documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}#documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}#documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}#documenter .docs-sidebar .docs-package-name a,#documenter .docs-sidebar .docs-package-name a:hover{color:#0a0a0a}#documenter .docs-sidebar .docs-version-selector{border-top:1px solid #dbdbdb;display:none;padding:0.5rem}#documenter .docs-sidebar .docs-version-selector.visible{display:flex}#documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #dbdbdb;padding-bottom:1.5rem}#documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}#documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}#documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}#documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}#documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}#documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}#documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}#documenter .docs-sidebar ul.docs-menu .tocitem,#documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#0a0a0a;background:#f5f5f5}#documenter .docs-sidebar ul.docs-menu a.tocitem:hover,#documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#0a0a0a;background-color:#ebebeb}#documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #dbdbdb;border-bottom:1px solid #dbdbdb;background-color:#fff}#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#fff;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#ebebeb;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}#documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}#documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}#documenter .docs-sidebar form.docs-search>input{width:14.4rem}#documenter .docs-sidebar #documenter-search-query{color:#707070;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){#documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#ccc}}@media screen and (max-width: 1055px){#documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#ccc}}kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(0,0,0,0.6);box-shadow:0 2px 0 1px rgba(0,0,0,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}.search-min-width-50{min-width:50%}.search-min-height-100{min-height:100%}.search-modal-card-body{max-height:calc(100vh - 15rem)}.search-result-link{border-radius:0.7em;transition:all 300ms}.search-result-link:hover,.search-result-link:focus{background-color:rgba(0,128,128,0.1)}.search-result-link .property-search-result-badge,.search-result-link .search-filter{transition:all 300ms}.property-search-result-badge,.search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}.search-result-link:hover .property-search-result-badge,.search-result-link:hover .search-filter,.search-result-link:focus .property-search-result-badge,.search-result-link:focus .search-filter{color:#f1f5f9;background-color:#333}.search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}.search-filter:hover,.search-filter:focus{color:#333}.search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}.search-filter-selected:hover,.search-filter-selected:focus{color:#f5f5f5}.search-result-highlight{background-color:#ffdd57;color:black}.search-divider{border-bottom:1px solid #dbdbdb}.search-result-title{width:85%;color:#333}.search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}#search-modal .modal-card-body::-webkit-scrollbar,#search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}#search-modal .modal-card-body::-webkit-scrollbar-thumb,#search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}#search-modal .modal-card-body::-webkit-scrollbar-track,#search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}.w-100{width:100%}.gap-2{gap:0.5rem}.gap-4{gap:1rem}.gap-8{gap:2rem}.ansi span.sgr1{font-weight:bolder}.ansi span.sgr2{font-weight:lighter}.ansi span.sgr3{font-style:italic}.ansi span.sgr4{text-decoration:underline}.ansi span.sgr7{color:#fff;background-color:#222}.ansi span.sgr8{color:transparent}.ansi span.sgr8 span{color:transparent}.ansi span.sgr9{text-decoration:line-through}.ansi span.sgr30{color:#242424}.ansi span.sgr31{color:#a7201f}.ansi span.sgr32{color:#066f00}.ansi span.sgr33{color:#856b00}.ansi span.sgr34{color:#2149b0}.ansi span.sgr35{color:#7d4498}.ansi span.sgr36{color:#007989}.ansi span.sgr37{color:gray}.ansi span.sgr40{background-color:#242424}.ansi span.sgr41{background-color:#a7201f}.ansi span.sgr42{background-color:#066f00}.ansi span.sgr43{background-color:#856b00}.ansi span.sgr44{background-color:#2149b0}.ansi span.sgr45{background-color:#7d4498}.ansi span.sgr46{background-color:#007989}.ansi span.sgr47{background-color:gray}.ansi span.sgr90{color:#616161}.ansi span.sgr91{color:#cb3c33}.ansi span.sgr92{color:#0e8300}.ansi span.sgr93{color:#a98800}.ansi span.sgr94{color:#3c5dcd}.ansi span.sgr95{color:#9256af}.ansi span.sgr96{color:#008fa3}.ansi span.sgr97{color:#f5f5f5}.ansi span.sgr100{background-color:#616161}.ansi span.sgr101{background-color:#cb3c33}.ansi span.sgr102{background-color:#0e8300}.ansi span.sgr103{background-color:#a98800}.ansi span.sgr104{background-color:#3c5dcd}.ansi span.sgr105{background-color:#9256af}.ansi span.sgr106{background-color:#008fa3}.ansi span.sgr107{background-color:#f5f5f5}code.language-julia-repl>span.hljs-meta{color:#066f00;font-weight:bolder}/*! + Theme: Default + Description: Original highlight.js style + Author: (c) Ivan Sagalaev + Maintainer: @highlightjs/core-team + Website: https://highlightjs.org/ + License: see project LICENSE + Touched: 2021 +*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{background:#F3F3F3;color:#444}.hljs-comment{color:#697070}.hljs-tag,.hljs-punctuation{color:#444a}.hljs-tag .hljs-name,.hljs-tag .hljs-attr{color:#444}.hljs-keyword,.hljs-attribute,.hljs-selector-tag,.hljs-meta .hljs-keyword,.hljs-doctag,.hljs-name{font-weight:bold}.hljs-type,.hljs-string,.hljs-number,.hljs-selector-id,.hljs-selector-class,.hljs-quote,.hljs-template-tag,.hljs-deletion{color:#880000}.hljs-title,.hljs-section{color:#880000;font-weight:bold}.hljs-regexp,.hljs-symbol,.hljs-variable,.hljs-template-variable,.hljs-link,.hljs-selector-attr,.hljs-operator,.hljs-selector-pseudo{color:#ab5656}.hljs-literal{color:#695}.hljs-built_in,.hljs-bullet,.hljs-code,.hljs-addition{color:#397300}.hljs-meta{color:#1f7199}.hljs-meta .hljs-string{color:#38a}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold}.gap-4{gap:1rem} diff --git a/v2.15.0/assets/themeswap.js b/v2.15.0/assets/themeswap.js new file mode 100644 index 000000000..9f5eebe6a --- /dev/null +++ b/v2.15.0/assets/themeswap.js @@ -0,0 +1,84 @@ +// Small function to quickly swap out themes. Gets put into the tag.. +function set_theme_from_local_storage() { + // Initialize the theme to null, which means default + var theme = null; + // If the browser supports the localstorage and is not disabled then try to get the + // documenter theme + if (window.localStorage != null) { + // Get the user-picked theme from localStorage. May be `null`, which means the default + // theme. + theme = window.localStorage.getItem("documenter-theme"); + } + // Check if the users preference is for dark color scheme + var darkPreference = + window.matchMedia("(prefers-color-scheme: dark)").matches === true; + // Initialize a few variables for the loop: + // + // - active: will contain the index of the theme that should be active. Note that there + // is no guarantee that localStorage contains sane values. If `active` stays `null` + // we either could not find the theme or it is the default (primary) theme anyway. + // Either way, we then need to stick to the primary theme. + // + // - disabled: style sheets that should be disabled (i.e. all the theme style sheets + // that are not the currently active theme) + var active = null; + var disabled = []; + var primaryLightTheme = null; + var primaryDarkTheme = null; + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // To distinguish the default (primary) theme, it needs to have the data-theme-primary + // attribute set. + if (ss.ownerNode.getAttribute("data-theme-primary") !== null) { + primaryLightTheme = themename; + } + // Check if the theme is primary dark theme so that we could store its name in darkTheme + if (ss.ownerNode.getAttribute("data-theme-primary-dark") !== null) { + primaryDarkTheme = themename; + } + // If we find a matching theme (and it's not the default), we'll set active to non-null + if (themename === theme) active = i; + // Store the style sheets of inactive themes so that we could disable them + if (themename !== theme) disabled.push(ss); + } + var activeTheme = null; + if (active !== null) { + // If we did find an active theme, we'll (1) add the theme--$(theme) class to + document.getElementsByTagName("html")[0].className = "theme--" + theme; + activeTheme = theme; + } else { + // If we did _not_ find an active theme, then we need to fall back to the primary theme + // which can either be dark or light, depending on the user's OS preference. + var activeTheme = darkPreference ? primaryDarkTheme : primaryLightTheme; + // In case it somehow happens that the relevant primary theme was not found in the + // preceding loop, we abort without doing anything. + if (activeTheme === null) { + console.error("Unable to determine primary theme."); + return; + } + // When switching to the primary light theme, then we must not have a class name + // for the tag. That's only for non-primary or the primary dark theme. + if (darkPreference) { + document.getElementsByTagName("html")[0].className = + "theme--" + activeTheme; + } else { + document.getElementsByTagName("html")[0].className = ""; + } + } + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // we'll disable all the stylesheets, except for the active one + ss.disabled = !(themename == activeTheme); + } +} +set_theme_from_local_storage(); diff --git a/v2.15.0/assets/warner.js b/v2.15.0/assets/warner.js new file mode 100644 index 000000000..3f6f5d008 --- /dev/null +++ b/v2.15.0/assets/warner.js @@ -0,0 +1,52 @@ +function maybeAddWarning() { + // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE + // in siteinfo.js. + // If either of these are undefined something went horribly wrong, so we abort. + if ( + window.DOCUMENTER_NEWEST === undefined || + window.DOCUMENTER_CURRENT_VERSION === undefined || + window.DOCUMENTER_STABLE === undefined + ) { + return; + } + + // Current version is not a version number, so we can't tell if it's the newest version. Abort. + if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) { + return; + } + + // Current version is newest version, so no need to add a warning. + if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) { + return; + } + + // Add a noindex meta tag (unless one exists) so that search engines don't index this version of the docs. + if (document.body.querySelector('meta[name="robots"]') === null) { + const meta = document.createElement("meta"); + meta.name = "robots"; + meta.content = "noindex"; + + document.getElementsByTagName("head")[0].appendChild(meta); + } + + const div = document.createElement("div"); + div.classList.add("outdated-warning-overlay"); + const closer = document.createElement("button"); + closer.classList.add("outdated-warning-closer", "delete"); + closer.addEventListener("click", function () { + document.body.removeChild(div); + }); + const href = window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE; + div.innerHTML = + 'This documentation is not for the latest stable release, but for either the development version or an older release.
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/v2.15.0/contributing/new-documentation/index.html b/v2.15.0/contributing/new-documentation/index.html new file mode 100644 index 000000000..26365f13d --- /dev/null +++ b/v2.15.0/contributing/new-documentation/index.html @@ -0,0 +1,2 @@ + +Contributing to the documentation · RxInfer.jl
GitHub

Contributing to the documentation

Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:

  1. Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.

  2. Identify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.

  3. Fork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.

  4. Make Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.

  5. Submit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.

  6. Review and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.

  7. Merging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!

By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.

Use LiveServer.jl

LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.

To use LiveServer.jl, simply follow these steps[1]

  • Make sure to import the required packages 
julia> using LiveServer, Documenter
  • After importing the required packages, you can start the live server with the following command:
julia> servedocs()
  • 1Make sure to install the LiveServer and Documenter in your current working environment.
diff --git a/v2.15.0/contributing/new-example/index.html b/v2.15.0/contributing/new-example/index.html new file mode 100644 index 000000000..a9c4c4068 --- /dev/null +++ b/v2.15.0/contributing/new-example/index.html @@ -0,0 +1,7 @@ + +Contributing to the examples · RxInfer.jl
GitHub

Contributing to the examples

We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.

In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/"subcategory" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.

After preparing the new example it is necessary to modify the examples/.meta.jl file.

  1. Make sure that the very first cell of the notebook contains ONLY # <title> in it and has the markdown cell type. This is important for generating links in our documentation.
  2. The path option must be set to a local path in a category sub-folder.
  3. The text in the description option will be used on the Examples page in the documentation.
  4. Set category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).
  5. Please do no use Overview as a name for the new example, the title Overview is reserved.
  6. Use the following template for equations, note that $$ and both \begin and \end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.
$$\begin{aligned}
+      <latex equations here>
+\end{aligned}$$
  1. When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.
  2. Notebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.
variable = 0
+for i in 1:10
+    global variable = variable + i
+end
  1. All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.
  2. All plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.
Note

Please avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.

Note

Use make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.

diff --git a/v2.15.0/contributing/new-package/index.html b/v2.15.0/contributing/new-package/index.html new file mode 100644 index 000000000..022a7cd6c --- /dev/null +++ b/v2.15.0/contributing/new-package/index.html @@ -0,0 +1,28 @@ + +Contributing to the dependencies · RxInfer.jl
GitHub

Contributing to the dependencies

Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.

The benefits of small packages for the ecosystem

In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:

  1. Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.

  2. Collaboration: Teams can work on different packages concurrently, speeding up development.

  3. Version Control: Precise versioning and fewer dependencies lead to leaner projects.

  4. Performance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.

  5. Flexibility: Developers can select and customize packages for their needs.

  6. Community: Smaller packages attract contributors, fostering collaboration and faster feedback.

In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.

Use PkgTemplates

PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:

julia> using PkgTemplates
+
+julia> USER = "your github user name" # Use `biaslab` if developing within the BIASlab organisation
+
+julia> template = Template(
+    user = USER, 
+    plugins = [
+        CompatHelper(), 
+        ProjectFile(), 
+        SrcDir(), 
+        Git(), 
+        License(), 
+        Readme(), 
+        Tests(), 
+        GitHubActions(), 
+        Codecov(), 
+        Documenter{GitHubActions}(), 
+        Formatter(style="blue"), 
+        BlueStyleBadge(), 
+        PkgEvalBadge()
+])
+
+julia> template("MyNewCoolPackage")

This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.

  • Adjust the minimum supported version of Julia

After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:

[compat]
+julia = "1.9.2"

Try to be conservative and set as low version of Julia as possible.

  • Adjust the authors of the package

The authors field is present in the Project.toml, e.g 

authors = ["John Wick <john.wick@continental.com>", ...]

  • Add requires dependencies and their [compat] bounds

To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:

julia --project=.

or 

julia
julia> ] activate .

Then, add dependencies like this:

julia> ] add SomeCoolDependency, SomeOtherCoolDependency

For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:

[compat]
+julia = "1.9"
+SomeCoolDependency = "0.19.2"
+SomeOtherCoolDependency = "1.3.12"

For more details on compat bounds, check the official Julia documentation.

Adjust README.md

The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.

Note

Some badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.

Write code and tests

The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.

Simplify Testing with ReTestItems

You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.

Write code and the documentation

Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):

julia --project=docs docs/make.jl

For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.

Hosting Documentation with GitHub Actions

The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.

Enable GitHub Pages in Repository Settings

The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:

  1. Navigate to the GitHub Pages settings of your repository.
  2. Choose the Deploy from a branch option.
  3. Select the gh-pages branch.
diff --git a/v2.15.0/contributing/new-release/index.html b/v2.15.0/contributing/new-release/index.html new file mode 100644 index 000000000..ef8feaaf2 --- /dev/null +++ b/v2.15.0/contributing/new-release/index.html @@ -0,0 +1,2 @@ + +Publishing a new release · RxInfer.jl
GitHub

Publishing a new release

Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.

Start the release process

In order to start the release process a person with the associated permissions should:

  • Open a commit page on GitHub
  • Write the @JuliaRegistrator register comment for the commit:

Release comment

The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.

diff --git a/v2.15.0/contributing/overview/index.html b/v2.15.0/contributing/overview/index.html new file mode 100644 index 000000000..8d9a2b9b1 --- /dev/null +++ b/v2.15.0/contributing/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Contributing

We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.

Reporting bugs

We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.

Nightly Julia status

The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.

PkgEval

Suggesting features

We welcome new feature proposals. However, before submitting a feature request, consider a few things:

  • Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.
  • If you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.

Contributing code

Installing RxInfer

We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:

] dev git@github.com:your_username/RxInfer.jl.git

The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.

Note

It is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.

Core dependencies

RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.

Committing code

We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.

Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well.

Note

Use make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.

Style conventions

We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:

  • Use 4 spaces for indentation
  • Type names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..
  • Function names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..
  • Variable names and function arguments use snake_case
  • The name of a method that modifies its argument(s) must end in !
Note

RxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.

Unit tests

We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.

All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.

The tests can be evaluated by running following command in the Julia REPL:

] test RxInfer

In addition tests can be evaluated by running following command in the RxInfer root directory:

make test
Note

Use make devtest to use local dev-ed versions of the core packages.

Makefile

RxInfer.jl uses Makefile for most common operations:

  • make help: Shows help snippet
  • make test: Run tests, supports extra arguments
    • make test test_args="distributions:normal_mean_variance" would run tests only from distributions/test_normal_mean_variance.jl
    • make test test_args="distributions:normal_mean_variance models:lgssm" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl
    • make test dev=true would run tests while using dev-ed versions of core packages
  • make devtest: Alias for the make test dev=true ...
  • make docs: Compile documentation
  • make devdocs: Same as make docs, but uses dev-ed versions of core packages
  • make examples: Run all examples and put them in the docs/ folder if successfull
  • make devexamples: Same as make examples, but uses dev-ed versions of core packages
  • make lint: Check codestyle
  • make format: Check and fix codestyle
Note

Core packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.

diff --git a/v2.15.0/examples/advanced_examples/Active Inference Mountain car/index.html b/v2.15.0/examples/advanced_examples/Active Inference Mountain car/index.html new file mode 100644 index 000000000..eedaea357 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Active Inference Mountain car/index.html @@ -0,0 +1,286 @@ + +Active Inference Mountain car · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Active Inference Mountain car

import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.

The environmental process of the mountain

Firstly, we specify the environmental process according to Ueltzhoeffer (2017) "Deep active inference". This process shows how the environment evolves after interacting with the agent.

Particularly, let's denote $z_t = (\phi_t, \,\,\dot{\phi_t})$ as the environmental state depending on the position $\phi_t$ and velocity $\dot{\phi_t}$ of the car; $a_t$ as the action of the environment on the car. Then the evolution of the state is described as follows

\[\begin{aligned} +\dot{\phi_t} &= \dot{\phi}_{t-1} + F_g(\phi_{t-1}) + F_f(\dot{\phi}_{t-1}) + F_a(a_t)\\ +\phi_t &= \phi_{t-1} + \dot{\phi_t} +\end{aligned}\]

where $F_g(\phi_{t-1})$ is the gravitational force of the hill landscape that depends on the car's position

\[F_g(\phi) = \begin{cases} + -0.05(2\phi + 1) , \, & \mathrm{if} \, \phi < 0 \\ + -0.05 \left[(1 + 5\phi^2)^{-\frac{1}{2}} + \phi^2 (1 + 5\phi^2)^{-\frac{3}{2}} + \frac{1}{16}\phi^4 \right], \, & \mathrm{otherwise} +\end{cases}\]

\[F_f(\dot{\phi})\]

is the friction on the car defined through the car's velocity $F_f(\dot{\phi}) = -0.1 \, \dot{\phi}\,$ and $F_a(a)$ is the engine force $F_a(a) = 0.04 \,\tanh(a).$ Since the car is on low battery, we use the $\tanh(\cdot)$ function to limit the engine force to the interval [-0.04, 0.04].

In the cell below, the create_physics function defines forces $F_g,\, F_f,\, F_a\,$; and the create_world function defines the environmental process of the mountain.

import HypergeometricFunctions: _₂F₁
+
+function create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)
+    # Engine force as function of action
+    Fa = (a::Real) -> engine_force_limit * tanh(a) 
+
+    # Friction force as function of velocity
+    Ff = (y_dot::Real) -> -friction_coefficient * y_dot 
+    
+    # Gravitational force (horizontal component) as function of position
+    Fg = (y::Real) -> begin
+        if y < 0
+            0.05*(-2*y - 1)
+        else
+            0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)
+        end
+    end
+    
+    # The height of the landscape as a function of the horizontal coordinate
+    height = (x::Float64) -> begin
+        if x < 0
+            h = x^2 + x
+        else
+            h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80
+        end
+        return 0.05*h
+    end
+
+    return (Fa, Ff, Fg,height)
+end;
+
+function create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)
+
+    y_t_min = initial_position
+    y_dot_t_min = initial_velocity
+    
+    y_t = y_t_min
+    y_dot_t = y_dot_t_min
+    
+    execute = (a_t::Float64) -> begin
+        # Compute next state
+        y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)
+        y_t = y_t_min + y_dot_t
+    
+        # Reset state for next step
+        y_t_min = y_t
+        y_dot_t_min = y_dot_t
+    end
+    
+    observe = () -> begin 
+        return [y_t, y_dot_t]
+    end
+        
+    return (execute, observe)
+end
create_world (generic function with 1 method)

Let's visualize the mountain landscape and the situation of the car. 

engine_force_limit   = 0.04
+friction_coefficient = 0.1
+
+Fa, Ff, Fg, height = create_physics(
+    engine_force_limit = engine_force_limit,
+    friction_coefficient = friction_coefficient
+);
+initial_position = -0.5
+initial_velocity = 0.0
+
+x_target = [0.5, 0.0] 
+
+valley_x = range(-2, 2, length=400)
+valley_y = [ height(xs) for xs in valley_x ]
+plot(valley_x, valley_y, title = "Mountain valley", label = "Landscape", color = "black")
+scatter!([ initial_position ], [ height(initial_position) ], label="initial car position")   
+scatter!([x_target[1]], [height(x_target[1])], label="camping site")

Naive approach

Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.

N_naive  = 100 # Total simulation time
+pi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only
+
+# Let there be a world
+(execute_naive, observe_naive) = create_world(; 
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+);
+
+y_naive = Vector{Vector{Float64}}(undef, N_naive)
+for t = 1:N_naive
+    execute_naive(pi_naive[t]) # Execute environmental process
+    y_naive[t] = observe_naive() # Observe external states
+end
+
+animation_naive = @animate for i in 1:N_naive
+    plot(valley_x, valley_y, title = "Naive policy", label = "Landscape", color = "black", size = (800, 400))
+    scatter!([y_naive[i][1]], [height(y_naive[i][1])], label="car")
+    scatter!([x_target[1]], [height(x_target[1])], label="goal")   
+end
+
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_naive, "../pics/ai-mountain-car-naive.gif", fps = 24, show_msg = false);

They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.

Active inference approach

Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.

We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows

\[\begin{aligned} +p_t(x,s,u) \propto p(s_{t-1}) \prod_{k=t}^{t+T} p(x_k \mid s_k) \, p(s_k \mid s_{k-1},u_k) \, p(u_k) \, p'(x_k) \nonumber +\end{aligned}\]

where the factors are defined as

\[p'(x_k) = \mathcal{N}(x_k \mid x_{goal},\,V_{goal}) , \quad (\mathrm{target})\]

\[p(s_k \mid s_{k-1},u_k) = \mathcal{N}(s_k \mid \tilde{g}(s_{k-1})+h(u_k),\,\gamma^{-1}) , \quad (\mathrm{state \,\, transition})\]

\[p(x_k \mid s_k) = \mathcal{N}(x_k \mid s_k,\,\theta), \quad (\mathrm{observation})\]

\[p(u_k) = \mathcal{N}(u_k \mid m_u,\,V_u), \quad (\mathrm{control})\]

\[p(s_{t-1}) = \mathcal{N}(s_{t-1} \mid m_{t-1},\,V_{t-1}), \quad (\mathrm{previous \,\, state})\]

where

  • \[x\]

    denotes observations of the agent after interacting with the environment;

  • \[s_t = (s_t,\dot{s_t})\]

    is the state of the car embodying its position and velocity;

  • \[u_t\]

    denotes the control state of the agent;

  • \[h(\cdot)\]

    is the $\tanh(\cdot)$ function modeling engine control;

  • \[\tilde{g}(\cdot)\]

    executes a linear approximation of equations (1) and (2):

\[\begin{aligned} +\dot{s_t} &= \dot{s}_{t-1} + F_g(s_{t-1}) + F_f(\dot{s}_{t-1})\\ +s_t &= s_{t-1} + \dot{s_t} +\end{aligned}\]

In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.

@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)
+    
+    # Transition function modeling transition due to gravity and friction
+    g = (s_t_min::AbstractVector) -> begin 
+        s_t = similar(s_t_min) # Next state
+        s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity
+        s_t[1] = s_t_min[1] + s_t[2] # Update position
+        return s_t
+    end
+    
+    # Function for modeling engine control
+    h = (u::AbstractVector) -> [0.0, Fa(u[1])] 
+    
+    # Inverse engine force, from change in state to corresponding engine force
+    h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] 
+    
+    # Internal model perameters
+    Gamma = 1e4*diageye(2) # Transition precision
+    Theta = 1e-4*diageye(2) # Observation variance
+    
+    m_s_t_min = datavar(Vector{Float64})
+    V_s_t_min = datavar(Matrix{Float64})
+
+    s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)
+    s_k_min = s_t_min
+    
+    m_u = datavar(Vector{Float64}, T)
+    V_u = datavar(Matrix{Float64}, T)
+    
+    m_x = datavar(Vector{Float64}, T)
+    V_x = datavar(Matrix{Float64}, T)
+    
+    u = randomvar(T)
+    s = randomvar(T)
+    x = randomvar(T)
+    
+    u_h_k = randomvar(T)
+    s_g_k = randomvar(T)
+    u_s_sum = randomvar(T)
+    
+    for k in 1:T
+        u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])
+        u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }
+        s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }
+        u_s_sum[k] ~ s_g_k[k] + u_h_k[k]
+        s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)
+        x[k] ~ MvNormal(mean = s[k], cov = Theta)
+        x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal
+        s_k_min = s[k]
+    end
+    
+    return (s, )
+end

After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.

  1. Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time $t$ and gets $T$ observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next $T$ time step.
  2. Infer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state $s_t$ and control $u_t$, i.e. $p(s_t\mid x_t)$ and $p(u_t\mid x_t)$.
  3. Slide: After updating its internal belief, the agent moves to the next time step and uses the inferred action $u_t$ in the previous time step to interact with the environment.

In the cell below, we create the agent through the create_agent function, which includes infer, act, slide and future functions:

  • The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next $T$ positions based on the current action. These two function implement the Act-Execute-Observe phase.
  • The infer function infers the policy (which is a set of actions for the next $T$ time steps) and the agent's state using the agent internal model. This function implements the Infer phase.
  • The slide function implements the Slide phase, which moves the agent internal model to the next time step.
# We are going to use some private functionality from ReactiveMP, 
+# in the future we should expose a proper API for this
+import RxInfer.ReactiveMP: getrecent, messageout
+
+function create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)
+    Epsilon = fill(huge, 1, 1)                # Control prior variance
+    m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors
+    V_u = Matrix{Float64}[ Epsilon for k=1:T ]
+
+    Sigma    = 1e-4*diageye(2) # Goal prior variance
+    m_x      = [zeros(2) for k=1:T]
+    V_x      = [huge*diageye(2) for k=1:T]
+    V_x[end] = Sigma # Set prior to reach goal at t=T
+
+    # Set initial brain state prior
+    m_s_t_min = [initial_position, initial_velocity] 
+    V_s_t_min = tiny * diageye(2)
+    
+    # Set current inference results
+    result = nothing
+
+    # The `infer` function is the heart of the agent
+    # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing
+    infer = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin
+        m_u[1] = [ upsilon_t ] # Register action with the generative model
+        V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action
+
+        m_x[1] = y_hat_t # Register observation with the generative model
+        V_x[1] = tiny*diageye(2) # Clamp goal prior to observation
+
+        data = Dict(:m_u       => m_u, 
+                    :V_u       => V_u, 
+                    :m_x       => m_x, 
+                    :V_x       => V_x,
+                    :m_s_t_min => m_s_t_min,
+                    :V_s_t_min => V_s_t_min)
+        
+        model  = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) 
+        result = inference(model = model, data = data)
+    end
+    
+    # The `act` function returns the inferred best possible action
+    act = () -> begin
+        if result !== nothing
+            return mode(result.posteriors[:u][2])[1]
+        else
+            return 0.0 # Without inference result we return some 'random' action
+        end
+    end
+    
+    # The `future` function returns the inferred future states
+    future = () -> begin 
+        if result !== nothing 
+            return getindex.(mode.(result.posteriors[:s]), 1)
+        else
+            return zeros(T)
+        end
+    end
+
+    # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step
+    # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`
+    slide = () -> begin
+        (s, ) = result.returnval
+        
+        slide_msg_idx = 3 # This index is model dependend
+        (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))
+
+        m_u = circshift(m_u, -1)
+        m_u[end] = [0.0]
+        V_u = circshift(V_u, -1)
+        V_u[end] = Epsilon
+
+        m_x = circshift(m_x, -1)
+        m_x[end] = x_target
+        V_x = circshift(V_x, -1)
+        V_x[end] = Sigma
+    end
+
+    return (infer, act, slide, future)    
+end
create_agent (generic function with 1 method)

Now it's time to see if we can help our friends arrive at the camping site by midnight?

(execute_ai, observe_ai) = create_world(
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+) # Let there be a world
+
+T_ai = 50
+
+(infer_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent
+    T  = T_ai, 
+    Fa = Fa,
+    Fg = Fg, 
+    Ff = Ff, 
+    engine_force_limit = engine_force_limit,
+    x_target = x_target,
+    initial_position = initial_position,
+    initial_velocity = initial_velocity
+) 
+
+N_ai = 100
+
+# Step through experimental protocol
+agent_a = Vector{Float64}(undef, N_ai) # Actions
+agent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future
+agent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations
+
+for t=1:N_ai
+    agent_a[t] = act_ai()            # Invoke an action from the agent
+    agent_f[t] = future_ai()         # Fetch the predicted future states
+    execute_ai(agent_a[t])           # The action influences hidden external states
+    agent_x[t] = observe_ai()        # Observe the current environmental outcome (update p)
+    infer_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)
+    slide_ai()                       # Prepare for next iteration
+end
+
+animation_ai = @animate for i in 1:N_ai
+    # pls - plot landscape
+    pls = plot(valley_x, valley_y, title = "Active inference results", label = "Landscape", color = "black")
+    pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label="car")
+    pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label="goal")   
+    pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = "Predicted future", alpha = map(i -> 0.5 / i, 1:T_ai))
+    
+    # pef - plot engine force
+    pef = plot(Fa.(agent_a[1:i]), title = "Engine force (agents actions)", xlim = (0, N_ai), ylim = (-0.05, 0.05))
+    
+    plot(pls, pef, size = (800, 400))
+end
+    
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_ai, "../pics/ai-mountain-car-ai.gif", fps = 24, show_msg = false);

Voila! The car now is able to reach the camping site with a smart strategy.

The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.

Now our friends can enjoy their trip at the camping site!.

Reference

We refer reader to the Thijs van de Laar (2019) "Simulating active inference processes by message passing" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) "Deep active inference".

diff --git a/v2.15.0/examples/advanced_examples/Advanced Tutorial/index.html b/v2.15.0/examples/advanced_examples/Advanced Tutorial/index.html new file mode 100644 index 000000000..37bbdf602 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Advanced Tutorial/index.html @@ -0,0 +1,416 @@ + +Advanced Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Advanced Tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.

This tutorial is also available in the documentation.

General model specification syntax

We use the @model macro from the RxInfer.jl package to create a probabilistic model $p(s, y)$ and we also specify extra constraints on the variational family of distributions $\mathcal{Q}$, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.

# the `@model` macro accepts a regular Julia function
+@model function test_model1(s_mean, s_precision)
+    
+    # We use the `randomvar` function to create 
+    # a random variable in our model
+    s = randomvar()
+    
+    # the `tilde` operator creates a functional dependency
+    # between variables in our model and can be read as 
+    # `sampled from` or `is modeled by`
+    s ~ Normal(mean = s_mean, precision = s_precision)
+    
+    # We use the `datavar` function to create 
+    # observed data variables in our models
+    # We also need to specify the type of our data 
+    # In this example it is `Float64`
+    y = datavar(Float64)
+    
+    y ~ Normal(mean = s, precision = 1.0)
+    
+    # It is possible to return something from the model specification (including variables and nodes)
+    return "Hello world"
+end

The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.

modelgenerator = test_model1(0.0, 1.0)
+
+model, returnval = create_model(modelgenerator)
(FactorGraphModel(), "Hello world")

The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.

RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as:

  • getnodes(): returns an array of factor nodes in a corresponding factor graph
  • getrandom(): returns an array of random variables in the model
  • getdata(): returns an array of data inputs in the model
  • getconstant(): returns an array of constant values in the model
getnodes(model)
FactorNodesCollection(nodes: 2)
getrandom(model) .|> name
1-element Vector{Symbol}:
+ :s
getdata(model) .|> name
1-element Vector{Symbol}:
+ :y
getconstant(model) .|> getconst
3-element Vector{Float64}:
+ 0.0
+ 1.0
+ 1.0

It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:

@model function test_model2(n)
+    
+    if n <= 1
+        error("`n` argument must be greater than one.")
+    end
+    
+    # `randomvar(n)` creates a dense sequence of 
+    # random variables
+    s = randomvar(n)
+    
+    # `datavar(Float64, n)` creates a dense sequence of 
+    # observed data variables of type `Float64`
+    y = datavar(Float64, n)
+    
+    s[1] ~ Normal(mean = 0.0, precision = 0.1)
+    y[1] ~ Normal(mean = s[1], precision = 1.0)
+    
+    for i in 2:n
+        s[i] ~ Normal(mean = s[i - 1], precision = 1.0)
+        y[i] ~ Normal(mean = s[i], precision = 1.0)
+    end
+    
+end
model, _ = create_model(test_model2(10));
# An amount of factor nodes in generated Factor Graph
+getnodes(model) |> length
20
# An amount of random variables
+getrandom(model) |> length
10
# An amount of data inputs
+getdata(model) |> length
10
# An amount of constant values
+getconstant(model) |> length
21

It is also possible to use complex expressions inside the functional dependency expressions

y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)

The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists

# s = randomvar() here is optional
+# `~` creates random variables automatically
+s ~ NormalMeanPrecision(0.0, 1.0)

An example model which will throw an error:

@model function error_model1()
+    s = 1.0
+    s ~ NormalMeanPrecision(0.0, 1.0)
+end

By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as

# Creates constant reference in a model with a prespecified value
+c = constvar(0.0)

An example:

@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)
+    
+    s = randomvar(n)
+    
+    y = datavar(Vector{Float64}, n)
+    
+    # Here we create constant references
+    # for constant matrices in our model 
+    # to make inference more memory efficient
+    cA = constvar(A)
+    cP = constvar(P)
+    cQ = constvar(Q)
+    
+    s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)
+    y[1] ~ MvNormal(mean = s[1], covariance = cQ)
+    
+    for i in 2:n
+        s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)
+        y[i] ~ MvNormal(mean = s[i], covariance = cQ)
+    end
+    
+end

The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:

@model function test_model()
+
+    # In this example `ynode` refers to the corresponding 
+    # `GaussianMeanVariance` node created in the factor graph
+    ynode, y ~ GaussianMeanVariance(0.0, 1.0)
+    
+    return ynode, y
+end

Probabilistic inference in RxInfer.jl

RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.

Observables

Observables are lazy push-based collections and they deliver their values over time.

# Timer that emits a new value every second and has an initial one second delay 
+observable = timer(300, 300)
TimerObservable(300, 300)

A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:

actor = (value) -> println(value)
+subscription1 = subscribe!(observable, actor)
TimerSubscription()
# We always need to unsubscribe from some observables
+unsubscribe!(subscription1)
# We can modify our observables
+modified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)
ProxyObservable(Int64, MapProxy(Int64))
subscription2 = subscribe!(modified, (value) -> println(value))
TimerSubscription()
unsubscribe!(subscription2)
@model function coin_toss_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+    
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    
+    # We assume that the outcome of each coin flip 
+    # is modeled by a Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+    
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during the inference step
+    return y, θ
+end

We can call the inference function to run inference in such model:

p = 0.75 # Bias of a coin
+
+dataset = float.(rand(Bernoulli(p), 500));
+
+result = inference(
+    model = coin_toss_model(length(dataset)),
+    data  = (y = dataset, )
+)
+
+println("Inferred bias: ", mean_var(result.posteriors[:θ]))
Inferred bias: (0.7387033398821218, 0.0003784719912335691)

We can see that the inferred bias is quite close to the actual value we used in the dataset generation.

The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions:

  • getmarginal(x): for a single random variable x
  • getmarginals(xs): for a dense sequence of random variables sx

Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.

_, (y, θ) = create_model(coin_toss_model(length(dataset)));
# As soon as we have a new value for the marginal posterior over the `θ` variable
+# we simply print the first two statistics of it
+θ_subscription = subscribe!(getmarginal(θ), (marginal) -> println("New update: mean(θ) = ", mean(marginal), ", std(θ) = ", std(marginal)));

To pass data to our model we use update! function

update!(y, dataset)
New update: mean(θ) = 0.7387033398821218, std(θ) = 0.01945435661320027
# It is necessary to always unsubscribe from running observables
+unsubscribe!(θ_subscription)
# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them
+# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing
+update!(y, dataset)

Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.

# the `keep` actor simply keeps all incoming updates in an internal storage, ordered
+θvalues = keep(Marginal)
KeepActor{Marginal}(Marginal[])
# `getmarginal` always emits last cached value as its first value
+subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=376.0, β=133.0))
subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
2-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=376.0, β=133.0))
+ Marginal(Beta{Float64}(α=376.0, β=133.0))
# the `buffer` actor keeps very last incoming update in an internal storage and can also store 
+# an array of updates for a sequence of random variables
+θbuffer = buffer(Marginal, 1)
BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=376.0, β=133.0))
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=376.0, β=133.0))

Reactive Online Inference

RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.

@model function online_coin_toss_model()
+    
+    # We create datavars for the prior 
+    # over `θ` variable
+    θ_a = datavar(Float64)
+    θ_b = datavar(Float64)
+    
+    θ ~ Beta(θ_a, θ_b)
+    
+    y = datavar(Float64)
+    y ~ Bernoulli(θ)
+
+end
autoupdates = @autoupdates begin 
+    θ_a, θ_b = params(q(θ))
+end
(θ_a,θ_b = params(q(θ)),)
rxresult = rxinference(
+    model = online_coin_toss_model(),
+    data  = (y = dataset, ),
+    autoupdates = autoupdates,
+    historyvars = (θ = KeepLast(), ),
+    keephistory = length(dataset),
+    initmarginals = (
+        θ = vague(Beta),
+    ),
+    autostart = true
+);
animation = @animate for i in 1:length(dataset)
+    plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = "Online coin bias inference", label = "Inferred bias", legend = :bottomright)
+    hline!([ p ], label = "Real bias", size = (600, 200))
+end
+
+gif(animation, "../pics/online-coin-bias-inference.gif", fps = 24, show_msg = false);

In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.

That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.

Variational inference

On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions $q \in \mathcal{Q}$. Often this involves assuming some factorization over $q$. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.

@model function test_model6_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+
+end

In this example we specified an extra constraints for $q_a$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

There are several options to specify the mean-field factorisation constraint. 

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name

It is also possible to use local structured factorisation:

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification

RxInfer.jl constraints macro

RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:

constraints6 = @constraints begin
+     q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

Note: where blocks have higher priority over constraints specification

@model function test_model6(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end

Inference

To run inference in this model we again need to create a synthetic dataset:

dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);

inference function

In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:

Use ?inference to quickly check the documentation for the inference function.

result = inference(
+    model         = test_model6(length(dataset)),
+    data          = (y = dataset, ),
+    constraints   = constraints6, 
+    initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),
+    returnvars    = (μ = KeepLast(), τ = KeepLast()),
+    iterations    = 10,
+    free_energy   = true,
+    showprogress  = true
+)
Inference results:
+  Posteriors       | available for (μ, τ)
+  Free Energy:     | Real[14763.3, 3275.76, 651.834, 609.391, 609.391, 609.
+391, 609.391, 609.391, 609.391, 609.391]
println("μ: mean = ", mean(result.posteriors[:μ]), ", std = ", std(result.posteriors[:μ]))
μ: mean = -3.000724646986326, std = 0.013966417335757148
println("τ: mean = ", mean(result.posteriors[:τ]), ", std = ", std(result.posteriors[:τ]))
τ: mean = 5.126596331700441, std = 0.22903943279021433

Manual inference

For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);

For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:

setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values)
10-element Vector{Marginal}:
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.006731961208428e-9, w=
+0.010000001002000566))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.534269275882096, w=9.
+185855437107634))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9886.339565217606, w=329
+4.6542755992728))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15375.00197071403, w=512
+3.763022641175))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.525455265057, w=51
+26.603492503708))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533966426894, w=51
+26.606328866963))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974921042, w=51
+26.606331697606))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974929553, w=51
+26.606331700403))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974929553, w=51
+26.606331700403))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974929553, w=51
+26.606331700403))
getvalues(τ_values)
10-element Vector{Marginal}:
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=5.000000000046004e14))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=54599.81398289297))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=152.064975181232))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.77988864532342))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72571215810044))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565808994209))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803598197))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803592796))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803592796))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803592796))
println("μ: mean = ", mean(last(μ_values)), ", std = ", std(last(μ_values)))
μ: mean = -3.000724646986326, std = 0.013966417335757148
println("τ: mean = ", mean(last(τ_values)), ", std = ", std(last(τ_values)))
τ: mean = 5.126596331700441, std = 0.22903943279021433

Form constraints

In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.

<img style="display: block; margin-left: auto; margin-right: auto; width: 50%;" src="./pics/posterior.png" />

@model function test_model7_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+    
+    return μ, τ, y
+end

As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:

constraints7 = @constraints begin 
+    q(μ) :: PointMass
+    
+    q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+    q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

In this example we specified an extra constraints for $q_i$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

@model function test_model7(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar()
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end
model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);
setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, PointMass(1.0))
+
+μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values) |> last
Marginal(PointMass{Float64}(-3.000724652827777))
getvalues(τ_values) |> last
Marginal(GammaShapeRate{Float64}(a=501.0, b=97.62812762929559))

By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.

μ = randomvar() where { 
+    prod_constraint = ProdGeneric(),
+    form_constraint = SampleListFormConstraint() 
+}

Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:

μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }

Note: @constraints macro specifies required prod_constraint automatically.

Free Energy

During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);
bfe_observable = score(model, Float64, BetheFreeEnergy())
ProxyObservable(Float64, ErrorIfProxy())
bfe_subscription = subscribe!(bfe_observable, (fe) -> println("Current BFE value: ", fe));
# Reset the model with vague marginals
+setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
+
+for i in 1:10
+    update!(y, dataset)
+end
Current BFE value: 621.8890579210147
+Current BFE value: 609.3910191436262
+Current BFE value: 609.3910188947075
+Current BFE value: 609.3910188947066
+Current BFE value: 609.3910188947084
+Current BFE value: 609.391018894707
+Current BFE value: 609.3910188947075
+Current BFE value: 609.3910188947066
+Current BFE value: 609.3910188947066
+Current BFE value: 609.3910188947066
# It always necessary to unsubscribe and release computer resources
+unsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])

Meta data specification

During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:

# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of 
+# the autoregressive process and its order. In addition it specifies that the message computation rules should
+# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations
+# by cost of possible numerical instabilities during an inference procedure
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }
+...
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }

Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:

# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` 
+# method with `21` sigma points for approximation of non-lineariety between hierarchy layers
+xt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }

The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.

RxInfer.jl @meta macro

Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:

@meta begin 
+     AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())
+end
Meta specification:
+  AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())
+Options:
+  warn = true

Creating custom nodes and message computation rules

Custom nodes

To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:

# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification
+@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]
+
+# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error
+struct NormalMeanVariance end 
+
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# It is also possible to use function objects as a node functional form
+function dot end
+
+# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them 
+# out = dot(x, a)
+@node typeof(dot) Deterministic [ out, x, a ]

Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.

After that it is possible to use the newly created node during model specification:

@model function test_model()
+    ...
+    y ~ dot(x, a)
+    ...
+end

Custom messages computation rules

RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:

\[\begin{aligned} +\mu_z = \mu_x + \mu_y\\ +V_z = V_x + V_y +\end{aligned}\]

To specify this in RxInfer.jl we use the @node and @rule macros:

@node typeof(+) Deterministic  [ z, x, y ]
+
+@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin
+    x_mean, x_var = mean_var(m_x)
+    y_mean, y_var = mean_var(m_y)
+    return NormalMeanVariance(x_mean + y_mean, x_var + y_var)
+end

In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:

\[\begin{aligned} +q(z) = \int q(z, x, y) \mathrm{d}x\mathrm{d}y +\end{aligned}\]

If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:

\[\begin{aligned} +\mu(z) = \int f(x, y, z)\mu(x)\mu(y)\mathrm{d}x\mathrm{d}y +\end{aligned}\]

\[\begin{aligned} +\nu(z) = \exp{ \int \log f(x, y, z)q(x)q(y)\mathrm{d}x\mathrm{d}y } +\end{aligned}\]

The @rule macro supports both cases with special prefixes during rule specification:

  • m_ prefix corresponds to the incoming message on a specific edge
  • q_ prefix corresponds to the posterior marginal of a specific edge

Example of a Sum-Product rule with m_ messages used:

@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin 
+    m_out_mean, m_out_cov = mean_cov(m_out)
+    return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))
+end

Example of a Variational rule with Mean-Field assumption with q_ posteriors used:

@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin 
+    return NormalMeanPrecision(mean(q_out), mean(q_τ))
+end

RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:

@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin
+    m, V = mean_cov(q_out_μ)
+    θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))
+    α = convert(typeof(θ), 1.5)
+    return Gamma(α, θ)
+end

NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:

# Inference backend expects arguments in `@rule` macro to be in the same order
+@node NormalMeanPrecision Stochastic [ out, μ, τ ]

Any rule always has access to the meta information with hidden the meta::Any variable:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin 
+    ...
+    println(meta)
+    ...
+end

It is also possible to dispatch on a specific type of a meta object:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin 
+    ...
+end

or

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin 
+    ...
+end

Customizing messages computational pipeline

In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.

<img style="display: block; margin-left: auto; margin-right: auto; width: 30%;" src="./pics/pipeline.png" width="20%" />

# Logs all outbound messages
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }
+# Initialise messages to be vague
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }
+# In principle, it is possible to approximate outbound messages with Laplace Approximation
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }

Let us return to the coin toss model, but this time we want to print flowing messages:

@model function coin_toss_model_log(n)
+
+    y = datavar(Float64, n)
+
+    θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage("θ") }
+
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)  where { pipeline = LoggerPipelineStage("y[$i]") }
+    end
+    
+    return y, θ
+end
_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));
θ_subscription = subscribe!(getmarginal(θ), (value) -> println("New posterior marginal for θ: ", value));
[θ][Beta][out]: VariationalMessage()
coinflips = float.(rand(Bernoulli(0.5), 5));
update!(y, coinflips)
[y[1]][Bernoulli][p]: VariationalMessage()
+[y[2]][Bernoulli][p]: VariationalMessage()
+[y[3]][Bernoulli][p]: VariationalMessage()
+[y[4]][Bernoulli][p]: VariationalMessage()
+[y[5]][Bernoulli][p]: VariationalMessage()
+New posterior marginal for θ: Marginal(Beta{Float64}(α=4.0, β=10.0))
unsubscribe!(θ_subscription)
# Inference is lazy and does not send messages if no one is listening for them
+update!(y, coinflips)
diff --git a/v2.15.0/examples/advanced_examples/Assessing People Skills/index.html b/v2.15.0/examples/advanced_examples/Assessing People Skills/index.html new file mode 100644 index 000000000..2137ae274 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Assessing People Skills/index.html @@ -0,0 +1,49 @@ + +Assessing People’s Skills · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Assessing People’s Skills

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of "Model-Based Machine Learning" by Winn et al.

Problem Statement

We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?

We model the result for question $i$ as a continuous variable $r_i\in[0,1]$, and skill/attitude as a binary variable $s_i \in \{0, 1\}$, where $s_1$ represents whether the student has partied, and $s_2$ and $s_3$ represent whether the student has studied the chapters for the corresponding questions.

We assume the following logic:

  • If the student is alert (has not partied), then they will score on the first question;
  • If the student is alert or has studied chapter two, then they will score on question two;
  • If the student can answer question two and has studied chapter three, then they will score on question three.

Generative Model Definition

To model the probability for correct answers, we assume a latent state variable $t_i \in \{0,1\}$. The dependencies between the variables can then be modeled by the following Bayesian network:

(s_1)   (s_2)   (s_3)
+  |       |       |
+  v       v       v
+(t_1)-->(t_2)-->(t_3)
+  |       |       |
+  v       v       v
+(r_1)   (r_2)   (r_3)

As prior beliefs, we assume that a student is equally likely to study/party or not: $s_i \sim Ber(0.5)\,,$ for all $i$. Next, we model the domain logic as $\begin{aligned} t_1 &= ¬s_1\\ + t_2 &= t_1 ∨ s_2\\ + t_3 &= t_2 ∧ s_3\,. \end{aligned}$ For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as $t_i \sim Ber(s_i)\,,$ for all $i$.

Custom Nodes and Rules

The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.

In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.

using RxInfer, Random
+
+# Create Score node
+struct Score end
+
+@node Score Stochastic [out, in]

We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.

# Adding update rule for the Score node
+@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin     
+    return Bernoulli(mean(q_out))
+end

Generative Model Specification

We can now build the full generative model.

# GraphPPL.jl exports the `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function skill_model()
+    s = randomvar(3)
+    t = randomvar(3)
+    r = datavar(Float64, 3)
+
+    # Priors
+    for i=1:3
+        s[i] ~ Bernoulli(0.5)
+    end
+
+    # Domain logic
+    t[1] ~ ¬s[1]
+    t[2] ~ t[1] || s[2]
+    t[3] ~ t[2] && s[3]
+    
+    # Results
+    for i=1:3
+        r[i] ~ Score(t[i])
+    end
+end

Inference Specification

Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.

test_results = [0.1, 0.1, 0.1]
+inference_result = inference(
+    model = skill_model(),
+    data  = (r = test_results, )
+)
Inference results:
+  Posteriors       | available for (s, t)

Results

# Inspect the results
+map(params, inference_result.posteriors[:s])
3-element Vector{Tuple{Float64}}:
+ (0.9872448979591837,)
+ (0.06377551020408162,)
+ (0.4719387755102041,)

These results suggest that this particular student was very likely out on the town last night.

diff --git a/v2.15.0/examples/advanced_examples/Chance Constraints/index.html b/v2.15.0/examples/advanced_examples/Chance Constraints/index.html new file mode 100644 index 000000000..3bc30d719 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Chance Constraints/index.html @@ -0,0 +1,166 @@ + +Chance-Constrained Active Inference · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Chance-Constrained Active Inference

This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, "Chance-constrained active inference") and discussion with John Boik.

We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. 

using Pkg; Pkg.activate(".."); Pkg.instantiate();
using Plots, Distributions, StatsFuns, RxInfer

Chance-Constraint Node Definition

A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not "overflow" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.

In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.

struct ChanceConstraint end  
+
+# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol
+@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]
# Function to compute normalizing constant and central moments of a truncated Gaussian distribution
+function truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)
+    V = clamp(V, tiny, huge)
+    StdG = Distributions.Normal(m, sqrt(V))
+    TrG = Distributions.Truncated(StdG, a, b)
+    
+    Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a)  # safe mass for standard Gaussian
+    
+    if Z < tiny
+        # Invalid region; return undefined mean and variance of truncated distribution
+        Z    = 0.0
+        m_tr = 0.0
+        V_tr = 0.0
+    else
+        m_tr = Distributions.mean(TrG)
+        V_tr = Distributions.var(TrG)
+    end
+    
+    return (Z, m_tr, V_tr)
+end;
@rule ChanceConstraint(:out, Marginalisation) (
+    m_out::UnivariateNormalDistributionsFamily, # Require inbound message
+    q_lo::PointMass, 
+    q_hi::PointMass, 
+    q_epsilon::PointMass, 
+    q_atol::PointMass) = begin 
+
+    # Extract parameters
+    lo = mean(q_lo)
+    hi = mean(q_hi)
+    epsilon = mean(q_epsilon)
+    atol = mean(q_atol)
+    
+    (m_bw, V_bw) = mean_var(m_out)
+    (xi_bw, W_bw) = (m_bw, 1. /V_bw)  # check division by  zero
+    (m_tilde, V_tilde) = (m_bw, V_bw)
+    
+    # Compute statistics (and normalizing constant) of q in safe region G
+    # Phi_G is called the "safe mass" 
+    (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)
+
+    xi_fw = xi_bw
+    W_fw  = W_bw
+    if epsilon <= 1.0 - Phi_G # If constraint is active
+        # Initialize statistics of uncorrected belief
+        m_tilde = m_bw
+        V_tilde = V_bw
+        for i = 1:100 # Iterate at most this many times
+            (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G
+            (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G
+
+            # Compute moments of non-G region as a mixture of left and right truncations
+            Phi_nG = Phi_lG + Phi_rG
+            m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG
+            V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2
+
+            # Compute moments of corrected belief as a mixture of G and non-G regions
+            m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG
+            V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2
+            # Re-compute statistics (and normalizing constant) of corrected belief
+            (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)
+            if (1.0 - Phi_G) < (1.0 + atol)*epsilon
+                break # Break the loop if the belief is sufficiently corrected
+            end
+        end
+        
+        # Convert moments of corrected belief to canonical form
+        W_tilde = inv(V_tilde)
+        xi_tilde = W_tilde * m_tilde
+
+        # Compute canonical parameters of forward message
+        xi_fw = xi_tilde - xi_bw
+        W_fw  = W_tilde - W_bw
+    end
+
+    return NormalWeightedMeanPrecision(xi_fw, W_fw)
+end

Definition of the Environment

We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.

wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile
+
+function initializeWorld()
+    x_0 = 0.0 # Initial elevation
+    
+    x_t_last = x_0
+    function execute(t::Int64, a_t::Float64)
+        x_t = x_t_last + a_t + wind(t) # Update elevation
+    
+        x_t_last = x_t # Reset state
+                
+        return x_t
+    end
+
+    x_t = x_0 # Predefine outcome variable
+    observe() = x_t # State is fully observed
+
+    return (execute, observe)
+end;

Generative Model for Regulator

We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.

@model function regulator_model(; T, lo, hi, epsilon, atol)
+    # Fully observed state
+    x_t = datavar(Float64)
+
+    # Control prior statistics
+    m_u = datavar(Float64, T)
+    v_u = datavar(Float64, T)    
+        
+    # Random variables
+    u = randomvar(T) # Control
+    x = randomvar(T) # Elevation
+    
+    # Loop over horizon
+    x_k_last = x_t
+    for k = 1:T
+        u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior
+        x[k] ~ x_k_last + u[k] # Transition model
+        x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state
+            pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency
+        x_k_last = x[k]
+    end
+    
+    return (u, x)
+end

Reactive Agent Definition

function initializeAgent()
+    # Set control prior statistics
+    m_u = zeros(T)
+    v_u = lambda^(-1)*ones(T)
+    
+    function infer(x_t::Float64)
+        model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)
+        data_t = (m_u = m_u, v_u = v_u, x_t = x_t)
+        
+        result = inference(
+            model = model_t, 
+            data = data_t,
+            iterations = n_its)
+
+        # Extract policy from inference results
+        pol = mode.(result.posteriors[:u][end])
+
+        return pol
+    end
+
+    pol = zeros(T) # Predefine policy variable
+    act() = pol[1]
+
+    return (infer, act)
+end;

Action-Perception Cycle

Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. 

# Simulation parameters
+N = 160 # Total simulation time
+T = 1 # Lookahead time horizon
+lambda = 1.0 # Control prior precision
+lo = 1.0 # Chance region lower bound
+hi = Inf # Chance region upper bound
+epsilon = 0.01 # Allowed chance violation
+atol = 0.01 # Convergence tolerance for chance constraints
+n_its = 10;  # Number of inference iterations
(execute, observe) = initializeWorld() # Let there be a world
+(infer, act) = initializeAgent() # Let there be an agent
+
+a = Vector{Float64}(undef, N) # Actions
+x = Vector{Float64}(undef, N) # States
+for t = 1:N
+    a[t] = act()
+           execute(t, a[t])
+    x[t] = observe()
+           infer(x[t])
+end

Results

Results show that the agent does not allow the wind to push it all the way to the ground.

p1 = plot(1:N, wind.(1:N), color="blue", label="Wind", ylabel="Velocity", lw=2)
+plot!(p1, 1:N, a, color="red", label="Control", lw=2)
+p2 = plot(1:N, x, color="black", lw=2, label="Agent", ylabel="Elevation")
+plot(p1, p2, layout=(2,1))

diff --git a/v2.15.0/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html b/v2.15.0/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html new file mode 100644 index 000000000..3ef1ea8f5 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html @@ -0,0 +1,143 @@ + +Conjugate-Computational Variational Message Passing (CVI) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Conjugate-Computational Variational Message Passing (CVI)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions

In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.

This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.

An example: nonlinear dynamical system

A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position $z_t$ at time $t$. Instead they have access to the observed squared distance $y_t$ between the object and some reference point $s$. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:

# data generating process
+nr_observations = 50
+reference_point = 53
+hidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)
+measurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);
# plot hidden location and reference frame
+p1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label="hidden location")
+hline!([reference_point], linewidth=3, label="reference point")
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot measurements
+p2 = scatter(1:nr_observations, measurements, linewidth=3, label="measurements")
+xlabel!("time [sec]"), ylabel!("squared distance [cm2]")
+
+plot(p1, p2, size=(1200, 500))

The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model

\[\begin{aligned} + p(\tau) & = \Gamma(\tau \mid \alpha_{\tau}, \beta_{\tau}),\\ + p(\gamma) & = \Gamma(\gamma \mid \alpha_{\gamma}, \beta_{\gamma}),\\ + p(z_t \mid z_{t - 1}, \tau) & = \mathcal{N}(z_t \mid z_{t - 1} + 1, \tau^{-1}),\\ + p(y_t \mid z_t, \gamma) & = \mathcal{N}(y_t \mid (z_t - s)^2, \gamma^{-1}), +\end{aligned}\]

where the researchers put priors on the process and measurement noise parameters, $\tau$ and $\gamma$, respectively. They do this, because they do not know the accuracy of their devices.

The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:

function compute_squared_distance(z)
+    (z - reference_point)^2
+end;
@model function measurement_model(nr_observations)
+
+    # allocate random variables and observations
+    z = randomvar(nr_observations)
+    y = datavar(Float64, nr_observations)
+
+    # set priors on precision parameters
+    τ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    γ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    
+    # specify estimate of initial location
+    z[1] ~ Normal(mean = 0, precision = τ)
+    y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)
+
+    # loop over observations
+    for t in 2:nr_observations
+
+        # specify state transition model
+        z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)
+
+        # specify non-linear observation model
+        y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)
+        
+    end
+
+end

But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).

The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:

@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)
+    compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)
+end;

In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:

@meta function model_meta(...)
+    f() -> CVI(args...)
+end

See ?CVI for more information about the args....

In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.

In the above example, we will assume the following posterior factorization:

@constraints function measurement_constraints()
+    q(z, τ, γ) = q(z)q(τ)q(γ)
+end;

This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as 

@constraints function posterior_constraints() begin
+    q(z, γ) = q(z)q(γ) # CVI
+    q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node
+end

Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.

results = inference(
+    model = measurement_model(nr_observations),
+    data = (y = measurements,),
+    iterations = 5,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = measurement_constraints(),
+    meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),
+    initmessages = (z = NormalMeanVariance(0, 5),),
+    initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),
+)
Inference results:
+  Posteriors       | available for (z)
+  Free Energy:     | Real[1241.91, 429.933, 376.869, 365.774, 362.879]
# plot estimates for location
+p1 = plot(collect(1:nr_observations), hidden_location, label = "hidden location", legend=:topleft, linewidth=3, color = :red)
+plot!(map(mean, results.posteriors[:z]), label = "estimated location (±2σ)", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot Bethe free energy
+p2 = plot(results.free_energy, linewidth=3, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size = (1200, 500))

Requirements

There are several main requirements for the CVI procedure to satisfy:

  1. The out interface of the non-linearity must be independently factorized with respect to other variables in the model.
  2. The messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.

In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as

@model function model(...)
+    ...
+    y ~ f(x1, x2, ..., xN)
+    ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity
+    ... 
+end
+
+@constraints function constraints_meta() begin
+    q(y, z1, ..., zn) = q(y)q(z1,...,zM)
+    ...
+end;
+
+@meta function model_meta(...)
+    f() -> CVI(rng, nr_samples, nr_iterations, optimizer))
+end

Note that not all exponential family distributions are implemented.

Extensions

Using a custom optimizer

CVI only supports Optimisers optimizers out of the box.

Below an explanation on how to extend to it to a custom optimizer.

Suppose we have CustomDescent structure which we want to use inside CVI for optimization.

To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).

ReactiveMP.cvi_update! incapsulates the gradient step:

  1. opt is used to select your optimizer structure
  2. λ is the current value
  3. ∇ is a gradient value computed inside CVI.
struct CustomDescent 
+    learning_rate::Float64
+end
+
+# Must return an optimizer and its initial state
+function ReactiveMP.cvi_setup(opt::CustomDescent, q)
+     return (opt, nothing)
+end
+
+# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)
+function ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)
+    opt, _ = opt_and_state
+    λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))
+    copyto!(new_λ, λ̂)
+    return opt_and_state, new_λ
+end

Let's try to apply it to a model: $\begin{aligned} p(x) & = \mathcal{N}(0, 1),\\ + p(y_{i}\mid x) & = \mathcal{N}(y_i \mid x^2, 1),\\ +\end{aligned}$

Let's generate some synthetic data for the model

# generate data
+y = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)
+histogram(y)

Again we can create the corresponding model as:

# specify non-linearity
+f(x) = x ^ 2
+
+# specify model
+@model function normal_square_model(nr_observations)
+
+    # allocate observations
+    y = datavar(Float64, nr_observations)
+
+    # describe prior on latent state
+    x ~ NormalMeanPrecision(0, 100)
+
+    # transform latent state
+    mean ~ f(x)
+
+    # observation model
+    y .~ NormalMeanVariance(mean, 1)
+
+end
+
+# specify meta
+@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)
+    f() ->  CVI(rng, nr_samples, nr_iterations, optimizer)
+end
normal_square_meta (generic function with 1 method)

We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:

Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.

res = inference(
+    model = normal_square_model(1000),
+    data = (y = y,),
+    iterations = 10,
+    free_energy = true,
+    initmessages = (x = NormalMeanVariance(0, 100),),
+    meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))
+)
+
+mean(res.posteriors[:x][end])
-18.998075156688632

The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working!

Note: $x^2$ can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.

diff --git a/v2.15.0/examples/advanced_examples/GP Regression by SSM/index.html b/v2.15.0/examples/advanced_examples/GP Regression by SSM/index.html new file mode 100644 index 000000000..5355828c1 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/GP Regression by SSM/index.html @@ -0,0 +1,99 @@ + +Solve GP regression by SDE · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Solve GP regression by SDE

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this notebook, we solve a GP regression problem by using "Stochastic Differential Equation" (SDE). This method is well described in the dissertation "Stochastic differential equation methods for spatio-temporal Gaussian process regression." by Arno Solin and "Sequential Inference for Latent Temporal Gaussian Process Models" by Jouni Hartikainen. The idea of the method is as follows.

Suppose a function $f(x)$ follows a zero-mean Gaussian Process $\begin{aligned} f(x) \sim \mathcal{GP}(0, k(x,x')). \end{aligned}$

When the dimensionality of $x$ is 1, we can consider $f(x)$ as a stochastic process over time, i.e. $f(t)$. For a certain classses of covariance functions, $f(t)$ is a solution to an $m$-th order linear stochastic differential equation (SDE) $\begin{aligned} a_0 f(t) + a_1 \frac{d f(t)}{dt} + \dots + a_m \frac{d^m f(t)}{dt^m} = w(t) \end{aligned}$

where $w(t)$ is a zero-mean white noise process with spectral density $Q_c$. If we define a vector-valued function $\mathbf{f}(t) = (f(t),\, d/dt f(t),\dots,\, d^{m-1}/dt^{m-1}f(t))$, then we can rewrite the above SDE under the companion form

\[\begin{aligned} +\frac{d \mathbf{f}(t)}{dt} = \mathbf{F}\, \mathbf{f}(t) + \mathbf{L} w(t) \quad (1) +\end{aligned}\]

where $\mathbf{F}$ and $\mathbf{L}$ are defined based on the choice of covariance functions. From (1), we have the following state-space model: $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \quad(2a) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}) \quad(2b). \\ +\end{aligned}$

where $\mathbf{A}_k = \exp{(\mathbf{F}\,\Delta t_k)}$, with $\Delta t_k = t_{k+1} - t_k$, is called the discrete-time state transition matrix, and $\mathbf{Q}_k$ the process noise covariance matrix. For the computation of $\mathbf{Q}_k$, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state $f_0 \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_0)$. For stationary covariance function, the SDE has a stationary state $f_\infty \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_\infty)$, where $\mathbf{P}_\infty$ is the solution to $\begin{aligned} \frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0 \quad (\mathrm{Lyapunov \, equation}). \end{aligned}$

With this stationary condition, the process noise covariance $\mathbf{Q}_k$ is computed as follows $\begin{aligned} \mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T \end{aligned}$

For one-dimensional problem the SDE representation of the GP is defined by the matrices $\mathbf{F}, \, \mathbf{L}, \, \mathbf{Q}_c, \, \mathbf{P}_0$ and $\mathbf{H}$. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.

using RxInfer, Random, Distributions, LinearAlgebra, Plots

Create state space model for GP regression

Here we create a state-space model $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}), \\ +\end{aligned}$ where $y_k$ is the noisy observation of the function $f$ at time $t_k$, and $\sigma^2_{noise}$ is the noise variance and assumed to be known.

@model function gp_regression(n, P∞, A, Q, H, σ²_noise)
+    f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)
+    f = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+    
+    f_prev = f_0
+
+    for i=1:n
+        f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])
+        y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)
+        f_prev = f[i]
+    end
+    return f, y
+end

Generate data

Random.seed!(10)
+n = 100
+σ²_noise = 0.04;
+t = collect(range(-2, 2, length=n)); #timeline
+f_true = sinc.(t); # true process
+f_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process
+
+pos = sort(randperm(75)[1:2:75]); 
+t_obser = t[pos]; # time where we observe data
+
+y_data = Array{Union{Float64,Missing}}(missing, n)
+for i in pos 
+    y_data[i] = f_noisy[i]
+end
+
+θ = [1., 1.]; # store [l, σ²]
+Δt = [t[1]]; # time difference
+append!(Δt, t[2:end] - t[1:end-1]);

Let's visualize our data

plot(t, f_true, label="True process f(t)")
+scatter!(t_obser, y_data[pos], label = "Noisy observations")
+xlabel!("t")
+ylabel!("f(t)")

Covariance function: Matern-3/2

The Matern is a stationary covariance function and defined as follows $\begin{aligned} k(\tau) = \sigma^2 \frac{2^{1-\nu}}{\Gamma(\nu)} \left(\frac{\sqrt{2\nu}\tau}{l} \right)^\nu K_\nu\left(\frac{\sqrt{2\nu}\tau}{l} \right) \end{aligned}$ where $\begin{aligned} \sigma^2: \text{the magnitude scale hyperparameter}\\ +l: \text{the characteristic length-scale}\\ +\nu: \text{the smoothness hyperparameter}\\ +K_\nu(.): \text{the modified Bessel function of the second kind}. \end{aligned}$ When we say the Matern-3/2, we mean $\nu=3/2$. The matrices for the state space model are computed as follows $\begin{aligned} \mathbf{F} = \begin{pmatrix} 0 & 1\\ +-\lambda^2 & -2\lambda \end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} 0 \\ 1 \end{pmatrix}, \quad \quad \mathbf{P}_\infty = \begin{pmatrix} \sigma^2 & 0 \\ 0 & \lambda^2\sigma^2 \end{pmatrix} ,\quad \quad \mathbf{H} = \begin{pmatrix} 1 & 0 \end{pmatrix}, \quad \quad Q_c = 4\lambda^3\sigma^2 \end{aligned}$ where $\lambda = \frac{\sqrt{3}}{l} $. From these matrices, we can define $\mathbf{A}_k$ and $\mathbf{Q}_k$.

λ = sqrt(3)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 1.];
+H = [1., 0.];
+F = [0. 1.; -λ^2 -2λ]
+P∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_32 = inference(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Covariance function: Matern-5/2

Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:

\[\begin{aligned} +\mathbf{F} = \begin{pmatrix} +0 & 1 & 0\\ +0 & 0 & 1 \\ +-\lambda^3 & -3\lambda^2 & -3\lambda +\end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} +0 \\ 0 \\ 1 +\end{pmatrix}, \quad \quad \mathbf{H} = \begin{pmatrix} +1 & 0 & 0 +\end{pmatrix}, \quad \quad Q_c = \frac{16}{3} \sigma^2 \lambda^5, +\end{aligned}\]

where $\lambda = \sqrt{5} / l$. To find $\mathbf{P}_\infty$, we solve the Lyapunov equation

\[\begin{aligned} +\frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0, +\end{aligned}\]

of which the solution is

\[\begin{aligned} +vec(\mathbf{P}_\infty) = (\mathbf{I} \otimes \mathbf{F} + \mathbf{F}\otimes\mathbf{I})^{-1}\, vec(-\mathbf{L}Q_c\mathbf{L}^T) +\end{aligned}\]

where $vec(.)$ is the vectorization operator and $\otimes$ denotes the Kronecker product. Now we can find $\mathbf{A}_k$ and $\mathbf{Q}_k$

\[\begin{aligned} +\mathbf{A}_k = \exp{(\mathbf{F}\Delta t_k)} +\end{aligned}\]

\[\begin{aligned} +\mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T +\end{aligned}\]

λ = sqrt(5)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 0., 1.];
+H = [1., 0., 0.];
+F = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]
+Qc = 16/3 * θ[2] * λ^5;
+
+I = diageye(3) ; 
+vec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); 
+P∞ = reshape(vec_P,3,3);
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_52 = inference(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Result

slicedim(dim) = (a) -> map(e -> e[dim], a)
+
+plot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M32", title = "Matern-3/2", legend =false, lw = 2)
+plot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M52",legend = :bottomleft, title = "GPRegression by SSM", lw = 2)
+plot!(t, f_true,label="true process", lw = 2)
+scatter!(t_obser, f_noisy[pos], label="Observations")
+xlabel!("t")
+ylabel!("f(t)")

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.

diff --git a/v2.15.0/examples/advanced_examples/Global Parameter Optimisation/index.html b/v2.15.0/examples/advanced_examples/Global Parameter Optimisation/index.html new file mode 100644 index 000000000..222a3c155 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Global Parameter Optimisation/index.html @@ -0,0 +1,497 @@ + +Global Parameter Optimisation · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Global Parameter Optimisation

This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.

By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Univariate State Space Model

Let us try use the following simple state space model:

\[\begin{aligned} + {x}_t &= {x}_{t-1} + c \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, p \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Our goal is to optimize parameters $c$ and ${m_{{x}_0}}$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)
+    
+    x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n)
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ x_prev + c
+        y[i] ~ NormalMeanVariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+
+    return x, y
+end
rng = MersenneTwister(42)
+
+P      = 1.0
+n      = 250
+c_real = -5.0
+data   = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);
# c[1] is C
+# c[2] is μ0
+function f(c)
+    x0_prior = NormalMeanVariance(c[2], 100.0)
+    result = inference(
+        model = smoothing(n, x0_prior, c[1], P), 
+        data  = (y = data,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
using Optim
res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     3.651509e+02     1.001412e+03
+ * time: 0.04605293273925781
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     3.645772e+02
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.18e-06 ≰ 0.0e+00
+    |x - x'|/|x'|          = 2.30e-07 ≰ 0.0e+00
+    |f(x) - f(x')|         = 9.13e-07 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00
+    |g(x)|                 = 2.56e-06 ≤ 1.0e-03
+
+ * Work counters
+    Seconds run:   6  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    67
+    ∇f(x) calls:   67
res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)
2-element Vector{Float64}:
+  1.0007749243942134
+ -5.14368311177876
println("Real value vs Optimized")
+println("Real:      ", [ 1.0, c_real ])
+println("Optimized: ", res.minimizer)
Real value vs Optimized
+Real:      [1.0, -5.0]
+Optimized: [1.0007749243942134, -5.14368311177876]

Multivariate state space model

Let us consider the multivariate state space model:

\[\begin{aligned} + \mathbf{x}_t &\sim \mathcal{N}\left(\mathbf{Ax}_{t-1}, \mathbf{Q} \right) \\ + \mathbf{y}_t &\sim \mathcal{N}\left(\mathbf{x}_{t}, \mathbf{P} \right) +\end{aligned}\]

with prior

\[\begin{aligned} +\mathbf{x}_0 \sim \mathcal{N}(\mathbf{m_{{x}_0}}, \mathbf{V_{{x}_0}})\ +\end{aligned}\]

and transition matrix

\[\begin{aligned} +\mathbf{A} = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} +\end{aligned}\]

Covariance matrices $\mathbf{V_{{x}_0}}$, $\mathbf{P}$ and $\mathbf{Q}$ are known. Our goal is to optimize parameters $\mathbf{m_{{x}_0}}$ and $\theta$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)
+    
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    
+    x_prev = x_prior
+    
+    A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)
+        y[i] ~ MvNormalMeanCovariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+    
+end
# Generate data
+function generate_rotate_ssm_data()
+    rng = MersenneTwister(1234)
+
+    θ = π / 8
+    A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+    Q = Matrix(Diagonal(1.0 * ones(2)))
+    P = Matrix(Diagonal(1.0 * ones(2)))
+
+    n = 300
+
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(x[i], Q))
+        
+        x_prev = x[i]
+    end
+
+    return θ, A, Q, P, n, x, y
+end
generate_rotate_ssm_data (generic function with 1 method)
θ, A, Q, P, n, x, y = generate_rotate_ssm_data();
px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+
+plot(px, size = (1200, 450))

function f(θ)
+    x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))
+    result = inference(
+        model = rotate_ssm(n, θ[1], x0, Q, P), 
+        data  = (y = y,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     2.192003e+04     9.032537e+04
+ * time: 7.200241088867188e-5
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.161372e+03
+
+ * Found with
+    Algorithm:     L-BFGS
+
+ * Convergence measures
+    |x - x'|               = 5.09e-09 ≰ 0.0e+00
+    |x - x'|/|x'|          = 4.48e-10 ≰ 0.0e+00
+    |f(x) - f(x')|         = 0.00e+00 ≤ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14
+    |g(x)|                 = 5.63e-07 ≰ 1.0e-12
+
+ * Work counters
+    Seconds run:   19  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    58
+    ∇f(x) calls:   58
println("Real value vs Optimized")
+println("Real:      ", θ)
+println("Optimized: ", res.minimizer[1])
+
+@show sin(θ), sin(res.minimizer[1])
+@show cos(θ), cos(res.minimizer[1])
Real value vs Optimized
+Real:      0.39269908169872414
+Optimized: 0.3929332481380117
+(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)
+(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)
+(0.9238795325112867, 0.9237898955654058)
x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))
+
+result = inference(
+    model = rotate_ssm(n, res.minimizer[1], x0, Q, P), 
+    data  = (y = y,), 
+    free_energy = true
+)
+
+xmarginals = result.posteriors[:x]
+
+px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "inf₁")
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "inf₂")
+
+plot(px, size = (1200, 450))

Learning Kalman filter with LSTM driven dynamic

In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example.

Our objective is to compute the marginal posterior distribution of the latent (hidden) state $x_k$ at each time step $k$, considering the history of measurements up to that time step:

\[ +p(x_k | y_{1:k}). +$$ + +The above expression represents the probability distribution of the latent state $x_k$ given the measurements $y_{1:k}$ up to time step $k$. + +```julia +using RxInfer, BenchmarkTools, Flux, ReverseDiff, Random, Plots, LinearAlgebra, ProgressMeter, JLD, StableRNGs +``` + + + +### Generate data + +```julia +# Lorenz system equations to be used to generate dataset +Base.@kwdef mutable struct Lorenz + dt::Float64 + σ::Float64 + ρ::Float64 + β::Float64 + x::Float64 + y::Float64 + z::Float64 +end + +function step!(l::Lorenz) + dx = l.σ * (l.y - l.x); l.x += l.dt * dx + dy = l.x * (l.ρ - l.z) - l.y; l.y += l.dt * dy + dz = l.x * l.y - l.β * l.z; l.z += l.dt * dz +end +; +``` + + +```julia +# Dataset +rng = StableRNG(999) + +ordered_dataset = [] +ordered_parameters = [] +for σ = 11:15 + for ρ = 23:27 + for β_nom = 6:9 + attractor = Lorenz(0.02, σ, ρ, β_nom/3.0, 1, 1, 1) + noise_free_data = [[1.0, 1.0, 1.0]] + for i=1:99 + step!(attractor) + push!(noise_free_data, [attractor.x, attractor.y, attractor.z]) + end + push!(ordered_dataset, noise_free_data) + push!(ordered_parameters, [σ, ρ, β_nom/3.0]) + end + end +end + +new_order = collect(1:100) +shuffle!(rng,new_order) + +dataset = [] # noisy dataset +noise_free_dataset = [] # noise free dataset +lorenz_parameters = [] + +for i in new_order + local data = [] + push!(noise_free_dataset, ordered_dataset[i]) + push!(lorenz_parameters, ordered_parameters[i]) + for nfd in ordered_dataset[i] + push!(data,nfd+randn(rng,3)) + end + push!(dataset, data) +end + +trainset = dataset[1:60] +validset = dataset[61:80] +testset = dataset[81:end] + +noise_free_trainset = noise_free_dataset[1:60] +noise_free_validset = noise_free_dataset[61:80] +noise_free_testset = noise_free_dataset[81:end] +; +``` + + + +### Data visualization + +```julia +one_nonoise=noise_free_trainset[1] +one=trainset[1] +gx, gy, gz = zeros(100), zeros(100), zeros(100) +rx, ry, rz = zeros(100), zeros(100), zeros(100) +for i=1:100 + rx[i], ry[i], rz[i] = one[i][1], one[i][2], one[i][3] + gx[i], gy[i], gz[i] = one_nonoise[i][1], one_nonoise[i][2], one_nonoise[i][3] +end +p1=plot(rx,ry,label="Noise observations") +p1=plot!(gx,gy,label="True state") +xlabel!("x") +ylabel!("y") +p2=plot(rx,rz,label="Noise observations") +p2=plot!(gx,gz,label="True state") +xlabel!("x") +ylabel!("z") +p3=plot(ry,rz,label="Noise observations") +p3=plot!(gy,gz,label="True state") +xlabel!("y") +ylabel!("z") +plot(p1, p2, p3, size = (800, 200),layout=(1,3)) +``` + +![](../../assets/examples/Global Parameter Optimisation_22_1.png) + + +### Inference + + +We use the following state-space model representation: + +$$\begin{aligned} +x_k \sim p(x_k | x_{k-1}) \\ +y_k \sim p(y_k | x_k). +\end{aligned}\]

where $x_k \sim p(x_k | x_{k-1})$ represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system.

\[\begin{aligned} +A_{k-1}=NN(y_{k-1}) \\ +p(x_k | x_{k-1})=\mathcal{N}(x_k | A_{k-1}x_{k-1}, Q) \\ +p(y_k | x_k)=\mathcal{N}(y_k | Bx_k, R) +\end{aligned}\]

where $NN$ is the neural network. The input is the observation $y_{k-1}$, and output is the trasition matrix $A_{k-1}$. $B$ denote distortion or measurment matrix. $Q$ and $R$ are covariance matrices. Note that the hidden state $x_k$ comprises three coordinates, i.e. $x_k = (rx_k, ry_k, rz_k)$

By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.

# Neural Network model
+mutable struct NN
+    InputLayer
+    OutputLater
+    g
+    params
+    function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+        InputLayer = Dense(W1, b1, relu)
+        Lstm = LSTM(W2_1,W2_2,b2,s2_1)
+        OutputLayer = Dense(W3, b3)
+        g = Chain(InputLayer, OutputLayer);
+        new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))
+    end
+end

Model specification

Note that we treat the trasition matrix $A_{k-1}$ as time-varying.

#State Space Model
+@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior_mean = zeros(3)
+    x_prior_cov  = Matrix(Diagonal(ones(3)))
+    
+    x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)
+    y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }
+    
+    for i in 2:n
+        x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }
+        y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }
+    end
+    
+    return x, y
+end

We set distortion matrix $B$ and the covariance matrices $Q$ and $R$ as identity matrix.

Q = Matrix(Diagonal(ones(3)))*2
+B = Matrix(Diagonal(ones(3)))
+R = Matrix(Diagonal(ones(3)))
+;

We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix $A$ output by the neural network. And the $A$ is treated as a datavar in the inference function.

function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    n = length(data)
+    neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])
+    return As
+end
get_matrix_AS (generic function with 1 method)

The weights of neural network $NN$ are initialized as follows:

# Initial model parameters
+W1, b1 = randn(5, 3)./100, randn(5)./100
+W2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)
+W3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100
+;

Before network training, we show the inference results for the hidden states:

# Performance on an instance from the testset before training
+index = 1
+data=testset[index]
+n=length(data)
+result = inference(
+    model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300))

Training network

In this part, we use the Free Energy as the objective function to optimize the weights of network.

# free energy objective to be optimized during training
+function fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    fe_ = 0
+    for train_instance in trainset
+        result = inference(
+            model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+            data  = (y = train_instance, ), 
+            returnvars = (x = KeepLast(), ),
+            free_energy = true
+        )
+        fe_ += result.free_energy[end]
+    end
+    return fe_
+end
fe_tot_est (generic function with 1 method)

Training

# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights
+# Uncomment the following code to train the network manually
+# opt = Flux.Optimise.RMSProp(0.006, 0.95)
+# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+# @showprogress for epoch in 1:800
+#     grads = ReverseDiff.gradient(fe_tot_est, params);
+#     for i=1:length(params)
+#         Flux.Optimise.update!(opt,params[i],grads[i])
+#     end
+# end

Test

Import the weights of neural network that we have trained.

W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load("../data/nn_prediction/weights.jld")["data"];
# Performance on an instance from the testset after training
+index = 1
+data = testset[index]
+n = length(data)
+result = inference(
+    model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+
+gx, gy, gz = zeros(100), zeros(100), zeros(100)
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+plot(p1, p2, p3, size = (1000, 300))

Prediction

In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill $k$ and estimate the future state at time $k+1$, $k+2$, $\dots$,$k+T$.

We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.

\[\begin{aligned} +A_{k}=NN(x_{k}) \\ +p(x_{k+1} | x_{k})=\mathcal{N}(x_{k+1} | A_{k}x_{k}, Q) \\ +\end{aligned}\]

#Define the prediction function
+multiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))
+sumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)
+
+function runForward(A,B,Q,R,mh_old,Vh_old)
+    mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)
+    mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)
+end
+
+function g_predict(mh_old,Vh_old,Q)
+    neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)
+    # Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])
+    As = As[1]
+    return runForward(As,B,Q,R,mh_old,Vh_old), As
+end
g_predict (generic function with 1 method)

After $k=75$, the observations are not available, and we predict the future state from $k=76$ to the end

tt = 75
+mh = mean(x_est[tt])
+Vh = cov(x_est[tt])
+mo_list, Vo_list, A_list = [], [], [] 
+inv_Q = inv(Q)
+for t=1:100-tt
+    (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)
+    push!(mo_list, mo)
+    push!(Vo_list, Vh)
+    push!(A_list, A_t)
+    global mh = mo
+    global Vh = Vo
+end
# Prediction visualization
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+for i=1:tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+for i=tt+1:100
+    ii=i-tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]
+end
+p1 = plot(rx,label="Ground truth rx")
+p1 = plot!(rx_est_m,label="Inffered state rx",ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Ground truth ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index][1:tt], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Ground truth rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)

diff --git a/v2.15.0/examples/advanced_examples/Infinite Data Stream/index.html b/v2.15.0/examples/advanced_examples/Infinite Data Stream/index.html new file mode 100644 index 000000000..941dca370 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Infinite Data Stream/index.html @@ -0,0 +1,169 @@ + +Infinite Data Stream · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Infinite Data Stream

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:

using RxInfer, Plots, Random, StableRNGs

For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:

mutable struct Environment
+    rng                   :: AbstractRNG
+    current_state         :: Float64
+    observation_precision :: Float64
+    history               :: Vector{Float64}
+    observations          :: Vector{Float64}
+    
+    Environment(current_state, observation_precision; seed = 123) = begin 
+         return new(StableRNG(seed), current_state, observation_precision, [], [])
+    end
+end
+
+function getnext!(environment::Environment)
+    environment.current_state = environment.current_state + 1.0
+    nextstate  = 10sin(0.1 * environment.current_state)
+    observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))
+    push!(environment.history, nextstate)
+    push!(environment.observations, observation)
+    return observation
+end
+
+function gethistory(environment::Environment)
+    return environment.history
+end
+
+function getobservations(environment::Environment)
+    return environment.observations
+end
getobservations (generic function with 1 method)

Model specification

We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:

@model function kalman_filter()
+    
+    # Prior for the previous state
+    x_prev_mean = datavar(Float64)
+    x_prev_var  = datavar(Float64)
+    
+    x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)
+    
+    # Prior for the observation noise
+    τ_shape = datavar(Float64)
+    τ_rate  = datavar(Float64)
+    
+    τ ~ Gamma(shape = τ_shape, rate = τ_rate)
+    
+    # Random walk with fixed precision
+    x_current ~ Normal(mean = x_prev, precision = 1.0)
+    
+    # Noisy observation
+    y = datavar(Float64)
+    y ~ Normal(mean = x_current, precision = τ)
+    
+end
+
+# We assume the following factorisation between variables 
+# in the variational distribution
+@constraints function filter_constraints()
+    q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)
+end
filter_constraints (generic function with 1 method)

Prepare environment

initial_state         = 0.0
+observation_precision = 0.1
0.1

After we have created the environment we can observe how our signal behaves:

testenvironment = Environment(initial_state, observation_precision);
+
+animation = @animate for i in 1:100
+    getnext!(testenvironment)
+    
+    history = gethistory(testenvironment)
+    observations = getobservations(testenvironment)
+    
+    p = plot(size = (1000, 300))
+    
+    p = plot!(p, 1:i, history[1:i], label = "Hidden signal")
+    p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = "Observation")
+end
+
+gif(animation, "../pics/infinite-data-stream.gif", fps = 24, show_msg = false);

Filtering on static dataset

RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:

n                  = 300
+static_environment = Environment(initial_state, observation_precision);
+
+for i in 1:n
+    getnext!(static_environment)
+end
+
+static_history      = gethistory(static_environment)
+static_observations = getobservations(static_environment);
+static_datastream   = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
function run_static(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    engine = rxinference(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        keephistory   = 10_000,
+        historyvars   = (x_current = KeepLast(), τ = KeepLast()),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        free_energy   = true,
+        autostart     = true,
+    )
+    
+    return engine
+end
run_static (generic function with 1 method)
result = run_static(static_environment, static_datastream);
static_inference = @animate for i in 1:n
+    estimated = result.history[:x_current]
+    p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = "Estimation")
+    p = plot!(static_history[1:i], label = "Real states")    
+    p = scatter!(static_observations[1:i], ms = 2, label = "Observations")
+    p = plot(p, size = (1000, 300), legend = :bottomright)
+end
+
+gif(static_inference, "../pics/infinite-data-stream-inference.gif", fps = 24, show_msg = false);

plot(result.free_energy_history, label = "Bethe Free Energy (averaged)")

Filtering on realtime dataset

Next lets create a "real" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:

function run_and_plot(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    posteriors = []
+    
+    plotfn = (q_current) -> begin 
+        IJulia.clear_output(true)
+        
+        push!(posteriors, q_current)
+
+        p = plot(mean.(posteriors), ribbon = var.(posteriors), label = "Estimation")
+        p = plot!(gethistory(environment), label = "Real states")    
+        p = scatter!(getobservations(environment), ms = 2, label = "Observations")
+        p = plot(p, size = (1000, 300), legend = :bottomright)
+
+        display(p)
+    end
+    
+    engine = rxinference(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        autostart     = false,
+    )
+    
+    qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)
+    
+    RxInfer.start(engine)
+    
+    return engine
+end
run_and_plot (generic function with 1 method)
# This example runs in our documentation pipeline, which does not support "real-time" execution context
+# We skip this code if run not in Jupyter notebook (see below an example with gif)
+engine = nothing 
+if isdefined(Main, :IJulia)
+    timegen      = 41 # 41 ms
+    environment  = Environment(initial_state, observation_precision);
+    observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations
+    datastream   = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
+    engine = run_and_plot(environment, datastream)
+end;

The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:

if !isnothing(engine) && isdefined(Main, :IJulia)
+    RxInfer.stop(engine)
+    IJulia.clear_output(true)
+end;
diff --git a/v2.15.0/examples/advanced_examples/Nonlinear Sensor Fusion/index.html b/v2.15.0/examples/advanced_examples/Nonlinear Sensor Fusion/index.html new file mode 100644 index 000000000..8c2d46d0a --- /dev/null +++ b/v2.15.0/examples/advanced_examples/Nonlinear Sensor Fusion/index.html @@ -0,0 +1,140 @@ + +Nonlinear Sensor Fusion · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Nonlinear Sensor Fusion

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers
+using DataFrames, DelimitedFiles, StableRNGs

In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.

A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.

To illustrate these noisy measurements, the engineers decided to plot them:

# fetch measurements
+beacon_locations = readdlm("../data/sensor_fusion/beacons.txt")
+distances = readdlm("../data/sensor_fusion/distances.txt")
+position = readdlm("../data/sensor_fusion/position.txt")
+nr_observations = size(distances, 1);
# plot beacon and actual location of WALL-E
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+xlabel!("longitude [m]"), ylabel!("latitude [m]")
+
+# plot noisy distance measurements
+p2 = plot(distances, legend=:topleft, linewidth=3, label=["distance to beacon 1" "distance to beacon 2" "distance to beacon 3"])
+xlabel!("time [sec]"), ylabel!("distance [m]")
+
+plot(p1, p2, size=(1200, 500))

In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time $t$, denoted by $z_t$, follows a 2-dimensional normal random walk:

\[\begin{aligned} + & p(z_t \mid z_{t - 1}) = \mathcal{N}(z_t \mid z_{t-1},~\mathrm{I}_{2}),\\ +\end{aligned}\]

where $\mathrm{I}_2$ denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements $y_t$ as a noisy set of the distances between WALL-E and the beacons, specified by $s_i$:

\[\begin{aligned} + & p(y_t \mid z_t) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~\mathrm{I}_{3}\! \right . \right)\!. +\end{aligned}\]

The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:

# function to compute distance to beacons
+function compute_distances(z)    
+    distance1 = norm(z - beacon_locations[1,:])
+    distance2 = norm(z - beacon_locations[2,:])
+    distance3 = norm(z - beacon_locations[3,:])
+    distances = [distance1, distance2, distance3]
+end;
@model function random_walk_model(nr_observations)
+    
+    # specify precision matrices
+    W = diageye(2)
+    R = diageye(3)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], W)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;

Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.

Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:

    compute_distances(z) -> CVI(..., Val(false), ...)

This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.

@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)
+    compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)
+end;

NOTE: You can try out different meta for approximating the nonlinearity, e.g.

@meta function random_walk_linear_meta()
+    compute_distances(z) -> Linearization()
+end;
@meta function random_walk_unscented_meta()
+    compute_distances(z) -> Unscented()
+end;
results_fast = inference(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),
+);
results_accuracy = inference(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1000, 100, StableRNG(42)),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),
+);

After running this fast inference procedure, the engineers plot the results and evaluate the performance:

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_fast.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Fast (1 sample, 3 iterations)"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot beacon and actual and estimated location of WALL-E (accurate inference)
+p2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_accuracy.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Accurate (1000 samples, 100 iterations)"); p2.series_list[end][:label] = "estimated location ±2σ"
+
+plot(p1, p2, size=(1200, 500))

The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, $Q$ and $R$ respectively. They did this by adding Wishart priors to those matrices:

\[\begin{aligned} + & p(Q) = \mathcal{W}(Q \mid 3, \mathrm{I}_2), \\ + & p(R) = \mathcal{W}(R \mid 4, \mathrm{I}_3), \\ + & p(z_t \mid z_{t - 1}, Q) = \mathcal{N}(z_t \mid z_{t-1}, Q^{-1}),\\ + & p(y_t \mid z_t, R) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~R^{-1}\! \right . \right)\!. +\end{aligned}\]

@model function random_walk_model_wishart(nr_observations)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # set priors on precision matrices
+    Q ~ Wishart(3, diageye(2))
+    R ~ Wishart(4, diageye(3))
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], Q)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;
meta = @meta begin 
+    compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)
+end;

Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:

constraints = @constraints begin
+    q(z, Q, R) = q(z)q(Q)q(R)
+end;

The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.

results_wishart = inference(
+    model = random_walk_model_wishart(nr_observations),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = constraints,
+    meta = meta,
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),
+    initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))
+);

They plot the new estimates and the performance over time, and luckily WALL-E is found!

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_wishart.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot bethe free energy performance
+p2 = plot(results_wishart.free_energy, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size=(1200, 500))

diff --git a/v2.15.0/examples/advanced_examples/overview/index.html b/v2.15.0/examples/advanced_examples/overview/index.html new file mode 100644 index 000000000..74bf641f0 --- /dev/null +++ b/v2.15.0/examples/advanced_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Advanced examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Advanced examples contain more complex inference problems.

  • Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.
  • Advanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.
  • Assessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.
  • Chance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.
  • Conjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.
  • Global Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.
  • Solve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.
  • Infinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.
  • Nonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors
diff --git a/v2.15.0/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html b/v2.15.0/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html new file mode 100644 index 000000000..086c9428f --- /dev/null +++ b/v2.15.0/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html @@ -0,0 +1,548 @@ + +Bayesian Linear Regression Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Bayesian Linear Regression Tutorial

This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM

Part 1. Bayesian Linear Regression

John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

He records the speed and fuel consumption for the urban road which is the xdata and ydata.

function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = inference(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (a, b)
+  Free Energy:     | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184
+.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821
+, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]

He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a\mid y)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0,Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b)", c=1, legend = :topleft)
+prb = vline!(prb, [ 25 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b\mid y)", c=2, legend = :topleft)
+psb = vline!(psb, [ 25 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

a = results.posteriors[:a]
+b = results.posteriors[:b]
+
+println("Real a: ", 0.5, " | Estimated a: ", mean_var(a), " | Error: ", abs(mean(a) - 0.5))
+println("Real b: ", 25.0, " | Estimated b: ", mean_var(b), " | Error: ", abs(mean(b) - 25.0))
Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err
+or: 0.001490188462705988
+Real b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error
+: 0.18735789804394898

Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:

# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Univariate regression with unknown noise

Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. $\begin{aligned} p(y_n \mid a, b, s) &= \mathcal{N}(y_n \mid ax_n + b, s)\\ +p(s) &= \mathcal{IG}(s\mid\alpha, \theta)\\ +p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ +p(b) &= \mathcal{N}(b \mid m_b, v_b) \end{aligned}$

@model function linear_regression_unknown_noise(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    s ~ InverseGamma(1.0, 1.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = s)
+end
x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)
+
+scatter(x_data_un, y_data_un, title = "Dateset with unknown noise (mountain road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results_unknown_noise = inference(
+    model           = linear_regression_unknown_noise(length(x_data_un)), 
+    data            = (y = y_data_un, x = x_data_un), 
+    initmessages    = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars      = (a = KeepLast(), b = KeepLast(), s = KeepLast()), 
+    iterations      = 20,
+    constraints     = MeanField(),
+    initmarginals   = (s = vague(InverseGamma), ),
+    free_energy     = true
+)
Inference results:
+  Posteriors       | available for (a, b, s)
+  Free Energy:     | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125
+.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56
+, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]

Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:

plot(results_unknown_noise.free_energy, title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Below he visualizes the obtained posterior distributions for parameters:

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(a)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0, Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(b)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 25.0 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(b)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 25.0 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L"Prior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(s)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 200 ], label=L"True $s$", c = 3)
+psb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L"Posterior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(s)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 200 ], label=L"True $s$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$s$", ylabel=L"$p(s)$", ylims=[0, Inf])

He sees that in the presence of more noise the inference result is more uncertain about the actual values for $a$ and $b$ parameters.

John samples $a$ and $b$ and plot many possible regression lines on the same plot:

as = rand(results_unknown_noise.posteriors[:a], 100)
+bs = rand(results_unknown_noise.posteriors[:b], 100)
+p = scatter(x_data_un, y_data_un, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)
+end
+
+plot(p, size = (900, 400))

From this plot John can see that many lines do fit the data well and there is no definite "best" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.

Multivariate linear regression

In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.

@model function linear_regression_multivariate(dim, nr_samples)
+    a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))
+    b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))
+    W ~ InverseWishart(dim + 2, 100 * diageye(dim))
+
+    # Here is a small trick to make the example work
+    # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`
+    x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)
+    y = datavar(Vector{Float64}, nr_samples)
+    z = randomvar(nr_samples)
+
+    z .~ x .* a .+ b
+    y .~ MvNormal(mean = z, covariance = W)
+
+end

After received all the measurement records, he plots the measurements and performance index:

dim_mv = 6
+nr_samples_mv = 50
+rng_mv = StableRNG(42)
+a_mv = randn(rng_mv, dim_mv)
+b_mv = 10 * randn(rng_mv, dim_mv)
+v_mv = 100 * rand(rng_mv, dim_mv)
+
+x_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));
p = plot(title = "Multivariate linear regression", legend = :topleft)
+
+plt = palette(:tab10)
+
+data_set_label = [""]
+
+for k in 1:dim_mv
+    global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = "Measurement #$k", ms = 2, color = plt[k])
+end
+xlabel!(L"$x$")
+ylabel!(L"$y$")
+p

Before this data can be used to perform inference, John needs to change its format slightly.

x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)
+y_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);
results_mv = inference(
+    model           = linear_regression_multivariate(dim_mv, nr_samples_mv),
+    data            = (y = y_data_mv_processed, x = x_data_mv_processed),
+    initmarginals   = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),
+    initmessages    = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),
+    returnvars      = (a = KeepLast(), b = KeepLast(), W = KeepLast()),
+    free_energy     = true,
+    iterations      = 50,
+    constraints     = MeanField()
+)
Inference results:
+  Posteriors       | available for (a, b, W)
+  Free Energy:     | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7
+22, 712.341, 700.865, 690.782, 682.505  …  664.434, 664.434, 664.434, 664.4
+34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]

Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.

p = plot(title = "Multivariate linear regression", legend = :topleft, xlabel=L"$x$", ylabel=L"$y$")
+
+# how many lines to plot
+r = 50
+
+i_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))
+i_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))
+
+plt = palette(:tab10)
+
+for k in 1:dim_mv
+    x_mv_k = x_data_mv[k]
+    y_mv_k = y_data_mv[k]
+
+    for i in 1:r
+        global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])
+    end
+
+    global p = scatter!(p, x_mv_k, y_mv_k, label = "Measurement #$k", ms = 2, color = plt[k])
+end
+
+# truncate the init step
+f = plot(results_mv.free_energy[2:end], title ="Bethe free energy convergence", label = nothing, xlabel = "Iteration", ylabel = "Bethe free energy [nats]") 
+
+plot(p, f, size = (1000, 400))

He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.

i_a_mv = results_mv.posteriors[:a]
+
+ps_a = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $a_{%$k}$", xlabel=L"$a_{%$k}$", ylabel=L"$p(a_{%$k})$", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])
+
+    local m_a_mv_k = mean(i_a_mv)[k]
+    local v_a_mv_k = std(i_a_mv)[k, k]
+    
+    _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(a_{%$k})$", c=2,)
+    _p = vline!(_p, [ a_mv[k] ], label=L"True $a_{%$k}$", c = 3)
+           
+    push!(ps_a, _p)
+end
+
+plot(ps_a...)

i_b_mv = results_mv.posteriors[:b]
+
+ps_b = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $b_{%$k}$", xlabel=L"$b_{%$k}$", ylabel=L"$p(b_{%$k})$", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])
+    local m_b_mv_k = mean(i_b_mv)[k]
+    local v_b_mv_k = std(i_b_mv)[k, k]
+
+    _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(b_{%$k})$", c=2,)
+    _p = vline!(_p, [ b_mv[k] ], label=L"Real $b_{%$k}$", c = 3)
+           
+    push!(ps_b, _p)
+end
+
+plot(ps_b...)

He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.

scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L"True $s_d$")
+scatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L"$\mathrm{E}[s_d] \pm \sigma$")
+plot!(; xlabel=L"Dimension $d$", ylabel="Variance", title="Estimated variance of the noise")

Part 2. Hierarchical Bayesian Linear Regression

Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro.

The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.

Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].

The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using NumPyro. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.

# https://www.machinelearningplus.com/linear-regression-in-julia/
+# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb

Understanding the Task

Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.

In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).

Now, let's explore the data and delve deeper into the problem involved.

dataset = CSV.read("../data/hbr/osic_pulmonary_fibrosis.csv", DataFrame);
describe(dataset)
7×7 DataFrame
+ Row │ variable       mean     min                        median   max     
+    ⋯
+     │ Symbol         Union…   Any                        Union…   Any     
+    ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ Patient                 ID00007637202177411956430           ID004266
+372 ⋯
+   2 │ Weeks          31.8618  -5                         28.0     133
+   3 │ FVC            2690.48  827                        2641.0   6399
+   4 │ Percent        77.6727  28.8776                    75.6769  153.145
+   5 │ Age            67.1885  49                         68.0     88      
+    ⋯
+   6 │ Sex                     Female                              Male
+   7 │ SmokingStatus           Currently smokes                    Never sm
+oke
+                                                               3 columns om
+itted
first(dataset, 5)
5×7 DataFrame
+ Row │ Patient                    Weeks  FVC    Percent  Age    Sex      Sm
+oki ⋯
+     │ String31                   Int64  Int64  Float64  Int64  String7  St
+rin ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ ID00007637202177411956430     -4   2315  58.2536     79  Male     Ex
+-sm ⋯
+   2 │ ID00007637202177411956430      5   2214  55.7121     79  Male     Ex
+-sm
+   3 │ ID00007637202177411956430      7   2061  51.8621     79  Male     Ex
+-sm
+   4 │ ID00007637202177411956430      9   2144  53.9507     79  Male     Ex
+-sm
+   5 │ ID00007637202177411956430     11   2069  52.0634     79  Male     Ex
+-sm ⋯
+                                                                1 column om
+itted

The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.

Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:

patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)
patientinfo (generic function with 1 method)
function patientchart(dataset, patient_id; line_kws = true)
+    info = patientinfo(dataset, patient_id)
+    x = info[!, "Weeks"]
+    y = info[!, "FVC"]
+
+    p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)
+    p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = "Weeks", ylabel = "FVC")
+    
+    if line_kws
+        # Use the `GLM.jl` package to estimate linear regression
+        linearFormulae = @formula(FVC ~ Weeks)
+        linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))
+        linearPredicted = predict(linearRegressor)
+        p = plot!(p, x, linearPredicted, color = :red, lw = 3)
+    end
+
+    return p
+end
patientchart (generic function with 1 method)
p1 = patientchart(dataset, "ID00007637202177411956430")
+p2 = patientchart(dataset, "ID00009637202177434476278")
+p3 = patientchart(dataset, "ID00010637202177584971671")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.

Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:

The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].

Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling

In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the "pooled model." On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the "unpooled model," where each patient has completely separate regression lines.

In this analysis, we will adopt a middle ground approach known as "Partial pooling." Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:

Mathematically, the model is described by the following equations:

\[\begin{equation} + \begin{aligned} + \mu_\alpha &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 250000.0) \\ + \sigma_\alpha &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mu_\beta &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 9.0) \\ + \sigma_\beta &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 1.36) \\ + \alpha_i &\sim \mathcal{N}(\mathrm{mean} = \mu_\alpha, \mathrm{precision} = \sigma_\alpha) \\ + \beta &\sim \mathcal{N}(\mathrm{mean} = \mu_\beta, \mathrm{precision} = \sigma_\beta) \\ + \sigma &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mathrm{FVC}_{ij} &\sim \mathcal{N}(\mathrm{mean} = \alpha_i + t \beta_i, \mathrm{precision} = \sigma) + \end{aligned} +\end{equation}\]

where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!

Implementing this model in RxInfer is pretty straightforward:

@model function partially_pooled(patient_codes, weeks)
+    μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β ~ Normal(mean = 0.0, var = 9.0)      # Prior for the mean of β (slope)
+    σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)
+    σ_β ~ Gamma(shape = 1.75, scale = 1.36)  # Prior for the precision of β (slope)
+
+    n_codes = length(patient_codes)            # Total number of data points
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    α = randomvar(n_patients)                # Individual intercepts for each patient
+    β = randomvar(n_patients)                # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution
+        β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54)   # Prior for the standard deviation of the error term
+    
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes) # Observed FVC measurements
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+end

Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.

@constraints function partially_pooled_constraints()
+    # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent
+    q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)
+    # Assume that `μ_α`, `σ_α`, `α` are jointly independent
+    q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)
+    # Assume that `μ_β`, `σ_β`, `β` are jointly independent
+    q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)
+    # Assume that `FVC_est`, `σ` are jointly independent
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_constraints (generic function with 1 method)

These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!

Inference in the model

A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.

Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.

patient_ids          = dataset[!, "Patient"] # get the column of all patients
+patient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));
+patient_code_column  = map(patient -> patient_code_encoder[patient], patient_ids)
+
+dataset[!, :PatientCode] = patient_code_column
+
+first(patient_code_encoder, 5)
5-element Vector{Pair{InlineStrings.String31, Int64}}:
+ "ID00197637202246865691526" => 85
+ "ID00388637202301028491611" => 160
+ "ID00341637202287410878488" => 142
+ "ID00020637202178344345685" => 9
+ "ID00305637202281772703145" => 127
function partially_pooled_inference(dataset)
+
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+
+    results = inference(
+        model = partially_pooled(patient_codes, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+            σ = vague(Gamma),
+            σ_α = vague(Gamma),
+            σ_β = vague(Gamma),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100
+    )
+    
+end
partially_pooled_inference (generic function with 1 method)

We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.

In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. 

partially_pooled_inference_results = partially_pooled_inference(dataset)
Inference results:
+  Posteriors       | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)

Checking the model

Inspecting the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)
+    local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))
+end

Looks like our model learned personalized alphas and betas for each patient!

Visualizing FVC decline curves for some patients

Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.

function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)
+    info            = patientinfo(dataset, patient_id)
+    patient_code_id = encoder[patient_id]
+
+    patient_α = results.posteriors[:α][patient_code_id]
+    patient_β = results.posteriors[:β][patient_code_id]
+    
+    predict_weeks = range(-12, 134)
+
+    predicted = map(predict_weeks) do week
+        pm = mean(patient_α) + mean(patient_β) * week
+        pv = var(patient_α) + var(patient_β) * week ^ 2
+        return pm, sqrt(pv)
+    end
+    
+    p = patientchart(dataset, patient_id; kwargs...)
+    
+    return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)
+end
patientchart_bayesian (generic function with 1 method)
p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430")
+p2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278")
+p3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

The results match our expectations perfectly! Let's highlight the observations:

  • The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.

  • The model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.

  • Additionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.

Computing the modified Laplace Log Likelihood and RMSE

As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.

To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:

\[\begin{equation} + \begin{aligned} + \sigma_{\mathrm{clipped}} &= \max(\sigma, 70) \\ + \delta &= \min(\vert \mathrm{FVC}_{\mathrm{true}} - \mathrm{FVC}_{\mathrm{pred}}\vert, 1000) \\ + \mathrm{metric} &= -\frac{\sqrt{2}\delta}{\sigma_{\mathrm{clipped}}} - \mathrm{ln}(\sqrt{2}\sigma_{\mathrm{clipped}}) \\ + \end{aligned} +\end{equation}\]

To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.

function FVC_predict(results)
+    return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s
+        return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)
+    end
+end
FVC_predict (generic function with 1 method)
function compute_rmse(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    return mean((dataset[!, "FVC"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)
+end
+
+function compute_laplace_log_likelihood(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    sigma_c = std.(FVC_predicted)
+    sigma_c[sigma_c .< 70] .= 70
+    delta = abs.(mean.(FVC_predicted) .- dataset[!, "FVC"])
+    delta[delta .> 1000] .= 1000
+    return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))
+end
compute_laplace_log_likelihood (generic function with 1 method)
println("RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))")
RMSE: 124.0313266260767
+Laplace Log Likelihood: -6.15689374755478

What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!

Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.

Add layer to model hierarchy: Smoking Status

We can enhance the model by incorporating the column "SmokingStatus" as a pooling level, where model parameters will be partially pooled within the groups "Never smoked," "Ex-smoker," and "Currently smokes." To achieve this, we need to:

Encode the "SmokingStatus" column. Map the patient encoding to the corresponding "SmokingStatus" encodings. Refine and retrain the model with the additional hierarchical structure.

combine(groupby(dataset, "SmokingStatus"), nrow)
3×2 DataFrame
+ Row │ SmokingStatus     nrow
+     │ String31          Int64
+─────┼─────────────────────────
+   1 │ Ex-smoker          1038
+   2 │ Never smoked        429
+   3 │ Currently smokes     82
smoking_id_mapping   = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, "SmokingStatus"]))))
+smoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id
+    smoking_status = first(unique(patientinfo(dataset, patient_id)[!, "SmokingStatus"]))
+    return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]
+end)
+
+smoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));
@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)
+    μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)
+    σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+    σ_β_global ~ Gamma(shape = 1.75, scale = 1.36)  # Corresponds to half-normal with scale 3.0
+
+    n_codes = length(patient_codes) # Total number of data points
+    n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern
+    μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern
+    
+    for i in 1:n_smoking_statuses
+        μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)
+        μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)
+    end
+    
+    α = randomvar(n_patients) # Individual intercepts for each patient
+    β = randomvar(n_patients) # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)
+        β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes)
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+    
+end
+
+@constraints function partially_pooled_with_smooking_constraints()
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)
+    q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)
+    q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)
+    q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_with_smooking_constraints (generic function with 1 method)
function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+    
+    return inference(
+        model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_with_smooking_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            σ = Gamma(1.75, 45.54),
+            σ_α_global = Gamma(1.75, 45.54),
+            σ_β_global = Gamma(1.75, 1.36),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100,
+    )
+end
partially_pooled_with_smoking (generic function with 2 methods)
partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);

Inspect the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)
+    local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)
+    local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])
+    local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α_global)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β_global)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    local p5 = plot(title = "q(μ_α_smoking_status)...", legend = false)
+    local p6 = plot(title = "q(μ_β_smoking_status)...", legend = false)
+    
+    foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) 
+    foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)
+    
+    plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))
+end

Interpret smoking status model parameters

The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.

smoking_id_mapping
Dict{InlineStrings.String31, Int64} with 3 entries:
+  "Currently smokes" => 3
+  "Ex-smoker"        => 1
+  "Never smoked"     => 2
posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]
+
+println("Trend for")
+foreach(pairs(smoking_id_mapping)) do (key, id)
+    println("  $key: $(mean(posteriors_μ_β_smoking_status[id]))")
+end
Trend for
+  Currently smokes: 1.815745767102511
+  Ex-smoker: -4.565164617653452
+  Never smoked: -4.446729680169412

Let's look at these curves for individual patients to help interpret these model results.

# Never smoked
+p1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430") 
+# Ex-smoker
+p2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278") 
+# Currently smokes
+p3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184") 
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

Review patients that currently smoke

When plotting each patient with the smoking status "Currently smokes," we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.

Depending on the purpose of the model, we can proceed in different ways:

  • If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.

  • However, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the "Currently smokes" group's parameters closer to the global parameters, or even consider merging the group with "Ex-smokers." Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.

let 
+    local plots = []
+
+    for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==("Currently smokes"), dataset)[!, "Patient"]))
+        push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))
+    end
+
+    plot(plots..., size = (1200, 1200))
+end

Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level

We calculate the metrics for the updated model and compare to the original model.

println("RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))")
RMSE: 124.7845980866074
+Laplace Log Likelihood: -6.165346437287479

Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.

References

[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541

[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.

diff --git a/v2.15.0/examples/basic_examples/Coin Toss Model/index.html b/v2.15.0/examples/basic_examples/Coin Toss Model/index.html new file mode 100644 index 000000000..af67e8fcb --- /dev/null +++ b/v2.15.0/examples/basic_examples/Coin Toss Model/index.html @@ -0,0 +1,42 @@ + +Coin toss model (Beta-Bernoulli) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Coin toss model (Beta-Bernoulli)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example, we are going to perform an exact inference for a coin toss model that can be represented as:

\[\begin{aligned} +p(\theta) &= \mathrm{Beta}(\theta|a, b),\\ +p(y_i|\theta) &= \mathrm{Ber}(y_i|\theta),\\ +\end{aligned}\]

where $y_i \in \{0, 1\}$ is a binary observation induced by Bernoulli likelihood while $\theta$ is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of $\theta$.

We start with importing all needed packages:

using RxInfer, Random

Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:

rng = MersenneTwister(42)
+n = 500
+θ_real = 0.75
+distribution = Bernoulli(θ_real)
+
+dataset = float.(rand(rng, Bernoulli(θ_real), n));
# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(4.0, 8.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+end
result = inference(
+    model = coin_model(length(dataset)), 
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
θestimated = result.posteriors[:θ]
Beta{Float64}(α=365.0, β=147.0)
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+plot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+vline!([θ_real], label="Real θ")

diff --git a/v2.15.0/examples/basic_examples/Hidden Markov Model/index.html b/v2.15.0/examples/basic_examples/Hidden Markov Model/index.html new file mode 100644 index 000000000..a07ee3ff1 --- /dev/null +++ b/v2.15.0/examples/basic_examples/Hidden Markov Model/index.html @@ -0,0 +1,132 @@ + +How to train your Hidden Markov Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

How to train your Hidden Markov Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate()
+;

In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment.

First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time $t$, let's call the estimate of the Roomba's position $s_t$.

However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call $A$.

Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.

At time $t$, we will call our observations $x_t$ and encode the mapping from the Roomba's position to the observations in a matrix we call $B$. $B$ also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:

\[\begin{aligned} + s_t & \sim \mathcal{C}at(A s_{t-1}),\\ + x_t & \sim \mathcal{C}at(B s_t).\\ +\end{aligned}\]

This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices $A$ and $B$ so we can use them to track the whereabouts of our little cleaning agent.

using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots

In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).

To generate our observation data, we'll follow these steps:

  1. Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.
  2. Determine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.
  3. Determine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.
  4. Repeat steps 2-3 for as many samples as we want.

The following code implements this process and generates our observation data:

"""
+    rand_vec(rng, distribution::Categorical)
+
+This function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.
+"""
+function rand_vec(rng, distribution::Categorical) 
+    k = ncategories(distribution)
+    s = zeros(k)
+    drawn_category = rand(rng, distribution)
+    s[drawn_category] = 1.0
+    return s
+end
+
+function generate_data(n_samples; seed = 42)
+    
+    rng = MersenneTwister(seed)
+    
+    # Transition probabilities 
+    state_transition_matrix = [0.9 0.0 0.1;
+                                                        0.0 0.9 0.1; 
+                                                        0.05 0.05 0.9] 
+    # Observation noise
+    observation_distribution_matrix = [0.9 0.05 0.05;
+                                                                         0.05 0.9 0.05;
+                                                                         0.05 0.05 0.9] 
+    # Initial state
+    s_initial = [1.0, 0.0, 0.0] 
+    
+    states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states
+    observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations
+    
+    s_prev = s_initial
+    
+    for t = 1:n_samples
+        s_probvec = state_transition_matrix * s_prev
+        states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))
+        obs_probvec = observation_distribution_matrix * states[t]
+        observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))
+        s_prev = states[t]
+    end
+    
+    return observations, states
+end
generate_data (generic function with 1 method)

We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.

# Test data
+N = 100
+x_data, s_data = generate_data(N);
+
+scatter(argmax.(s_data), leg=false, xlabel="Time",yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]))

Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the $A$ and $B$ matrices we can use MatrixDirichlet priors. For the $A$-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on $A$ with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on $B$. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.

Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!

# Model specification
+@model function hidden_markov_model(n)
+    
+    A ~ MatrixDirichlet(ones(3,3))
+    B ~ MatrixDirichlet([ 10.0 1.0 1.0; 
+                                            1.0 10.0 1.0; 
+                                            1.0 1.0 10.0 ])
+    
+    s_0 ~ Categorical(fill(1.0 / 3.0, 3))
+    
+    s = randomvar(n)
+    x = datavar(Vector{Float64}, n)
+    
+    s_prev = s_0
+    
+    for t in 1:n
+        s[t] ~ Transition(s_prev, A) 
+        x[t] ~ Transition(s[t], B)
+        s_prev = s[t]
+    end
+    
+end
+
+# Constraints specification
+@constraints function hidden_markov_model_constraints()
+    q(s_0, s, A, B) = q(s_0, s)q(A)q(B)
+end
hidden_markov_model_constraints (generic function with 1 method)

Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?

We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.

Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!

imodel = hidden_markov_model(N)
+idata = (x = x_data,)
+
+imarginals = (
+    A = vague(MatrixDirichlet, 3, 3), 
+    B = vague(MatrixDirichlet, 3, 3), 
+    s = vague(Categorical, 3)
+)
+
+ireturnvars = (
+    A = KeepLast(),
+    B = KeepLast(),
+    s = KeepLast()
+)
+
+result = inference(
+    model         = imodel, 
+    data          = idata,
+    constraints   = hidden_markov_model_constraints(),
+    initmarginals = imarginals, 
+    returnvars    = ireturnvars, 
+    iterations    = 20, 
+    free_energy   = true
+);

That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over $A$) and about the uncertainty in the roombas observations (A good posterior over $B$). Let's see if it worked

println("Posterior Marginal for A:")
+mean(result.posteriors[:A])
Posterior Marginal for A:
+3×3 Matrix{Float64}:
+ 0.871955   0.0290008  0.0572283
+ 0.0349989  0.817591   0.135675
+ 0.0930457  0.153408   0.807097
println("Posterior Marginal for B:")
+mean(result.posteriors[:B])
Posterior Marginal for B:
+3×3 Matrix{Float64}:
+ 0.949636   0.0974741  0.0518997
+ 0.0244903  0.833632   0.0277884
+ 0.0258734  0.0688939  0.920312

Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. 

p1 = scatter(argmax.(s_data), 
+                        title="Inference results", 
+                        label = "Real", 
+                        ms = 6, 
+                        legend=:right,
+                        xlabel="Time" ,
+                        yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]),
+                        size=(900,550)
+                        )
+
+p1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),
+                        label = "Inferred",
+                        ms = 3
+                        )
+
+p2 = plot(result.free_energy, 
+                    label="Free energy",
+                    xlabel="Iteration Number"
+                    )
+
+plot(p1, p2, layout = @layout([ a; b ]))

Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.

diff --git a/v2.15.0/examples/basic_examples/Kalman filtering and smoothing/index.html b/v2.15.0/examples/basic_examples/Kalman filtering and smoothing/index.html new file mode 100644 index 000000000..1b8500622 --- /dev/null +++ b/v2.15.0/examples/basic_examples/Kalman filtering and smoothing/index.html @@ -0,0 +1,412 @@ + +Kalman filtering and smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Kalman filtering and smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.

We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.

We then solve an identification problem which does not have an analytical solution.

Utimately, we show how RxInfer.jl can deal with missing observations.

Gaussian Linear Dynamical System

LGSSM can be described with the following equations:

\[\begin{aligned} + p(x_i|x_{i - 1}) & = \mathcal{N}(x_i|A * x_{i - 1}, \mathcal{P}),\\ + p(y_i|x_i) & = \mathcal{N}(y_i|B * x_i, \mathcal{Q}), +\end{aligned}\]

where $x_i$ are hidden states, $y_i$ are noisy observations, $A$, $B$ are state transition and observational matrices, $\mathcal{P}$ and $\mathcal{Q}$ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, A, B, Q, P)
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(B * x[i], P))
+        x_prev = x[i]
+    end
+    
+    return x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 1234
+
+rng = MersenneTwister(1234)
+
+# We will model 2-dimensional observations with rotation matrix `A`
+# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`
+# are known and fixed for all time-steps
+θ = π / 35
+A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+B = diageye(2)
+Q = diageye(2)
+P = 25.0 .* diageye(2)
+
+# Number of observations
+n = 300;
x, y = generate_data(rng, A, B, Q, P);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.

px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+px = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)
+
+plot(px)

To create a model we use GraphPPL package and @model macro:

@model function rotate_ssm(n, x0, A, B, Q, P)
+    
+    # We create constvar references for better efficiency
+    cA = constvar(A)
+    cB = constvar(B)
+    cQ = constvar(Q)
+    cP = constvar(P)
+    
+    # `x` is a sequence of hidden states
+    x = randomvar(n)
+    # `y` is a sequence of "clamped" observations
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    x_prev = x_prior
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)
+        y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)
+        x_prev = x[i]
+    end
+
+end

To run inference we also specify prior for out first hidden state:

x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));
# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. 
+# inference(..., options = (limit_stack_depth = 500, ))`
+result = inference(
+    model = rotate_ssm(length(y), x0, A, B, Q, P), 
+    data = (y = y,),
+    free_energy = true
+);
+
+xmarginals  = result.posteriors[:x]
+logevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence
px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :teal)
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :violet)
+
+plot(px)

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:

logevidence
1-element Vector{Float64}:
+ -1882.2434870099778

We may be also interested in performance of our resulting Belief Propagation algorithm:

@benchmark inference(
+    model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), 
+    data = (y = $y,)
+)
BenchmarkTools.Trial: 145 samples with 1 evaluation.
+ Range (min … max):  25.289 ms … 105.283 ms  ┊ GC (min … max): 0.00% … 17.2
+5%
+ Time  (median):     30.949 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   34.474 ms ±   9.607 ms  ┊ GC (mean ± σ):  8.58% ± 12.6
+6%
+
+      ▆▅█▁                                                      
+  ▃▁▄▇████▇▃▃▁▃▃▃▁▃▃▄▃▄▃▄▃▄▄▃▃▃▃▃▁▁▃▁▁▃▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▃ ▃
+  25.3 ms         Histogram: frequency by time         75.6 ms <
+
+ Memory estimate: 9.65 MiB, allocs estimate: 223850.

System Identification Problem

In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:

using RxInfer, Distributions, StableRNGs, Plots
function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)
+
+    rng = StableRNG(seed)
+
+    real_x = Vector{Float64}(undef, n)
+    real_w = Vector{Float64}(undef, n)
+    real_y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))
+        real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))
+        real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))
+
+        x_i_min = real_x[i]
+        w_i_min = real_w[i]
+    end
+    
+    return real_x, real_w, real_y
+end
generate_data (generic function with 2 methods)

The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.

Combination 1: y = x + w

In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:

n = 250
+real_x, real_w, real_y = generate_data(+, n);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, real_x, label = "x")
+pl = plot!(pl, real_w, label = "w")
+
+pr = plot(title = "Combined y = x + w")
+pr = scatter!(pr, real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:

@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x = randomvar(n)
+    w = randomvar(n)
+    s = randomvar(n)
+    y = datavar(Float64, n)
+    
+    x_i_min = x0
+    w_i_min = w0
+    
+    for i in 1:n
+        x[i] ~ Normal(mean = x_i_min, precision = τ_x)
+        w[i] ~ Normal(mean = w_i_min, precision = τ_w)
+        s[i] ~ f(x[i], w[i])
+        y[i] ~ Normal(mean = s[i], precision = τ_y)
+        
+        x_i_min = x[i]
+        w_i_min = w[i]
+    end
+    
+end

RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:

constraints = @constraints begin 
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y
+)
+Options:
+  warn = true

The next step is to assign priors, initialise needed messages and marginals and call the inference function:

m_x_0, τ_x_0 = -20.0, 1.0
+m_w_0, τ_w_0 = 20.0, 1.0
+
+# We set relatively strong priors for random walk noise components
+# and sort of vague prior for the noise of the observations
+a_x, b_x = 0.01, 0.01var(real_x)
+a_w, b_w = 0.01, 0.01var(real_w)
+a_y, b_y = 1.0, 1.0
+
+# We set relatively strong priors for messages
+xinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))
+winit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))
+
+imessages = (x = xinit, w = winit)
+imarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))
+
+result = inference(
+    model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),
+    data  = (y = real_y,), 
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = imessages, 
+    initmarginals = imarginals, 
+    iterations = 50
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)

Let's examine our inference results:

τ_x_marginals = result.posteriors[:τ_x]
+τ_w_marginals = result.posteriors[:τ_w]
+τ_y_marginals = result.posteriors[:τ_y]
+
+smarginals = result.posteriors[:s]
+xmarginals = result.posteriors[:x]
+wmarginals = result.posteriors[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.

Combination 2: y = min(x, w)

In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:

# Smoothed version of `min` without zero-ed derivatives
+function smooth_min(x, y)    
+    if x < y
+        return x + 1e-4 * y
+    else
+        return y + 1e-4 * x
+    end
+end
smooth_min (generic function with 1 method)

RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:

min_meta = @meta begin 
+    # In this example we are going to use a simple `Linearization` method
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true
n = 200
+min_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, min_real_x, label = "x")
+pl = plot!(pl, min_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, min_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

min_m_x_0, min_τ_x_0 = -1.0, 1.0
+min_m_w_0, min_τ_w_0 = 1.0, 1.0
+
+min_a_x, min_b_x = 1.0, 1.0
+min_a_w, min_b_w = 1.0, 1.0
+min_a_y, min_b_y = 1.0, 1.0
+
+min_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))
+min_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))
+
+min_result = inference(
+    model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),
+    data  = (y = min_real_y,), 
+    meta = min_meta,
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = min_imessages, 
+    initmarginals = min_imarginals, 
+    iterations = 100
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)
min_τ_x_marginals = min_result.posteriors[:τ_x]
+min_τ_w_marginals = min_result.posteriors[:τ_w]
+min_τ_y_marginals = min_result.posteriors[:τ_y]
+
+min_smarginals = min_result.posteriors[:s]
+min_xmarginals = min_result.posteriors[:x]
+min_wmarginals = min_result.posteriors[:w]
+
+px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, min_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, min_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, min_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks).

Online (filtering) identification: y = min(x, w)

Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:

@model function rx_identification(f)
+    
+    # We are going to continuosly update our priors
+    # based on new posteriors
+    m_x_0 = datavar(Float64) 
+    τ_x_0 = datavar(Float64)
+    m_w_0 = datavar(Float64) 
+    τ_w_0 = datavar(Float64)
+    a_x   = datavar(Float64) 
+    b_x   = datavar(Float64)
+    a_y   = datavar(Float64) 
+    b_y   = datavar(Float64)
+    a_w   =  datavar(Float64) 
+    b_w   = datavar(Float64)
+    s     = randomvar()
+    y     = datavar(Float64)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x ~ Normal(mean = x0, precision = τ_x)
+    w ~ Normal(mean = w0, precision = τ_w)
+
+    s ~ f(x, w)
+    y ~ Normal(mean = s, precision = τ_y)
+    
+end

We impose structured mean-field assumption for this model as well:

rx_constraints = @constraints begin 
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ
+_y)
+Options:
+  warn = true

Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:

autoupdates = @autoupdates begin 
+    m_x_0, τ_x_0 = mean_precision(q(x))
+    m_w_0, τ_w_0 = mean_precision(q(w))
+    a_x = shape(q(τ_x)) 
+    b_x = rate(q(τ_x))
+    a_y = shape(q(τ_y))
+    b_y = rate(q(τ_y))
+    a_w = shape(q(τ_w)) 
+    b_w = rate(q(τ_w))
+end
(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_
+x = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_
+y)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))

As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):

rx_meta = @meta begin 
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true

Next step is to generate our dataset and to run the actual inference procedure! For that we use the rxinference function, which has a similar API as the inference function:

n = 300
+rx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, rx_real_x, label = "x")
+pl = plot!(pl, rx_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

engine = rxinference(
+    model         = rx_identification(smooth_min),
+    constraints   = rx_constraints,
+    data          = (y = rx_real_y,),
+    autoupdates   = autoupdates,
+    meta          = rx_meta,
+    returnvars    = (:x, :w, :τ_x, :τ_w, :τ_y, :s),
+    keephistory   = 1000,
+    historyvars   =  KeepLast(),
+    initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),
+    iterations    = 10,
+    free_energy = true, 
+    free_energy_diagnostics = nothing,
+    autostart     = true,
+)
RxInferenceEngine:
+  Posteriors stream    | enabled for (w, s, τ_x, τ_w, τ_y, x)
+  Free Energy stream   | enabled
+  Posteriors history   | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)
+  Free Energy history  | available
+  Enabled events       | [  ]
rx_smarginals = engine.history[:s]
+rx_xmarginals = engine.history[:x]
+rx_wmarginals = engine.history[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, rx_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = "Estimated X")
+
+px1 = plot!(px1, rx_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = "Estimated W")
+
+px2 = scatter!(px2, rx_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the "disabled" state, does not infer anything and simply increases its variance (which is expected for the random walk).

Handling Missing Data

An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.

Let us assume that the following model generates the data

\[\begin{aligned} + {x}_t &\sim \mathcal{N}\left({x}_{t-1}, 1.0\right) \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, P \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation $\hat{y}_t \in \mathrm{R}$ we sometimes will catch missing observations.

using RxInfer, Plots
@model function smoothing(n, x0)
+    
+    P ~ Gamma(shape = 0.001, scale = 0.001)
+    x_prior ~ Normal(mean = mean(x0), var = var(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ Normal(mean = x_prev, precision = 1.0)
+        y[i] ~ Normal(mean = x[i], precision = P)
+        
+        x_prev = x[i]
+    end
+
+end

We need to manually extend the set of rules to support ::Missing values

P = 1.0
+n = 250
+
+real_signal     = map(e -> sin(0.05 * e), collect(1:n))
+noisy_data      = real_signal + rand(Normal(0.0, sqrt(P)), n);
+missing_indices = 100:125
+missing_data    = similar(noisy_data, Union{Float64, Missing}, )
+
+copyto!(missing_data, noisy_data)
+
+for index in missing_indices
+    missing_data[index] = missing
+end
constraints = @constraints begin
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+Options:
+  warn = true
x0_prior = NormalMeanVariance(0.0, 1000.0)
+
+result = inference(
+    model = smoothing(n, x0_prior), 
+    data  = (y = missing_data,), 
+    constraints = constraints,
+    initmarginals = (P = Gamma(0.001, 0.001), ),
+    returnvars = (x = KeepLast(),),
+    iterations = 20
+);
plot(real_signal, label = "Noisy signal", legend = :bottomright)
+scatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = "Missing region")
+plot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = "Estimated hidden state")

diff --git a/v2.15.0/examples/basic_examples/Predicting Bike Rental Demand/index.html b/v2.15.0/examples/basic_examples/Predicting Bike Rental Demand/index.html new file mode 100644 index 000000000..847c17a86 --- /dev/null +++ b/v2.15.0/examples/basic_examples/Predicting Bike Rental Demand/index.html @@ -0,0 +1,193 @@ + +Predicting Bike Rental Demand · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Predicting Bike Rental Demand

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer

Preamble: Enabling Predictions

RxInfer.jl facilitates predictions in two primary ways.

  1. Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.
  2. Explicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.

Example

Consider the following model:

@model function example_model()
+    y = datavar(Float64) where {allow_missing = true}
+
+    h ~ NormalMeanPrecision(0, 1.0)
+    x ~ NormalMeanPrecision(h, 1.0)
+    y ~ NormalMeanPrecision(x, 10.0)
+end
# Implicit Prediction
+result = inference(model = example_model(), data = (y = missing,))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)
# Explicit Prediction
+result = inference(model = example_model(), predictvars = (y = KeepLast(),))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)

Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.

using CSV, DataFrames, Plots

Objective

This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.

Dataset Source

Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.

# Load the data
+df = CSV.read("../data/bike_count/modified_bicycle.csv", DataFrame)
+df[1:10, :]
10×6 DataFrame
+ Row │ datetime            temp     atemp    humidity  windspeed  count
+     │ String31            Float64  Float64  Float64   Float64    Int64
+─────┼──────────────────────────────────────────────────────────────────
+   1 │ 2011-01-01 0:00:00     9.84   14.395      81.0     0.0        16
+   2 │ 2011-01-01 1:00:00     9.02   13.635      80.0     0.0        40
+   3 │ 2011-01-01 2:00:00     9.02   13.635      80.0     0.0        32
+   4 │ 2011-01-01 3:00:00     9.84   14.395      75.0     0.0        13
+   5 │ 2011-01-01 4:00:00     9.84   14.395      75.0     0.0         1
+   6 │ 2011-01-01 5:00:00     9.84   12.88       75.0     6.0032      1
+   7 │ 2011-01-01 6:00:00     9.02   13.635      80.0     0.0         2
+   8 │ 2011-01-01 7:00:00     8.2    12.88       86.0     0.0         3
+   9 │ 2011-01-01 8:00:00     9.84   14.395      75.0     0.0         8
+  10 │ 2011-01-01 9:00:00    13.12   17.425      76.0     0.0        14
# we reserve few samples for prediction
+n_future = 24
+
+X = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]
+y = Union{Float64, Missing}[df[:, "count"]...][1:end-n_future]
+
+state_dim = length(X[1]); # dimensionality of feature space

Generative Model with Priors

We present a generative model that delineates the latent dynamics of feature evolution, represented by $\mathbf{h}_t$, and their link to the bike rental counts, $\mathbf{y}_t$.

Equations and Priors

  1. Feature Dynamics with Prior:

    • Prior: $\mathbf{a} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Dynamics: $\mathbf{h}_t \sim \mathcal{N}(\mathbf{A h}_{t-1}, \mathbf{Q})$

    • \[\mathbf{A}\]

      is the transition matrix, reshaped from the prior vector $\mathbf{a}$, and $\mathbf{Q}$ represents process noise.

  2. Noisy Observations:

    • \[\mathbf{x}_t \sim \mathcal{N}(\mathbf{h}_t, \mathbf{P})\]

    • Represents the observed noisy state of the features.

  3. Count Prediction with Prior:

    • Prior: $\boldsymbol{\theta} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Prediction: $y_t \sim \mathcal{N}(\text{softplus}(\boldsymbol{\theta}^\top\mathbf{h}_t), \sigma^2)$
    • Models the bike rental count as influenced by a non-linear transformation of the hidden state.

Interpretation

  • This framework aims to simultaneously infer the transition matrix $\mathbf{A}$ and the regression parameters $\boldsymbol{\theta}$, providing a comprehensive view of the feature space dynamics and the count prediction.
  • By employing Gaussian priors on both $\mathbf{a}$ and $\boldsymbol{\theta}$, we incorporate beliefs about their distributions.
  • The inference process aims to discover these underlying dynamics, enabling predictions of both features $\mathbf{x}_t$ and counts $y_t$.
# We augument the dataset with missing entries for 24 hours ahead
+append!(X, repeat([missing], n_future))
+append!(y, repeat([missing], n_future));
# Function to perform the state transition in the model.
+# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.
+function transition(a, x)
+    nm, n = length(a), length(x)
+    m = nm ÷ n  # Calculate the number of rows for reshaping 'a' into a matrix
+    A = reshape(a, (m, n))  
+    return A * x
+end
transition (generic function with 1 method)
# The dotsoftplus function combines a dot product and softplus transformation.
+# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,
+# especially if the data suggests other forms of relationships or distributions.
+function dotsoftplus(a, x)
+    log(1 + exp(dot(a, x)))
+end
dotsoftplus (generic function with 1 method)
# model definction
+@model function bicycle_ssm(n, h0, θ0, a0, Q, P)
+
+    # `h` is a sequence of hidden states
+    h = randomvar(n)
+
+    # `x` is a sequence of observed states (features)
+    x = datavar(Vector{Float64}, n) where {allow_missing = true}
+    # `y` is a sequence of "count" bicycles
+    y = datavar(Float64, n) where {allow_missing = true}
+
+    a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))
+
+    θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))
+
+    h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))
+    h_prev = h_prior
+    
+    for i in 1:n
+        
+        h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)
+        
+        x[i] ~ MvNormal(μ=h[i], Σ=P)
+        
+        y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)
+        
+        h_prev = h[i]
+    end
+
+end
# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.
+# However, alternative methods like Unscented or CVI approximations can also be considered.
+transition_meta = @meta begin 
+    transition() -> Linearization()
+    dotsoftplus() -> Linearization()
+end
Meta specification:
+  transition() -> Linearization()
+  dotsoftplus() -> Linearization()
+Options:
+  warn = true
# We define rather uninformative priors 
+prior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))
+prior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))
+prior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))
MvNormalMeanCovariance(
+μ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0
+.0, 0.0]
+Σ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … 
+0.0 1.0]
+)
# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages
+imessages = ( h = prior_h, a = prior_a, θ = prior_θ,)
+
+bicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))
+
+result = inference(
+    model = bicycle_model,
+    data  = (y = y, x=X), 
+    options = (limit_stack_depth = 500, ), 
+    returnvars = KeepLast(),
+    initmessages = imessages,
+    meta = transition_meta,
+    iterations = 20,
+    showprogress=true,
+)
Inference results:
+  Posteriors       | available for (a, h, h_prior, θ)
+  Predictions      | available for (y, x)
# For a sake of this example, we extract only predictions
+mean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])
+mean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])
+
+mean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)
+mean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)
+mean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)
+mean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);
slice = (300, length(y))
+data = df[:, "count"][length(y)-n_future:length(y)]
+
+p = scatter(y, 
+            color=:darkblue, 
+            markerstrokewidth=0,
+            label="Observed Count", 
+            alpha=0.6)
+
+# Plotting the mean prediction with variance ribbon
+plot!(mean_y, ribbon=sqrt.(cov_y), 
+      color=:orange, 
+      fillalpha=0.3,
+      label="Predicted Mean ± Std Dev")
+
+# Adding a vertical line to indicate the start of the future prediction
+vline!([length(y)-n_future], 
+       label="Prediction Start", 
+       linestyle=:dash, 
+       linecolor=:green)
+
+# Future (unobserved) data
+plot!(length(y)-n_future:length(y), data, label="Future Count")
+
+# Adjusting the limits
+xlims!(slice)
+
+# Enhancing the plot with titles and labels
+title!("Bike Rental Demand Prediction")
+xlabel!("Time")
+ylabel!("Bike Count")
+
+# Adjust the legend
+legend=:topright
+
+# Show the final plot
+display(p)

using Plots
+
+# Define a color palette
+palette = cgrad(:viridis)
+
+# Plot the hidden states with observations
+p1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label="Hidden State 1", legend=:topleft)
+plot!(df[!, :temp], color=:grey, label="Temperature")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Temperature vs Hidden State 1")
+
+p2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label="Hidden State 2", legend=:topleft)
+plot!(df[!, :atemp], color=:grey, label="Feels-Like Temp")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="")
+xlabel!("Time")
+ylabel!("Value")
+title!("Feels-Like Temp vs Hidden State 2")
+
+p3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label="Hidden State 3", legend=:topleft)
+plot!(df[!, :humidity], color=:grey, label="Humidity")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Humidity vs Hidden State 3")
+
+p4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label="Hidden State 4", legend=:topleft)
+plot!(df[!, :windspeed], color=:grey, label="Windspeed")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Windspeed vs Hidden State 4")
+
+for p in [p1, p2, p3, p4]
+    xlims!(p, first(slice), last(slice))
+end
+
+plot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))

Conclusion

While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.

The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.

diff --git a/v2.15.0/examples/basic_examples/overview/index.html b/v2.15.0/examples/basic_examples/overview/index.html new file mode 100644 index 000000000..04f417d0a --- /dev/null +++ b/v2.15.0/examples/basic_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Basic examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Basic examples contain "Hello World!" of Bayesian inference in RxInfer.

  • Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.
  • Bayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.
  • Kalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations
  • Predicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.
  • How to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.
diff --git a/v2.15.0/examples/overview/index.html b/v2.15.0/examples/overview/index.html new file mode 100644 index 000000000..5ac35f6b1 --- /dev/null +++ b/v2.15.0/examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Examples overview

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

  • Basic examples: Basic examples contain "Hello World!" of Bayesian inference in RxInfer.
  • Advanced examples: Advanced examples contain more complex inference problems.
  • Problem specific: Problem specific examples contain specialized models and inference for various domains.
diff --git a/v2.15.0/examples/problem_specific/Autoregressive Models/index.html b/v2.15.0/examples/problem_specific/Autoregressive Models/index.html new file mode 100644 index 000000000..715486b24 --- /dev/null +++ b/v2.15.0/examples/problem_specific/Autoregressive Models/index.html @@ -0,0 +1,311 @@ + +Autoregressive Models · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Autoregressive Models

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:

\[\begin{aligned} +p(\gamma) &= \mathrm{Gamma}(\gamma|a, b),\\ +p(\mathbf{\theta}) &= \mathcal{N}(\mathbf{\theta}|\mathbf{\mu}, \Sigma),\\ +p(x_t|\mathbf{x}_{t-1:t-k}) &= \mathcal{N}(x_t|\mathbf{\theta}^{T}\mathbf{x}_{t-1:t-k}, \gamma^{-1}),\\ +p(y_t|x_t) &= \mathcal{N}(y_t|x_t, \tau^{-1}), +\end{aligned}\]

where $x_t$ is a current state of our system, $\mathbf{x}_{t-1:t-k}$ is a sequence of $k$ previous states, $k$ is an order of autoregression process, $\mathbf{\theta}$ is a vector of transition coefficients, $\gamma$ is a precision of state transition process, $y_k$ is a noisy observation of $x_k$ with precision $\tau$.

For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.

We start with importing all needed packages:

using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters

Let's generate some synthetic dataset, we use a predefined sets of coeffcients for $k$ = 1, 3 and 5 respectively:

# The following coefficients correspond to stable poles
+coefs_ar_1 = [-0.27002517200218096]
+coefs_ar_2 = [0.4511170798064709, -0.05740081602446657]
+coefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];
function generate_ar_data(rng, n, θ, γ, τ)
+    order        = length(θ)
+    states       = Vector{Vector{Float64}}(undef, n + 3order)
+    observations = Vector{Float64}(undef, n + 3order)
+    
+    γ_std = sqrt(inv(γ))
+    τ_std = sqrt(inv(τ))
+    
+    states[1] = randn(rng, order)
+    
+    for i in 2:(n + 3order)
+        states[i]       = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])
+        observations[i] = rand(rng, Normal(states[i][1], τ_std))
+    end
+    
+    return states[1+3order:end], observations[1+3order:end]
+end
generate_ar_data (generic function with 1 method)
# Seed for reproducibility
+seed = 123
+rng  = MersenneTwister(seed)
+
+# Number of observations in synthetic dataset
+n = 500
+
+# AR process parameters
+real_γ = 1.0
+real_τ = 0.5
+real_θ = coefs_ar_5
+
+states, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);

Let's plot our synthetic dataset:

plot(first.(states), label = "Hidden states")
+scatter!(observations, label = "Observations")

Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order $k$ > 1 and for Univariate AR (reduces to simple State-Space-Model) with order $k$ = 1.

@model function lar_model(T::Type, n, order, c, τ)
+    
+     
+    # We create a sequence of random variables for hidden states
+    x = randomvar(n)
+    # As well a sequence of observartions
+    y = datavar(Float64, n)
+    
+    ct = constvar(c)
+    # We assume observation noise to be known
+    cτ = constvar(τ)
+    
+    γ  = randomvar()
+    θ  = randomvar()
+    x0 = randomvar()
+    
+    # Prior for first state
+    if T === Multivariate
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+        x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+    else
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ Normal(μ = 0.0, γ = 1.0)
+        x0 ~ Normal(μ = 0.0, γ = 1.0)
+    end
+    
+    x_prev = x0
+    
+    for i in 1:n
+        
+        x[i] ~ AR(x_prev, θ, γ) 
+        
+        if T === Multivariate
+            y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)
+        else
+            y[i] ~ Normal(μ = ct * x[i], γ = cτ)
+        end
+        
+        x_prev = x[i]
+    end
+
+end
@constraints function ar_constraints() 
+    q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)
+end
ar_constraints (generic function with 1 method)
@meta function ar_meta(artype, order, stype)
+    AR() -> ARMeta(artype, order, stype)
+end
ar_meta (generic function with 1 method)
morder  = 5
+martype = Multivariate
+mc      = ReactiveMP.ar_unit(martype, morder)
+mconstraints = ar_constraints()
+mmeta        = ar_meta(martype, morder, ARsafe())
+
+moptions = (limit_stack_depth = 100, )
+
+mmodel         = lar_model(martype, length(observations), morder, mc, real_τ)
+mdata          = (y = observations, )
+minitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))
+mreturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+# First execution is slow due to Julia's initial compilation 
+# Subsequent runs will be faster (benchmarks are below)
+mresult = inference(
+    model = mmodel, 
+    data  = mdata,
+    constraints   = mconstraints,
+    meta          = mmeta,
+    options       = moptions,
+    initmarginals = minitmarginals,
+    returnvars    = mreturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
@unpack x, γ, θ = mresult.posteriors
Dict{Symbol, Vector} with 3 entries:
+  :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)
+, Ga…
+  :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…
+  :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…

We will use different initial marginals depending on type of our AR process

p1 = plot(first.(states), label="Hidden state")
+p1 = scatter!(p1, observations, label="Observations")
+p1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label="Inferred states", legend = :bottomright)
+
+p2 = plot(mean.(γ), ribbon = std.(γ), label = "Inferred transition precision", legend = :topright)
+p2 = plot!([ real_γ ], seriestype = :hline, label = "Real transition precision")
+
+p3 = plot(mresult.free_energy, label = "Bethe Free Energy")
+
+plot(p1, p2, p3, layout = @layout([ a; b c ]))

Let's also plot a subrange of our results:

subrange = div(n,5):(div(n, 5) + div(n, 5))
+
+plot(subrange, first.(states)[subrange], label="Hidden state")
+scatter!(subrange, observations[subrange], label="Observations")
+plot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label="Inferred states", legend = :bottomright)

It is also interesting to see where our AR coefficients converge to:

let
+    pθ = plot()
+
+    θms = mean.(θ)
+    θvs = var.(θ)
+    
+    l = length(θms)
+
+    edim(e) = (a) -> map(r -> r[e], a)
+
+    for i in 1:length(first(θms))
+        pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = "Estimated θ[$i]")
+    end
+    
+    for i in 1:length(real_θ)
+        pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = "Real θ[$i]")
+    end
+    
+    plot(pθ, legend = :outertopright, size = (800, 300))
+end

println("$(length(real_θ))-order AR inference Bethe Free Energy: ", last(mresult.free_energy))
5-order AR inference Bethe Free Energy: 1024.0766194723828

We can also run a 1-order AR inference on 5-order AR data:

uorder  = 1
+uartype = Univariate
+uc      = ReactiveMP.ar_unit(uartype, uorder)
+uconstraints = ar_constraints()
+umeta        = ar_meta(uartype, uorder, ARsafe())
+
+uoptions = (limit_stack_depth = 100, )
+
+umodel         = lar_model(uartype, length(observations), uorder, uc, real_τ)
+udata          = (y = observations, )
+uinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))
+ureturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+uresult = inference(
+    model = umodel, 
+    data  = udata,
+    meta  = umeta,
+    constraints   = uconstraints,
+    initmarginals = uinitmarginals,
+    returnvars    = ureturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
println("1-order AR inference Bethe Free Energy: ", last(uresult.free_energy))
1-order AR inference Bethe Free Energy: 1025.8792949319954
if uresult.free_energy[end] > mresult.free_energy[end]
+    println("We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.")
+else
+    error("AR-1 performs better than AR-5...") 
+end
We can see that, according to final Bethe Free Energy value, in this exampl
+e 5-order AR process can describe data better than 1-order AR.

Autoregressive Moving Average Model

Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:

\[\begin{aligned} +e_t \sim \mathcal{N}(0, \gamma^{-1}) \quad +\theta &\sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \quad +\eta \sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \\ +\mathbf{h}_0 &\sim \mathcal{MN}\left(\begin{bmatrix} +e_{-1} \\ +e_{-2} +\end{bmatrix}, \mathbf{I}\right) \\ +\mathbf{h}_t &= \mathbf{S}\mathbf{h}_{t-1} + \mathbf{c} e_{t-1} \\ +\mathbf{x}_t &= \boldsymbol{\theta}^\top\mathbf{x}_{t-1} + \boldsymbol{\eta}^\top\mathbf{h}_{t} + e_t +\end{aligned}\]

where shift matrix $\mathbf{S}$ is

\[\begin{aligned} +\mathbf{S} = \begin{pmatrix} +0 & 0 \\ +1 & 0 +\end{pmatrix} +\end{aligned}\]

and unit vector $\mathbf{c}$:

\[\begin{aligned} +\mathbf{c}=[1, 0] +\end{aligned}\]

when MA order is $2$

In this way, $\mathbf{h}_t$ containing errors $e_t$ can be viewed as hidden state.

In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., $\boldsymbol{\eta}^\top\mathbf{h}_{t}$, (2) induced by errors $e_t$ that prevents analytical update of precision parameter $\gamma$ (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.

# Load packages
+using RxInfer, LinearAlgebra, CSV, DataFrames, Plots
# Define shift function
+function shift(dim)
+    S = Matrix{Float64}(I, dim, dim)
+    for i in dim:-1:2
+           S[i,:] = S[i-1, :]
+    end
+    S[1, :] = zeros(dim)
+    return S
+end
shift (generic function with 1 method)
@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)
+        
+    c = zeros(p); c[1] = 1.0; # AR
+    b = zeros(q); b[1] = 1.0; # MA
+    S = shift(q); # MA
+    
+    # initialize variables
+    h  = randomvar(n-1)
+    e  = randomvar(n)
+    z  = randomvar(n)
+    
+    x  = datavar(Float64, n) where { allow_missing = true }
+    
+    # priors
+    γ  ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))
+    η  ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))
+    θ  ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))
+    τ  ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))
+    
+    # initial
+    h_0  ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))
+    z[1] ~ AR(h_0, η, τ)
+    e[1] ~ Normal(mean = 0.0, precision = γ)
+
+    x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]
+    
+    h_prev = h_0
+    for t in 1:n-1
+        
+        e[t+1] ~ Normal(mean = 0.0, precision = γ)
+        h[t]   ~ S*h_prev + b*e[t]
+        z[t+1] ~ AR(h[t], η, τ)
+        x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]
+        h_prev = h[t]
+    end
+end

To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle

x_df = CSV.read("../data/arma/aal_stock.csv", DataFrame)
1259×7 DataFrame
+  Row │ date        open     high     low      close    volume    Name
+      │ Date        Float64  Float64  Float64  Float64  Int64     String3
+──────┼───────────────────────────────────────────────────────────────────
+    1 │ 2013-02-08    15.07    15.12   14.63     14.75   8407500  AAL
+    2 │ 2013-02-11    14.89    15.01   14.26     14.46   8882000  AAL
+    3 │ 2013-02-12    14.45    14.51   14.1      14.27   8126000  AAL
+    4 │ 2013-02-13    14.3     14.94   14.25     14.66  10259500  AAL
+    5 │ 2013-02-14    14.94    14.96   13.16     13.99  31879900  AAL
+    6 │ 2013-02-15    13.93    14.61   13.93     14.5   15628000  AAL
+    7 │ 2013-02-19    14.33    14.56   14.08     14.26  11354400  AAL
+    8 │ 2013-02-20    14.17    14.26   13.15     13.33  14725200  AAL
+  ⋮   │     ⋮          ⋮        ⋮        ⋮        ⋮        ⋮         ⋮
+ 1253 │ 2018-01-30    52.45    53.05   52.36     52.59   4741808  AAL
+ 1254 │ 2018-01-31    53.08    54.71   53.0      54.32   5962937  AAL
+ 1255 │ 2018-02-01    54.0     54.64   53.59     53.88   3623078  AAL
+ 1256 │ 2018-02-02    53.49    53.99   52.03     52.1    5109361  AAL
+ 1257 │ 2018-02-05    51.99    52.39   49.75     49.76   6878284  AAL
+ 1258 │ 2018-02-06    49.32    51.5    48.79     51.18   6782480  AAL
+ 1259 │ 2018-02-07    50.91    51.98   50.89     51.4    4845831  AAL
+                                                         1244 rows omitted
# we will use "close" column
+x_data = filter(!ismissing, x_df[:, 5]);
# Plot data
+plot(x_data, xlabel="day", ylabel="price", label=false)

p_order = 10 # AR
+q_order = 4 # MA
4
# Training set
+train_size = 1000
+x_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]
+x_train = Float64.(x_data[p_order+1:end])[1:train_size];
# Test set
+x_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]
+x_test = Float64.(x_data[p_order+1:end])[train_size+1:end];

Inference

# Constraints are needed for performing VMP
+arma_constraints = @constraints begin
+    q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)
+end;
# This cell defines prior knowledge for model parameters
+h_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+γ_prior = GammaShapeRate(1e4, 1.0)
+τ_prior = GammaShapeRate(1e2, 1.0)
+η_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+θ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));
# Model's graph has structural loops, hence, it requires pre-initialisation
+arma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);
+arma_imessages  = (h_0 = h_prior, h = h_prior);
+arma_meta       = ar_meta(Multivariate, q_order, ARsafe());
result = inference(
+    model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), 
+    data  = (x = x_train, ),
+    initmarginals = arma_imarginals,
+    initmessages  = arma_imessages,
+    constraints   = arma_constraints,
+    meta          = arma_meta,
+    iterations    = 50,
+    options       = (limit_stack_depth = 400, ),
+);
plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = "eₜ")

# extract posteriors
+h_posterior = result.posteriors[:h][end][end]
+γ_posterior = result.posteriors[:γ][end]
+τ_posterior = result.posteriors[:τ][end]
+η_posterior = result.posteriors[:η][end]
+θ_posterior = result.posteriors[:θ][end];

Prediction

Here we are going to use our inference results in order to predict the dataset itself

# The prediction function is aimed at approximating the predictive posterior distribution
+# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)
+function prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)
+    h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))
+    ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))
+    c = zeros(p); c[1] = 1.0
+    b = zeros(q); b[1] = 1.0
+    ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)
+    θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))
+    ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)
+    e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))
+    ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out)  
+    @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out)  
+end
prediction (generic function with 1 method)
predictions = []
+for x_prev in x_prev_test
+    push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))
+    # after every new prediction we can actually "retrain" the model to use the power of Bayesian approach
+    # we will skip this part at this notebook
+end
plot(x_test, label="test data", legend=:topleft)
+plot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label="predicted", xlabel="day", ylabel="price")

diff --git a/v2.15.0/examples/problem_specific/Gamma Mixture/index.html b/v2.15.0/examples/problem_specific/Gamma Mixture/index.html new file mode 100644 index 000000000..dfc814101 --- /dev/null +++ b/v2.15.0/examples/problem_specific/Gamma Mixture/index.html @@ -0,0 +1,129 @@ + +Gamma Mixture Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gamma Mixture Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.

Load packages

using RxInfer, Random, StatsPlots
# create custom structure for model parameters for simplicity
+struct GammaMixtureModelParameters
+    nmixtures   # number of mixtures
+    priors_as   # tuple of priors for variable a
+    priors_bs   # tuple of priors for variable b
+    prior_s     # prior of variable s
+end

Model specification

@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)
+
+    # fetch information from struct
+    nmixtures = parameters.nmixtures
+    priors_as = parameters.priors_as
+    priors_bs = parameters.priors_bs
+    prior_s   = parameters.prior_s
+
+    # set prior on global selection variable
+    s ~ Dirichlet(probvec(prior_s))
+
+    # allocate vectors of random variables
+    as = randomvar(nmixtures)
+    bs = randomvar(nmixtures)
+
+    # set priors on variables of mixtures
+    for i in 1:nmixtures
+        as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))
+        bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))
+    end
+
+    # introduce random variables for local selection variables and data
+    z = randomvar(nobservations)
+    y = datavar(Float64, nobservations)
+
+    # convert vector to tuples for proper functioning of GammaMixture node
+    tas = tuple(as...)
+    tbs = tuple(bs...)
+
+    # specify local selection variable and data generating process
+    for i in 1:nobservations
+        z[i] ~ Categorical(s)
+        y[i] ~ GammaMixture(z[i], tas, tbs)
+    end
+    
+end
constraints = @constraints begin 
+
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+
+    q(as) = q(as[begin])..q(as[end])
+    q(bs) = q(bs[begin])..q(bs[end])
+    
+    q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])
+end
Constraints:
+  marginals form:
+    q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+    q(as) = q(as[(begin)..(end)])
+    q(bs) = q(bs[(begin)..(end)])
+Options:
+  warn = true
# specify seed and number of data points
+rng = MersenneTwister(43)
+n_samples = 2500
+
+# specify parameters of mixture model that generates the data
+# Note that mixture components have exactly the same means
+mixtures  = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]
+nmixtures = length(mixtures)
+mixing    = rand(rng, nmixtures)
+mixing    = mixing ./ sum(mixing)
+mixture   = MixtureModel(mixtures, mixing)
+
+# generate data set
+dataset = rand(rng, mixture, n_samples);
# specify priors of probabilistic model
+# NOTE: As the means of the mixtures "collide", we specify informative prior for selector variable
+nmixtures = 2
+gpriors = GammaMixtureModelParameters(
+    nmixtures,                                                    # number of mixtures
+    [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ],                         # priors on variables a
+    [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ],      # priors on variables b
+    Dirichlet(1e3*mixing)                                         # prior on variable s
+)
+
+gmodel         = gamma_mixture_model(length(dataset), gpriors)
+gdata          = (y = dataset, )
+ginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))
+greturnvars    = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())
+
+goptions = (
+     
+    default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently
+)
+
+gresult = inference(
+    model         = gmodel, 
+    data          = gdata,
+    constraints   = constraints,
+    options       = (limit_stack_depth = 100,),
+    initmarginals = ginitmarginals,
+    returnvars    = greturnvars,
+    free_energy   = true,
+    iterations    = 250, 
+    showprogress  = true
+);
# extract inferred parameters
+_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])
+_dists   = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))
+_mixing = mean(gresult.posteriors[:s])
+
+# create model from inferred parameters
+_mixture   = MixtureModel(_dists, _mixing);
# report on outcome of inference
+println("Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))")
+println("Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))")
+println("========")
+println("Generated mixing: $(mixing)")
+println("Inferred mixing: $(_mixing)")
Generated means: 0.3333333333333333 and 0.33333333333333337
+Inferred means: 0.33821706692775155 and 0.33305593557019114
+========
+Generated mixing: [0.18923488676601088, 0.8107651132339891]
+Inferred mixing: [0.11397705903361303, 0.886022940966387]
# plot results
+p1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p1 = plot!(mixture, label=false, title="Generated mixtures", linewidth=3.0)
+
+p2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p2 = plot!(_mixture, label=false, title="Inferred mixtures", linewidth=3.0)
+
+# evaluate the convergence of the algorithm by monitoring the BFE
+p3 = plot(gresult.free_energy, label=false, xlabel="iterations", title="Bethe FE")
+
+plot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))

diff --git a/v2.15.0/examples/problem_specific/Gaussian Mixture/index.html b/v2.15.0/examples/problem_specific/Gaussian Mixture/index.html new file mode 100644 index 000000000..a232e9b7d --- /dev/null +++ b/v2.15.0/examples/problem_specific/Gaussian Mixture/index.html @@ -0,0 +1,170 @@ + +Gaussian Mixture · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gaussian Mixture

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.

Load packages

using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings

Univariate Gaussian Mixture Model

Consider the data set of length $N$ observed below.

function generate_univariate_data(nr_samples; rng = MersenneTwister(123))
+
+    # data generating parameters
+    class        = [1/3, 2/3]
+    mean1, mean2 = -10, 10
+    precision    = 1.777
+
+    # generate data
+    z = rand(rng, Categorical(class), nr_samples)
+    y = zeros(nr_samples)
+    for k in 1:nr_samples
+        y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))
+    end
+
+    return y
+
+end;
data_univariate = generate_univariate_data(100)
+histogram(data_univariate, bins=50, label="data", normed=true)
+xlims!(minimum(data_univariate), maximum(data_univariate))
+ylims!(0, Inf)
+ylabel!("relative occurrence [%]")
+xlabel!("y")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, w, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(w_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Beta}(s \mid \alpha_s, \beta_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \sigma_k^2) \\ p(w_{k}) &= \Gamma(w_k \mid \alpha_k, \beta_k) \\ + p(z_n \mid s) &= \mathrm{Ber}(z_n \mid s) \\ + p(y_n \mid m, w, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, w_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $w = \{ w_1, w_2, \ldots, w_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

Here we implement the following model with uninformative values for the hyperparameters as

@model function univariate_gaussian_mixture_model(nr_samples)
+    
+    s ~ Beta(1.0, 1.0)
+    
+    m1 ~ Normal(mean = -2.0, var = 1e3)
+    w1 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    m2 ~ Normal(mean = 2.0, var = 1e3)
+    w2 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    z = randomvar(nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    for n in 1:nr_samples
+        z[n] ~ Bernoulli(s)
+        y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, w \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, w \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(w_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Beta}(s \mid \hat{\alpha}_s, \hat{\beta}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\sigma}^2_k) \\ + q(w_k) &= \Gamma (w_k \mid \hat{\alpha}_k, \hat{\beta}_k) \\ + q(z_n) &= \mathrm{Ber}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

results_univariate = inference(
+    model = univariate_gaussian_mixture_model(length(data_univariate)), 
+    constraints = MeanField(),
+    data  = (y = data_univariate,), 
+    initmarginals = (
+        s  = vague(Beta), 
+        m1 = NormalMeanVariance(-2.0, 1e3), 
+        m2 = NormalMeanVariance(2.0, 1e3), 
+        w1 = vague(GammaShapeRate), 
+        w2 = vague(GammaShapeRate)
+    ), 
+    iterations  = 10, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m2, m1, s, w2, w1, z)
+  Free Energy:     | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.
+277, 135.277, 135.277, 135.277, 135.277]

Results

Below the inference results can be seen as a function of the iterations

mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L"posterior $m_1$")
+mp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L"posterior $m_2$")
+mp = plot!(mp, [ -10 ], seriestype = :hline, label = L"true $m_1$")
+mp = plot!(mp, [ 10 ], seriestype = :hline, label = L"true $m_2$")
+
+wp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L"posterior $w_1$", legend = :bottomright, ylim = (-1, 3))
+wp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L"posterior $w_2$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_1$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_2$")
+
+swp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L"posterior $s$")
+swp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L"true $s$")
+
+fep = plot(results_univariate.free_energy, label = "Free Energy", legend = :topright)
+
+plot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))
+xlabel!("iteration")

Multivariate Gaussian Mixture Model

The above example can also be extended to the multivariate case. Consider the data set below

function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))
+
+    L         = 50.0
+    nr_mixtures = 6
+
+    probvec = normalize!(ones(nr_mixtures), 1)
+
+    switch = Categorical(probvec)
+
+    gaussians = map(1:nr_mixtures) do index
+        angle      = 2π / nr_mixtures * (index - 1)
+        basis_v    = L * [ 1.0, 0.0 ]
+        R          = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]
+        mean       = R * basis_v 
+        covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))
+        return MvNormal(mean, covariance)
+    end
+
+    z = rand(rng, switch, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+
+    for n in 1:nr_samples
+        y[n] = rand(rng, gaussians[z[n]])
+    end
+
+    return y
+
+end;
data_multivariate = generate_multivariate_data(500)
+
+sdim(n) = (a) -> map(d -> d[n], a) # helper function
+scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)
+xlabel!(L"y_1")
+ylabel!(L"y_2")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, W, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(W_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Dir}(s \mid \alpha_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \Sigma_k) \\ p(W_{k}) &= \mathcal{W}(W_k \mid V_k, \nu_k) \\ + p(z_n \mid s) &= \mathrm{Cat}(z_n \mid s) \\ + p(y_n \mid m, W, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, W_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $W = \{ W_1, W_2, \ldots, W_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)
+    
+    z = randomvar(nr_samples)
+    m = randomvar(nr_mixtures)
+    w = randomvar(nr_mixtures)
+    y = datavar(Vector{Float64}, nr_samples)
+    
+    for k in 1:nr_mixtures        
+        m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])
+        w[k] ~ Wishart(3, 1e2*diagm(ones(2)))
+    end
+    
+    s ~ Dirichlet(ones(nr_mixtures))
+    
+    means = tuple(m...)
+    precs = tuple(w...)
+    
+    for n in 1:nr_samples
+        z[n] ~ Categorical(s) 
+        y[n] ~ NormalMixture(z[n], means, precs)
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, W \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, W \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(W_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Dir}(s \mid \hat{\alpha}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\Sigma}_k) \\ + q(w_k) &= \mathcal{W}(W_k \mid \hat{V}_k, \hat{\nu}_k) \\ + q(z_n) &= \mathrm{Cat}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

rng = MersenneTwister(121)
+m = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]
+results_multivariate = inference(
+    model = multivariate_gaussian_mixture_model(
+        6, 
+        length(data_multivariate), 
+        m,
+        [diagm(1e2 * ones(2)) for k in 1:6]
+    ), 
+    data  = (y = data_multivariate,), 
+    constraints   = MeanField(),
+    initmarginals = (
+        s = vague(Dirichlet, 6), 
+        m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], 
+        w = Wishart(3, diagm(1e2 * ones(2)))
+    ), 
+    iterations  = 50, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m, w, s, z)
+  Free Energy:     | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49  …  3894.49, 3894.49, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]

Results

Below the inference results can be seen

p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title="Data", xlims=(-75, 75), ylims=(-75, 75))
+p_result = plot(xlims = (-75, 75), ylims = (-75, 75), title="Inference result", legend=false, colorbar = false)
+for (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])
+    gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))
+    global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title="Inference result", legend=false, levels = 7, colorbar = false)
+end
+p_fe = plot(results_multivariate.free_energy, label = "Free Energy")
+
+plot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))

diff --git a/v2.15.0/examples/problem_specific/Hierarchical Gaussian Filter/index.html b/v2.15.0/examples/problem_specific/Hierarchical Gaussian Filter/index.html new file mode 100644 index 000000000..7546fd813 --- /dev/null +++ b/v2.15.0/examples/problem_specific/Hierarchical Gaussian Filter/index.html @@ -0,0 +1,145 @@ + +Hierarchical Gaussian Filter · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Hierarchical Gaussian Filter

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).

Simple HGF model can be defined as:

\[\begin{aligned} + x^{(j)}_k & \sim \, \mathcal{N}(x^{(j)}_{k - 1}, f_k(x^{(j - 1)}_k)) \\ + y_k & \sim \, \mathcal{N}(x^{(j)}_k, \tau_k) +\end{aligned}\]

where $j$ is an index of layer in hierarchy, $k$ is a time step and $f_k$ is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with $f_k = \exp(\kappa x + \omega)$ variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:

\[\begin{aligned} + z_k & \sim \, \mathcal{N}(z_{k - 1}, \mathcal{\tau_z}) \\ + x_k & \sim \, \mathcal{N}(x_{k - 1}, \exp(\kappa z_k + \omega)) \\ + y_k & \sim \, \mathcal{N}(x_k, \mathcal{\tau_y}) +\end{aligned}\]

In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.

For simplicity we will consider $\tau_z$, $\tau_y$, $\kappa$ and $\omega$ known and fixed, but there are no principled limitations to make them random variables too.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, k, w, zv, yv)
+    z_prev = 0.0
+    x_prev = 0.0
+
+    z = Vector{Float64}(undef, n)
+    v = Vector{Float64}(undef, n)
+    x = Vector{Float64}(undef, n)
+    y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        z[i] = rand(rng, Normal(z_prev, sqrt(zv)))
+        v[i] = exp(k * z[i] + w)
+        x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))
+        y[i] = rand(rng, Normal(x[i], sqrt(yv)))
+
+        z_prev = z[i]
+        x_prev = x[i]
+    end 
+    
+    return z, x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 42
+
+rng = MersenneTwister(seed)
+
+# Parameters of HGF process
+real_k = 1.0
+real_w = 0.0
+z_variance = abs2(0.2)
+y_variance = abs2(0.1)
+
+# Number of observations
+n = 300
+
+z, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.

let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    scatter!(px, 1:n, y, label = "y_i", color = :red, ms = 2, alpha = 0.2)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

To create a model we use the @model macro:

# We create a single-time step of corresponding state-space process to
+# perform online learning (filtering)
+@model function hgf(real_k, real_w, z_variance, y_variance)
+    
+    # Priors from previous time step for `z`
+    zt_min_mean = datavar(Float64)
+    zt_min_var  = datavar(Float64)
+    
+    # Priors from previous time step for `x`
+    xt_min_mean = datavar(Float64)
+    xt_min_var  = datavar(Float64)
+
+    zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)
+    xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)
+
+    # Higher layer is modelled as a random walk 
+    zt ~ NormalMeanVariance(zt_min, z_variance)
+    
+    # Lower layer is modelled with `GCV` node
+    gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)
+    
+    # Noisy observations 
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(xt, y_variance)
+    
+    return gcvnode
+end
+
+@constraints function hgfconstraints() 
+    q(xt, zt, xt_min) = q(xt, xt_min)q(zt)
+end
+
+@meta function hgfmeta()
+    # Lets use 31 approximation points in the Gauss Hermite cubature approximation method
+    GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) 
+end
hgfmeta (generic function with 1 method)
function run_inference(data, real_k, real_w, z_variance, y_variance)
+
+    autoupdates   = @autoupdates begin
+        zt_min_mean, zt_min_var = mean_var(q(zt))
+        xt_min_mean, xt_min_var = mean_var(q(xt))
+    end
+
+    return rxinference(
+        model         = hgf(real_k, real_w, z_variance, y_variance),
+        constraints   = hgfconstraints(),
+        meta          = hgfmeta(),
+        data          = (y = data, ),
+        autoupdates   = autoupdates,
+        keephistory   = length(data),
+        historyvars    = (
+            xt = KeepLast(),
+            zt = KeepLast()
+        ),
+        initmarginals = (
+            zt = NormalMeanVariance(0.0, 5.0),
+            xt = NormalMeanVariance(0.0, 5.0),
+        ), 
+        iterations    = 5,
+        free_energy   = true,
+        autostart     = true,
+        callbacks     = (
+            after_model_creation = (model, returnval) -> begin 
+                gcvnode = returnval
+                setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))
+            end,
+        )
+    )
+end
run_inference (generic function with 1 method)
result = run_inference(y, real_k, real_w, z_variance, y_variance);
+
+mz = result.history[:zt];
+mx = result.history[:xt];
let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = "estimated z_i", color = :teal)
+    
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = "estimated x_i", color = :violet)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:

plot(result.free_energy_history, label = "Bethe Free Energy")

As we can see BetheFreeEnergy converges nicely to a stable point.

At final, lets check the overall performance of our resulting Variational Message Passing algorithm:

@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)
BenchmarkTools.Trial: 64 samples with 1 evaluation.
+ Range (min … max):  59.119 ms … 128.093 ms  ┊ GC (min … max): 0.00% … 0.00
+%
+ Time  (median):     77.214 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   79.066 ms ±  13.156 ms  ┊ GC (mean ± σ):  6.22% ± 6.90
+%
+
+        ▂  ▂▂   ▂▂ ▅█▅       ▂▂▂▂                               
+  ▅█▅▅▅▅█▅▅██▁▁███▅███▁▅▅▅▅▁▅████▁▅▁▁▁▁▁▅▅▁▁▁▁▅▅▁▁▁▁▁▁▁▁▁▁▁▁▁▅ ▁
+  59.1 ms         Histogram: frequency by time          119 ms <
+
+ Memory estimate: 18.64 MiB, allocs estimate: 447879.
diff --git a/v2.15.0/examples/problem_specific/Invertible Neural Network Tutorial/index.html b/v2.15.0/examples/problem_specific/Invertible Neural Network Tutorial/index.html new file mode 100644 index 000000000..f83c6158f --- /dev/null +++ b/v2.15.0/examples/problem_specific/Invertible Neural Network Tutorial/index.html @@ -0,0 +1,293 @@ + +Invertible neural networks: a tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Invertible neural networks: a tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Table of contents

  1. Introduction
  2. Model specification
  3. Model compilation
  4. Probabilistic inference
  5. Parameter estimation

Introduction

Load required packages

Before we can start, we need to import some packages:

using RxInfer
+using Random
+using StableRNGs
+
+using ReactiveMP        # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality
+using LinearAlgebra     # only used for some matrix specifics
+using Plots             # only used for visualisation
+using Distributions     # only used for sampling from multivariate distributions
+using Optim             # only used for parameter optimisation

Model specification

Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as 

model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Alternatively, the input_dim can also be passed as an InputLayer layer as 

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

In the above AdditiveCouplingLayer layers the input ${\bf{x}} = [x_1, x_2, \ldots, x_N]$ is partitioned into chunks of unit length. These partitions are additively coupled to an output ${\bf{y}} = [y_1, y_2, \ldots, y_N]$ as

\[\begin{aligned} + y_1 &= x_1 \\ + y_2 &= x_2 + f_1(x_1) \\ + \vdots \\ + y_N &= x_N + f_{N-1}(x_{N-1}) +\end{aligned}\]

Importantly, this structure can easily be converted as

\[\begin{aligned} + x_1 &= y_1 \\ + x_2 &= y_2 - f_1(x_1) \\ + \vdots \\ + x_N &= y_N - f_{N-1}(x_{N-1}) +\end{aligned}\]

\[f_n\]

is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.

A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false),
+        PermutationLayer(PermutationMatrix(2)),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Model compilation

In the current models, the layers are setup to work with the passed input dimension. This means that the function $f_n$ is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get

model
FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P
+lanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa
+yerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou
+plingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar
+FlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad
+ditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive
+MP.PlanarFlowEmpty{1}(),), 1)))

The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):

  • FlowModel - specifies that we are dealing with a flow model.
  • 3 - Number of layers.
  • Tuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.
  • Tuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions $f_n$.
  • PermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].

From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as

compiled_model = compile(model)
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(-0.51319441885293, -0.562855685
+8301944, -0.6039741162529291),), 1), PermutationLayer{Int64}(2, [0 1; 1 0])
+, AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlow
+{Float64, Float64}(-0.41324059953248177, -0.6524105536272277, 0.01360673107
+9877291),), 1)))

Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.

compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361
+28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323
+52386),), 1)))

Probabilistic inference

We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.

function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)
+
+    rng = StableRNG(seed)
+    
+    # specify latent sampling distribution
+    dist = MvNormal([1.5, 0.5], I)
+
+    # sample from the latent distribution
+    x = rand(rng, dist, nr_samples)
+
+    # transform data
+    y = zeros(Float64, size(x))
+    for k = 1:nr_samples
+        y[:,k] .= ReactiveMP.forward(model, x[:,k])
+    end
+
+    # return data
+    return y, x
+
+end;
# generate data
+y, x = generate_data(1000, compiled_model)
+
+# plot generated data
+p1 = scatter(x[1,:], x[2,:], alpha=0.3, title="Original data", size=(800,400))
+p2 = scatter(y[1,:], y[2,:], alpha=0.3, title="Transformed data", size=(800,400))
+plot(p1, p2, legend = false)

The probabilistic model for doing inference can be described as 

@model function invertible_neural_network(nr_samples::Int64)
+    
+    # initialize variables
+    z_μ   = randomvar()
+    z_Λ   = randomvar()
+    x     = randomvar(nr_samples)
+    y_lat = randomvar(nr_samples)
+    y     = datavar(Vector{Float64}, nr_samples)
+
+    # specify prior
+    z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))
+    z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)
+
+        # specify transformed latent value
+        y_lat[k] ~ Flow(x[k])
+
+        # specify observations
+        y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))
+
+    end
+
+    # return variables
+    return z_μ, z_Λ, x, y_lat, y
+
+end;

Here the model is passed inside a meta data object of the flow node. Inference then resorts to

observations = [y[:,k] for k=1:size(y,2)]
+
+fmodel         = invertible_neural_network(length(observations))
+data          = (y = observations, )
+initmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))
+returnvars    = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())
+
+constraints = @constraints begin
+    q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)
+end
+
+@meta function fmeta(model)
+    compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
+    Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). 
+                                               # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))
+end
+
+# First execution is slow due to Julia's initial compilation 
+result = inference(
+    model = fmodel, 
+    data  = data,
+    constraints   = constraints,
+    meta          = fmeta(model),
+    initmarginals = initmarginals,
+    returnvars    = returnvars,
+    free_energy   = true,
+    iterations    = 10, 
+    showprogress  = false
+)
Inference results:
+  Posteriors       | available for (z_μ, z_Λ, y_lat, x)
+  Free Energy:     | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357
+0.6, 23570.6, 23570.6, 23570.6, 23570.6]
fe_flow = result.free_energy
+zμ_flow = result.posteriors[:z_μ]
+zΛ_flow = result.posteriors[:z_Λ]
+x_flow  = result.posteriors[:x]
+y_flow  = result.posteriors[:y_lat];

As we can see, the variational free energy decreases inside of our model.

plot(1:10, fe_flow/size(y,2), xlabel="iteration", ylabel="normalized variational free energy [nats/sample]", legend=false)

If we plot a random noisy observation and its approximated transformed uncertainty we obtain:

# pick a random observation
+id = rand(StableRNG(321), 1:size(y,2))
+rand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))
+warped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');
+
+p1 = scatter(x[1,:], x[2,:], alpha=0.1, title="Latent distribution", size=(1200,500), label="generated data")
+contour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)
+scatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color="red", markershape=:x, markersize=5, label="inferred mean")
+contour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors="red", levels=1, linewidth=2, colorbar=false)
+scatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color="red", label="transformed noisy observation")
+p2 = scatter(y[1,:], y[2,:], alpha=0.1, label="generated data")
+scatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color="red", marker=:x, label="inferred mean")
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors="red", levels=1, linewidth=2, label="random noisy observation", colorba=false)
+scatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color="red", label="random noisy observation")
+plot(p1, p2, legend = true)

Parameter estimation

The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+
+    # sample weights
+    w = rand(rng, nr_samples, 2)
+
+    # sample appraisal
+    y = zeros(Float64, nr_samples)
+    for k = 1:nr_samples
+        y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)
+    end
+
+    # return data
+    return y, w
+
+end;
data_y, data_x = generate_data(50);
+scatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel="w1", ylabel="w2", colorbar=false, legend=false)

We will then specify a possible model as

# specify flow model
+model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

The corresponding probabilistic model for the binary classification task can be created as

@model function invertible_neural_network_classifier(nr_samples::Int64)
+    
+    # initialize variables
+    x_lat  = randomvar(nr_samples)
+    y_lat1 = randomvar(nr_samples)
+    y_lat2 = randomvar(nr_samples)
+    y      = datavar(Float64, nr_samples)
+    x      = datavar(Vector{Float64}, nr_samples)
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))
+
+        # specify transformed latent value
+        y_lat1[k] ~ Flow(x_lat[k])
+        y_lat2[k] ~ dot(y_lat1[k], [1, 1])
+
+        # specify observations
+        y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }
+
+    end
+
+    # return variables
+    return x_lat, x, y_lat1, y_lat2, y
+
+end;
fcmodel       = invertible_neural_network_classifier(length(data_y))
+data          = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )
+
+@meta function fmeta(model, params)
+    compiled_model = compile(model, params)
+    Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)
+end
fmeta (generic function with 2 methods)

Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as

For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.

function f(params)
+    Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure
+    result = inference(
+        model                   = fcmodel, 
+        data                    = data,
+        meta                    = fmeta(model, params),
+        free_energy             = true,
+        free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure
+        iterations              = 10, 
+        showprogress            = false
+    );
+    
+    result.free_energy[end]
+end;

Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:

res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)
  • uses finitediff and is slower/less accurate.

or

# create gradient function
+g = (x) -> ForwardDiff.gradient(f, x);
+
+# specify initial params
+params = randn(nr_params(model))
+
+# create custom optimizer (here Adam)
+optimizer = Adam(params; λ=1e-1)
+
+# allocate space for gradient
+∇ = zeros(nr_params(model))
+
+# perform optimization
+for it = 1:10000
+
+    # backward pass
+    ∇ .= ForwardDiff.gradient(f, optimizer.x)
+
+    # gradient update
+    ReactiveMP.update!(optimizer, ∇)
+
+end
+
res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)
Iter     Function value   Gradient norm 
+     0     5.888958e+02     8.943663e+02
+ * time: 0.022298812866210938
+   100     1.059826e+01     4.120090e+00
+ * time: 14.472792863845825
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.010332e+01
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.21e-03 ≰ 0.0e+00
+    |x - x'|/|x'|          = 5.80e-04 ≰ 0.0e+00
+    |f(x) - f(x')|         = 6.28e-03 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03
+    |g(x)|                 = 2.07e+00 ≰ 1.0e-08
+
+ * Work counters
+    Seconds run:   16  (vs limit Inf)
+    Iterations:    113
+    f(x) calls:    301
+    ∇f(x) calls:   301

optimization results are then given as

params = Optim.minimizer(res)
+inferred_model = compile(model, params)
+trans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'
+trans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])
+trans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title="original data")
+p2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title="|> warp")
+p3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title="|> dot")
+plot(p1, p2, p3, layout=(1,3), legend=false)

using StatsFuns: normcdf
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title="original labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title="predicted labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title="Classification map", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+plot(p1, p2, p3, layout=(1,3), legend=false)

diff --git a/v2.15.0/examples/problem_specific/Probit Model (EP)/index.html b/v2.15.0/examples/problem_specific/Probit Model (EP)/index.html new file mode 100644 index 000000000..c619a2657 --- /dev/null +++ b/v2.15.0/examples/problem_specific/Probit Model (EP)/index.html @@ -0,0 +1,76 @@ + +Probit Model (EP) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Probit Model (EP)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable $x_t$ with the discrete variable $y_t$. The model is defined as:

\[\begin{aligned} + u &= 0.1 \\ + x_0 &\sim \mathcal{N}(0, 100) \\ + x_t &\sim \mathcal{N}(x_{t-1}+ u, 0.01) \\ + y_t &\sim \mathrm{Ber}(\Phi(x_t)) +\end{aligned}\]

Import packages

using RxInfer, StableRNGs, Random, Plots
+using StatsFuns: normcdf

Data generation

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+    
+    # hyper parameters
+    u = 0.1
+
+    # allocate space for data
+    data_x = zeros(nr_samples + 1)
+    data_y = zeros(nr_samples)
+    
+    # initialize data
+    data_x[1] = -2
+    
+    # generate data
+    for k = 2:nr_samples + 1
+        
+        # calculate new x
+        data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)
+        
+        # calculate y
+        data_y[k-1] = normcdf(data_x[k]) > rand(rng)
+        
+    end
+    
+    # return data
+    return data_x, data_y
+    
+end;
n = 40
40
data_x, data_y = generate_data(n);
p = plot(xlabel = "t", ylabel = "x, y")
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x")

Model specification

@model function probit_model(nr_samples::Int64)
+    
+    # allocate space for variables
+    x = randomvar(nr_samples + 1)
+    y = datavar(Float64, nr_samples)
+    
+    # specify uninformative prior
+    x[1] ~ Normal(mean = 0.0, precision = 0.01)
+    
+    # create model 
+    for k = 2:nr_samples + 1
+        x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)
+        y[k - 1] ~ Probit(x[k]) where {
+            # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge
+            # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations
+            pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) 
+        }
+    end
+    
+end;

Inference

result = inference(
+    model = probit_model(length(data_y)), 
+    data  = (y = data_y, ), 
+    iterations = 5, 
+    returnvars = (x = KeepLast(),),
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (x)
+  Free Energy:     | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]

Results

mx = result.posteriors[:x]
+
+p = plot(xlabel = "t", ylabel = "x, y", legend = :bottomright)
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x", lw = 2)
+p = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label="x (inferred mean)")
+
+f = plot(xlabel = "t", ylabel = "BFE")
+f = plot!(result.free_energy, label = "Bethe Free Energy")
+
+plot(p, f, size = (800, 400))

diff --git a/v2.15.0/examples/problem_specific/RTS vs BIFM Smoothing/index.html b/v2.15.0/examples/problem_specific/RTS vs BIFM Smoothing/index.html new file mode 100644 index 000000000..625f75119 --- /dev/null +++ b/v2.15.0/examples/problem_specific/RTS vs BIFM Smoothing/index.html @@ -0,0 +1,242 @@ + +RTS vs BIFM Smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

RTS vs BIFM Smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

___Credits to Martin de Quincey___

This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:

  1. F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762
  2. H. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.

We perform Kalman smoothing in the linear state space model, represented by:

\[\begin{aligned} + Z_{k+1} &= A Z_k + B U_k \\ + Y_k &= C Z_k + W_k +\end{aligned}\]

with observations $Y_k$, latent states $Z_k$ and inputs $U_k$. $W_k$ is the observation noise. $A \in \mathrm{R}^{n \times n}$, $B \in \mathrm{R}^{n \times m}$ and $C \in \mathrm{R}^{d \times n}$ are the transition matrices in the model. Here $n$, $m$ and $d$ denote the dimensionality of the latent, input and output dimension, respectively.

The corresponding probabilistic model can be represented as

\[\begin{aligned} + p(y,\ z,\ u) + &= p(z_0) \prod_{k=1}^N p(y_k \mid z_k)\ p(z_k\mid z_{k-1},\ u_{k-1})\ p(u_{k-1}) \\ + &= \mathcal{N}(z_0 \mid \mu_{z_0}, \Sigma_{z_0}) \left( \prod_{k=1}^N \mathcal{N}(y_k \mid C z_k,\ \Sigma_W)\ \delta(z_k - (Az_{k-1} + Bu_{k-1})) \mathcal{N}(u_{k-1} \mid \mu_{i_{k-1}},\ \Sigma_{u_{k-1}}) \right) +\end{aligned}\]

Import packages

using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs

Data generation

function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)
+    
+    # define noise levels
+    input_noise  = 500.0
+    output_noise = 50.0
+
+    # create random generator for reproducibility
+    rng = MersenneTwister(seed)
+
+    # generate matrices, input statistics and noise matrices
+    A      = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat))                                            # size (dim_lat x dim_lat)
+    B      = rand(dim_lat, dim_in)                                                                              # size (dim_lat x dim_in)
+    C      = rand(dim_out, dim_lat)                                                                             # size (dim_out x dim_lat)
+    μu     = rand(dim_in) .* collect(1:dim_in)                                                                  # size (dim_in x 1)
+    Σu     = input_noise  .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in))))      # size (dim_in x dim_in)
+    Σy     = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out))))   # size (dim_out x dim_out)
+    Wu     = inv(Σu)
+    Wy     = inv(Σy)
+    
+    # return parameters
+    return A, B, C, μu, Σu, Σy, Wu, Wy
+
+end;
function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)
+        
+    # create random data generator
+    rng = StableRNG(seed)
+    
+    # preallocate space for variables
+    z = Vector{Vector{Float64}}(undef, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+    u = rand(rng, MvNormal(μu, Σu), nr_samples)'
+    
+    # set initial value of latent states
+    z_prev = zeros(size(A,1))
+    
+    # generate data
+    for i in 1:nr_samples
+
+        # generate new latent state
+        z[i] = A * z_prev + B * u[i,:]
+
+        # generate new observation
+        y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))
+        
+        # generate new observation
+        z_prev .= z[i]
+        
+    end
+    
+    # return generated data
+    return z, y, u
+    
+end
generate_data (generic function with 1 method)
# specify settings
+nr_samples = 200
+dim_out = 3
+dim_in = 3
+dim_lat = 25
+
+# generate parameters
+A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);
+            
+# generate data
+data_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);
+
+# visualise data
+p = Plots.plot(xlabel = "sample", ylabel = "observations")
+# plot each dimension independently
+for i in 1:dim_out
+    Plots.scatter!(p, getindex.(data_y, i), label = "y_$i", alpha = 0.5, ms = 2)
+end
+p

Model specification

@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+    
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    dim_out = size(C, 1)
+    
+    # initialize variables
+    z = randomvar(nr_samples)                 # hidden states (random variable)
+    u = randomvar(nr_samples)                 # inputs (random variable)
+    y = datavar(Vector{Float64}, nr_samples)  # outputs (observed variables)
+    
+    # set initial hidden state
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    
+    # update last/previous hidden state
+    z_prev = z_prior
+
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i] ~ MvNormalMeanPrecision(μu, Wu)
+        
+        # specify updated hidden state
+        z[i] ~ A * z_prev + B * u[i]
+        
+        # specify observation
+        y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+end
@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    
+    # initialize variables
+    z  = randomvar(nr_samples)                  # latent states
+    yt = randomvar(nr_samples)                  # latent observations
+    y  = datavar(Vector{Float64}, nr_samples)   # actual observations
+    u  = randomvar(nr_samples)                  # inputs
+    
+    # set priors
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    z_tmp   ~ BIFMHelper(z_prior) where { q = MeanField() }
+    
+    # update last/previous hidden state
+    z_prev = z_tmp
+    
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i]   ~ MvNormalMeanPrecision(μu, Wu)
+
+        # specify observation
+        yt[i]  ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }
+        y[i]   ~ MvNormalMeanPrecision(yt[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+    # set final value
+    z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))
+    
+end

Probabilistic inference

function inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+    
+    # In this task the inference is unstable and can diverge
+    meta = @meta begin 
+        *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)
+    end
+    
+    result = inference(
+        model      = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast()),
+        meta = meta
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_RTS (generic function with 1 method)
function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)
+    result = inference(
+        model      = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast())
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_BIFM (generic function with 1 method)

Experiments for 200 observations

z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+z_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);
ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state z")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state z")
+
+mz_RTS = mean.(z_RTS)
+mz_BIFM = mean.(z_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:5
+    Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state u")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state u")
+
+rdata_u = collect(eachrow(data_u))
+mu_RTS = mean.(u_RTS)
+mu_BIFM = mean.(u_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:1
+    Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

Benchmark

# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation
+# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`
+run_benchmark = false
+
+if run_benchmark
+    trials_range = 30
+    trials_n = 500
+    trials_RTS  = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+    trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+
+
+    @showprogress for k = 1 : trials_range
+
+        # generate parameters
+        local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);
+                    
+        # generate data|
+        local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);
+
+        # run inference
+        trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+        trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+
+    end
+
+    m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9
+    q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9
+    m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9
+    q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;
+
+    p = Plots.plot(ylabel = "duration [sec]", xlabel = "latent state dimension", title = "Benchmark", yscale = :log)
+    p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = "blue", label = "mean (RTS)")
+    p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = "orange", label = "mean (BIFM)")
+    Plots.savefig(p, "../pics/rts_bifm_benchmark.png")
+    p
+end

diff --git a/v2.15.0/examples/problem_specific/Simple Nonlinear Node/index.html b/v2.15.0/examples/problem_specific/Simple Nonlinear Node/index.html new file mode 100644 index 000000000..3e3165acb --- /dev/null +++ b/v2.15.0/examples/problem_specific/Simple Nonlinear Node/index.html @@ -0,0 +1,67 @@ + +Simple Nonlinear Node · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Simple Nonlinear Node

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, StableRNGs

Here is an example of creating custom node with nonlinear function approximation with samplelist.

Custom node creation

struct NonlinearNode end # Dummy structure just to make Julia happy
+
+struct NonlinearMeta{R, F}
+    rng      :: R
+    fn       :: F   # Nonlinear function, we assume 1 float input - 1 float output
+    nsamples :: Int # Number of samples used in approximation
+end
@node NonlinearNode Deterministic [ out, in ]

We need to define two Sum-product message computation rules for our new custom node

  • Rule for outbound message on out edge given inbound message on in edge
  • Rule for outbound message on in edge given inbound message on out edge
  • Both rules accept optional meta object
# Rule for outbound message on `out` edge given inbound message on `in` edge
+@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin 
+    samples = rand(meta.rng, m_in, meta.nsamples)
+    return SampleList(map(meta.fn, samples))
+end
# Rule for outbound message on `in` edge given inbound message on `out` edge
+@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin     
+    return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))
+end

Model specification

After we have defined our custom node with custom rules we may proceed with a model specification:

\[\begin{aligned} +p(\theta) &= \mathcal{N}(\theta|\mu_{\theta}, \sigma_{\theta}),\\ +p(m) &= \mathcal{N}(\theta|\mu_{m}, \sigma_{m}),\\ +p(w) &= f(\theta),\\ +p(y_i|m, w) &= \mathcal{N}(y_i|m, w), +\end{aligned}\]

Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable $\theta$ through a non-linear transformation $f$ to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of $\theta$. 

@model function nonlinear_estimation(n)
+    
+    θ ~ Normal(mean = 0.0, variance = 100.0)
+    m ~ Normal(mean = 0.0, variance = 1.0)
+    
+    w ~ NonlinearNode(θ)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = m, precision = w)
+    end
+    
+end
@constraints function nconstsraints(nsamples)
+    q(θ) :: SampleList(nsamples, LeftProposal())
+    q(w) :: SampleList(nsamples, RightProposal())
+    
+    q(θ, w, m) = q(θ)q(m)q(w)
+end
nconstsraints (generic function with 1 method)
@meta function nmeta(fn, nsamples)
+    NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)
+end
nmeta (generic function with 1 method)

Here we generate some data

nonlinear_fn(x) = abs(exp(x) * sin(x))
nonlinear_fn (generic function with 1 method)
seed = 123
+rng  = StableRNG(seed)
+
+niters   = 15 # Number of VMP iterations
+nsamples = 5_000 # Number of samples in approximation
+
+n = 500 # Number of IID samples
+μ = -10.0
+θ = -1.0
+w = nonlinear_fn(θ)
+
+data = rand(rng, NormalMeanPrecision(μ, w), n);
result = inference(
+    model = nonlinear_estimation(n),
+    meta =  nmeta(nonlinear_fn, nsamples),
+    constraints = nconstsraints(nsamples),
+    data = (y = data, ), 
+    initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),
+    returnvars = (θ = KeepLast(), ),
+    iterations = niters,  
+    showprogress = true
+)
Inference results:
+  Posteriors       | available for (θ)
θposterior = result.posteriors[:θ]
SampleList(Univariate, 5000)
using Plots, StatsPlots
+
+estimated = Normal(mean_std(θposterior)...)
+
+plot(estimated, title="Posterior for θ", label = "Estimated", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))
+vline!([ θ ], label = "Real value of θ")

diff --git a/v2.15.0/examples/problem_specific/Universal Mixtures/index.html b/v2.15.0/examples/problem_specific/Universal Mixtures/index.html new file mode 100644 index 000000000..cf52816f7 --- /dev/null +++ b/v2.15.0/examples/problem_specific/Universal Mixtures/index.html @@ -0,0 +1,94 @@ + +Universal Mixtures · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Universal Mixtures

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Distributions, Random, Plots

John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment

\[p(y_i \mid \theta) = \mathrm{Ber}(y_i \mid \theta),\]

where $y_i \in \{0,1\}$ are the outcomes of the coin tosses, i.e. heads or tails, and where $\theta$ is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter $\theta$, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of $\theta\in[0,1]$ they come up with the prior beliefs:

\[p(\theta \mid \text{John}) = \mathrm{Beta}(\theta \mid 7, 2)\]

\[p(\theta \mid \text{Jane}) = \mathrm{Beta}(\theta \mid 2, 7)\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior beliefs")
+plot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label="P(θ) John", c=1)
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="p(θ) Jane", c=3,)

John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. 

true_coin = Bernoulli(0.25)
+nr_throws = 10
+dataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))
+nr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)
+println("experimental outcome: \n - heads: ", nr_heads, "\n - tails: ", nr_tails);
experimental outcome: 
+ - heads: 3
+ - tails: 7

For computing the posterior beliefs $p(\theta \mid y)$ about the parameter $\theta$, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:

John's model:

\[p(y, \theta \mid \text{John}) = p(\theta \mid \text{John}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_john(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's prior model over θ
+    θ ~ Beta(7.0, 2.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Jane's model:

\[p(y, \theta \mid \text{Jane}) = p(\theta \mid \text{Jane}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_jane(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify Jane's prior model over θ
+    θ ~ Beta(2.0, 7.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy $\mathrm{F}_B$ bounds the model evidence $p(y)$ as

\[\mathrm{F}_B[p,q] \geq - \ln p(y)\]

result_john = inference(
+    model = beta_model_john(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true,
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[8.96366]
result_jane = inference(
+    model = beta_model_jane(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[6.63988]

From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying $\theta$ parameter. They formulate this through the posterior distributions $p(\theta \mid y, \text{John})$ and $p(\theta \mid y, \text{Jane})$:

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior beliefs")
+plot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) John", c=1)
+plot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="p(θ|y) Jane", c=3,)

What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over $\theta$, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as

\[p(y, \theta, c \mid \text{Mary}) = p(c \mid \text{Mary}) \, p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} \prod_{i=1}^N p(y_i \mid \theta),\]

where $c$ describes the probability of John being correct as

\[p(c \mid \text{Mary}) = \mathrm{Ber}(c \mid 0.7)\]

The predictive distribution $p(\theta \mid \text{Mary})$ for $\theta$ (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over $c$ as

\[p(\theta \mid \text{Mary}) = \sum_{c\in\{0,1\}} p(c\mid\text{Mary}) p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} = 0.7 \cdot p(\theta \mid \text{John}) + 0.3 \cdot p(\theta \mid \text{Jane})\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior belief")
+plot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label="P(θ) Mary", c=1)
+plot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label="")
+plot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label="")

She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:

@model function beta_model_mary(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's and Jane's prior models over θ
+    θ_jane ~ Beta(2.0, 7.0)
+    θ_john ~ Beta(7.0, 2.0)
+
+    # specify initial guess as to who is right
+    john_is_right ~ Bernoulli(0.7) 
+
+    # specify mixture prior Distribution
+    θ ~ Mixture(john_is_right, (θ_jane, θ_john))
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

This Mixture node updates the belief over $c$ on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.

result_mary = inference(
+    model = beta_model_mary(nr_throws), 
+    data  = (y = dataset, ),
+    returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),
+    addons = AddonLogScale(),
+    postprocess = UnpackMarginalPostprocess(),
+)
Inference results:
+  Posteriors       | available for (john_is_right, θ_john, θ, θ_jane)

Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over $\theta$ also changed, and as expected the estimate from Jane was more prominent.

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior belief")
+plot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) Mary", c=1)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label="", c=3)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label="", c=3)

diff --git a/v2.15.0/examples/problem_specific/overview/index.html b/v2.15.0/examples/problem_specific/overview/index.html new file mode 100644 index 000000000..fef75b979 --- /dev/null +++ b/v2.15.0/examples/problem_specific/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Problem specific

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Problem specific examples contain specialized models and inference for various domains.

diff --git a/v2.15.0/index.html b/v2.15.0/index.html new file mode 100644 index 000000000..7747e084c --- /dev/null +++ b/v2.15.0/index.html @@ -0,0 +1,2 @@ + +Home · RxInfer.jl
GitHub

RxInfer

Julia package for automatic Bayesian inference on a factor graph with reactive message passing.

Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.

Package Features

  • User friendly syntax for specification of probabilistic models.
  • Automatic generation of message passing algorithms including
  • Support for hybrid models combining discrete and continuous latent variables.
  • Support for hybrid distinct message passing inference algorithm under a unified paradigm.
  • Factorisation and functional form constraints specification.
  • Evaluation of Bethe free energy as a model performance measure.
  • Schedule-free reactive message passing API.
  • High performance.
  • Scalability for large models with millions of parameters and observations.
  • Inference procedure is differentiable.
  • Easy to extend with custom nodes and message update rules.

Why RxInfer

Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a "variational Free Energy" cost function. For large models, manual derivation of these gradients might not be feasible, while automated "black-box" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.

RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different "what-if" scenarios and enables very efficient inference in specific cases.

Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.

How to get started?

Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.

Table of Contents

References

Ecosystem

The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:

  • ReactiveMP.jl - core package for efficient and scalable for reactive message passing
  • GraphPPL.jl - package for model and constraints specification
  • Rocket.jl - reactive programming tools

Index

diff --git a/v2.15.0/library/bethe-free-energy/index.html b/v2.15.0/library/bethe-free-energy/index.html new file mode 100644 index 000000000..4e71114e3 --- /dev/null +++ b/v2.15.0/library/bethe-free-energy/index.html @@ -0,0 +1,2 @@ + +Bethe Free Energy · RxInfer.jl
GitHub

Bethe Free Energy implementation in RxInfer

The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.

Factorized model

Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, $y = (y_1, \dots, y_j, \dots, y_m)\,,$ and variables that can not be observed directly, also known as latent variables, $x = (x_1, \dots, x_i, \dots, x_n)\,.$ We then define a model that factorizes over consituent smaller factors (functions), as $f(y,x) = \prod_a f_a(y_a,x_a)\,.$

Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).

Variational Free Energy

The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, $F[q](\hat{y}) = \mathbb{E}_{q(x)}\left[\log \frac{q(x)}{f(y=\hat{y}, x)} \right]\,.$ A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.

The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.

Variational inference

The goal of variational inference is to find a variational distibution that minimizes the VFE, $q^{*}(x) = \arg\min_{q\in\mathcal{Q}} F[q](\hat{y})\,.$ This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.

For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.

Bethe approximation

Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.

A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, $q(x) \triangleq \frac{\prod_a q_a(x_a)}{\prod_i q_i(x_i)^{d_i - 1}}\,.$ The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.

The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.

The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.

Bethe Free Energy

The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as $F_B[q](\hat{y}) = \sum_a U_a[q_a](\hat{y}_a) - \sum_a H[q_a] + \sum_i (d_i - 1) H[q_i]\,.$ The first term of the BFE specifies an average energy, $U_a[q_a](\hat{y}_a) = -\mathbb{E}_{q_a(x_a)}\left[\log f_a(y_a=\hat{y}_a, x_a)\right]\,,$ which internalizes the factors of the model. The last two terms specify entropies.

Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.

For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the inference and rxinference functions initializes the variational distributions of the BFE.

For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.

Further reading

  • Pearl (1986) on the original foundations of Bayesian networks and belief propagation;
  • Yedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;
  • Dauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);
  • Senoz et al. (2021) on constraint manipulation and message passing on FFGs.
RxInfer.AbstractScoreObjective — Type
AbstractScoreObjective

Abstract type for functional objectives that can be used in the score function.

Note

score is defined in the ReactiveMP package.

source
RxInfer.BetheFreeEnergy — Type
BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)

Creates Bethe Free Energy values stream when passed to the score function.

source
RxInfer.apply_diagnostic_check — Function
apply_diagnostic_check(check, context, stream)

This function applies a check to the stream. Accepts optional context object for custom error messages.

source
diff --git a/v2.15.0/library/exported-methods/index.html b/v2.15.0/library/exported-methods/index.html new file mode 100644 index 000000000..cce4c55b8 --- /dev/null +++ b/v2.15.0/library/exported-methods/index.html @@ -0,0 +1,854 @@ + +Exported methods · RxInfer.jl
GitHub

Using methods from RxInfer

In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:

using RxInfer

A nice explanation about how modules/packages work in Julia can be found in the official documentation.

In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:

import RxInfer: mean

One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:

import RxInfer: mean as mean_from_rxinfer
+import Distributions: mean as mean_from_distributions
+
+mean_from_rxinfer === mean_from_distributions
true

Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.

# It is easier to let Julia resolve names automatically
+# Julia will not overwrite `mean` that is coming from both packages
+using RxInfer, Distributions
mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`
0.0
mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`
0.0

List of available methods

Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.

Note

Some exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.

foreach(println, names(RxInfer))
@autoupdates
+@average_energy
+@call_marginalrule
+@call_rule
+@constraints
+@logscale
+@marginalrule
+@meta
+@model
+@node
+@rule
+AND
+AR
+ARMeta
+ARsafe
+ARunsafe
+AbstractActor
+AbstractActorFactory
+AbstractApproximationMethod
+AbstractFormConstraint
+AbstractMStorage
+AbstractMessage
+AbstractMixtureModel
+AbstractMvNormal
+AbstractOperator
+AbstractPipelineStage
+AbstractSubject
+AbstractSubjectFactory
+AbstractSubscribable
+AbstractVariable
+Actor
+ActorProxy
+ActorSourceProxy
+ActorTrait
+Adam
+AdditiveCouplingLayer
+AddonDebug
+AddonLogScale
+AddonMemory
+Arcsine
+ArrayLikeVariate
+ArrayObservable
+AsapScheduler
+AsyncPipelineStage
+AsyncScheduler
+AutoProposal
+AutoVar
+Autoregressive
+AverageEnergy
+BIFM
+BIFMHelper
+BIFMMeta
+BaseActorTrait
+BayesBase
+BehaviorSubject
+BehaviorSubjectFactory
+Bernoulli
+BernoulliLogit
+Beta
+BetaBinomial
+BetaPrime
+BetheFreeEnergy
+BetheFreeEnergyCheckInfs
+BetheFreeEnergyCheckNaNs
+BetheFreeEnergyDefaultChecks
+BetheFreeEnergyDefaultMarginalSkipStrategy
+Binomial
+Biweight
+BufferActor
+CVI
+CallableTeardownLogic
+Categorical
+Cauchy
+Chernoff
+Chi
+Chisq
+CholeskyVariate
+CircularKeepActor
+ClosedProd
+CompanionMatrix
+CompanionMatrixTransposed
+CompiledFlowModel
+CompletedObservable
+CompletionActor
+CompletionActorTrait
+CompositeFormConstraint
+CompositePipelineStage
+ConnectableObservable
+ConstVariable
+ConstantBaseMeasure
+ConstraintsSpecification
+Contingency
+Continuous
+ContinuousDistribution
+ContinuousMatrixDistribution
+ContinuousMultivariateDistribution
+ContinuousMultivariateLogPdf
+ContinuousUnivariateDistribution
+ContinuousUnivariateLogPdf
+Cosine
+CountingReal
+CustomProdStrategy
+DataVariable
+DefaultConstraints
+DefaultMeta
+DefaultPostprocess
+DeltaFn
+DeltaFnNode
+DeltaMeta
+Deterministic
+DiagNormal
+DiagNormalCanon
+DifferentialEntropy
+Dirac
+Dirichlet
+DirichletMultinomial
+DiscontinuePipelineStage
+Discrete
+DiscreteDistribution
+DiscreteMatrixDistribution
+DiscreteMultivariateDistribution
+DiscreteNonParametric
+DiscreteUniform
+DiscreteUnivariateDistribution
+Distribution
+Distributions
+Domain
+DoubleExponential
+EdgeworthMean
+EdgeworthSum
+EdgeworthZ
+EmptyPipelineStage
+Epanechnikov
+Erlang
+ErrorActor
+ErrorActorTrait
+Estimator
+Exponential
+ExponentialFamily
+ExponentialFamilyDistribution
+ExponentialFamilyDistributionAttributes
+ExtraArgumentInCompleteCall
+FDist
+FactorBoundFreeEnergy
+FactorGraphModel
+FactorNodeCreationOptions
+FactorNodesCollection
+FactorizedJoint
+FastCholesky
+FaultedObservable
+FirstNotFoundException
+FisherNoncentralHypergeometric
+Flow
+FlowMeta
+FlowModel
+FoldLeftProdStrategy
+FoldRightProdStrategy
+FormConstraintCheckEach
+FormConstraintCheckLast
+FormConstraintCheckPickDefault
+ForwardDiffGrad
+Frechet
+FullFactorisation
+FullNormal
+FullNormalCanon
+FunctionActor
+FunctionObservable
+GCV
+GCVMetadata
+Gamma
+GammaDistributionsFamily
+GammaInverse
+GammaMixture
+GammaMixtureNode
+GammaShapeRate
+GammaShapeScale
+GaussHermiteCubature
+GaussLaguerreQuadrature
+GaussianDistributionsFamily
+GaussianMeanPrecision
+GaussianMeanVariance
+GaussianMixture
+GaussianMixtureNode
+GaussianWeighteMeanPrecision
+GeneralizedExtremeValue
+GeneralizedPareto
+GenericProd
+Geometric
+GraphPPL
+Gumbel
+HalfNormal
+Hypergeometric
+IMPLY
+ImportanceSamplingApproximation
+IncludeAll
+InconsistentActorWithSubscribableDataTypesError
+InconsistentSourceActorDataTypesError
+InconsistentSourceOperatorDataTypesError
+InconsistentSubjectDataTypesError
+InferableOperator
+InferableOperatorTrait
+InferenceResult
+InputLayer
+InvalidActorTrait
+InvalidActorTraitUsageError
+InvalidMultipleTeardownLogicTraitUsageError
+InvalidOperatorTrait
+InvalidOperatorTraitUsageError
+InvalidSubjectTrait
+InvalidSubjectTraitUsageError
+InvalidSubscribableTrait
+InvalidSubscribableTraitUsageError
+InvalidTeardownLogic
+InvalidTeardownLogicTraitUsageError
+InverseGamma
+InverseGaussian
+InverseWishart
+IsoNormal
+IsoNormalCanon
+JohnsonSU
+JointGaussian
+JointNormal
+JointOrderStatistics
+KSDist
+KSOneSided
+KeepActor
+KeepEach
+KeepLast
+Kolmogorov
+Kumaraswamy
+LKJ
+LKJCholesky
+LabeledObservable
+LambdaActor
+Laplace
+LaplaceApproximation
+LastNotFoundException
+LazyObservable
+LeftProposal
+LeftTypedOperator
+LeftTypedOperatorTrait
+Levy
+LimitSubscribersGuard
+Lindley
+Linearization
+LinearizedProductOf
+LocationScale
+LogNormal
+LogUniform
+LoggerActor
+LoggerPipelineStage
+Logistic
+LogitNormal
+MAX_PREGENERATED_MSTORAGE_SIZE
+MILLISECONDS_IN_SECOND
+MLEstimator
+Marginal
+Marginalisation
+MatrixBeta
+MatrixDirichlet
+MatrixDistribution
+MatrixFDist
+MatrixNormal
+MatrixReshaped
+MatrixTDist
+Matrixvariate
+MeanField
+MeanParametersSpace
+MeanToNatural
+Message
+MetaSpecification
+MissingCreateActorFactoryImplementationError
+MissingDataArgumentInNextCall
+MissingErrorArgumentInErrorCall
+MissingOnCallImplementationError
+MissingOnCompleteImplementationError
+MissingOnErrorImplementationError
+MissingOnNextImplementationError
+MissingOnScheduledSubscribeImplementationError
+MissingOnSubscribeImplementationError
+MissingOnUnsubscribeImplementationError
+MissingOperatorRightImplementationError
+Mixture
+MixtureDistribution
+MixtureModel
+MixtureNode
+MomentMatching
+Multinomial
+Multivariate
+MultivariateDistribution
+MultivariateGaussianDistributionsFamily
+MultivariateMixture
+MultivariateNormal
+MultivariateNormalDistributionsFamily
+MvGaussianMeanCovariance
+MvGaussianMeanPrecision
+MvGaussianWeightedMeanPrecision
+MvLogNormal
+MvLogitNormal
+MvNormal
+MvNormalCanon
+MvNormalKnownCov
+MvNormalMeanCovariance
+MvNormalMeanPrecision
+MvNormalMeanScalePrecision
+MvNormalWeightedMeanPrecision
+MvNormalWishart
+MvTDist
+NANOSECONDS_IN_MILLISECOND
+NANOSECONDS_IN_SECOND
+NOT
+NaturalParametersSpace
+NaturalToMean
+NegativeBinomial
+NetworkObservable
+NeverObservable
+NextActor
+NextActorTrait
+NonConstantBaseMeasure
+NonMatrixDistribution
+NoncentralBeta
+NoncentralChisq
+NoncentralF
+NoncentralHypergeometric
+NoncentralT
+NoopPostprocess
+Normal
+NormalCanon
+NormalDistributionsFamily
+NormalGamma
+NormalInverseGaussian
+NormalMeanPrecision
+NormalMeanVariance
+NormalMixture
+NormalMixtureNode
+NormalWeightedMeanPrecision
+OR
+OperatorTrait
+OperatorsComposition
+OrderStatistic
+OverrideHandler
+PGeneralizedGaussian
+Pareto
+PendingScheduler
+PendingSubject
+PendingSubjectFactory
+PermutationLayer
+PermutationMatrix
+PlanarFlow
+PointMass
+Poisson
+PoissonBinomial
+PostponeScheduler
+PreserveTypeLeftProd
+PreserveTypeProd
+PreserveTypeRightProd
+Probit
+ProbitMeta
+ProdCVI
+Product
+ProductOf
+ProxyObservable
+PushEach
+PushEachBut
+PushNew
+PushNewBut
+PushStrategy
+QQPair
+RadialFlow
+RandomVariable
+RandomVariableCreationOptions
+Rayleigh
+ReactiveMP
+RealInterval
+RecentSubject
+RecentSubjectFactory
+ReplaySubject
+ReplaySubjectFactory
+RequireInboundFunctionalDependencies
+Rician
+RightProposal
+RightTypedOperator
+RightTypedOperatorTrait
+Rocket
+RxInfer
+RxInferenceEngine
+RxInferenceEvent
+SampleList
+SampleListMeta
+Sampleable
+ScheduledSubscribable
+ScheduledSubscribableTrait
+Semicircle
+ServerActor
+SimpleSubscribableTrait
+SingleObservable
+Skellam
+SkewNormal
+SkewedExponentialPower
+SkipClamped
+SkipClampedAndInitial
+SkipInitial
+SoftDot
+Soliton
+SourceProxy
+StandardBasisVector
+Stochastic
+StorageActor
+StudentizedRange
+Subject
+SubjectFactory
+SubjectTrait
+Subscribable
+SubscribableTrait
+SubstituteHandler
+SufficientStats
+SymTriangularDist
+SyncActor
+SyncActorTimedOutException
+SyncFileObservable
+TDist
+TapAfterSubscription
+TapAfterUnsubscription
+TapBeforeSubscription
+TapBeforeUnsubscription
+Teardown
+TeardownLogic
+TerminalProdArgument
+TimerObservable
+Transition
+TriangularDist
+Triweight
+Truncated
+TruncatedNormal
+TypedOperator
+TypedOperatorTrait
+UT
+Uniform
+Uninformative
+Univariate
+UnivariateDistribution
+UnivariateGMM
+UnivariateGaussianDistributionsFamily
+UnivariateMixture
+UnivariateNormalDistributionsFamily
+UnpackMarginalPostprocess
+Unscented
+UnscentedTransform
+UnspecifiedConstraints
+UnspecifiedDimension
+UnspecifiedDomain
+UnspecifiedFormConstraint
+UnspecifiedMeta
+UnsubscribableTeardownLogic
+ValidSubjectTrait
+ValueSupport
+VariableBoundEntropy
+VariablesCollection
+VariateForm
+VariationalMessage
+VoidActor
+VoidTeardown
+VoidTeardownLogic
+VonMises
+VonMisesFisher
+WalleniusNoncentralHypergeometric
+Weibull
+Wishart
+WishartDistributionsFamily
+ZeroMeanDiagNormal
+ZeroMeanDiagNormalCanon
+ZeroMeanFullNormal
+ZeroMeanFullNormalCanon
+ZeroMeanIsoNormal
+ZeroMeanIsoNormalCanon
+accumulated
+actor_extract_type
+actor_proxy!
+apply_pipeline_stage
+approximation_name
+approximation_short_name
+as_actor
+as_marginal
+as_message
+as_operator
+as_subject
+as_subscribable
+as_teardown
+as_variable
+async
+basemeasure
+buffer
+call_operator!
+call_operator_composition!
+canonform
+catch_error
+ccdf
+cdf
+censored
+cf
+cgf
+cholinv
+cholinv_logdet
+chollogdet
+cholsqrt
+circularkeep
+circvar
+clamplog
+collectLatest
+combineLatest
+combineLatestUpdates
+compile
+complete!
+completed
+component
+components
+componentwise_logpdf
+componentwise_pdf
+compute_logscale
+concat
+concat_map
+concat_map_to
+concentration
+connect
+connectable
+constrain_form
+constvar
+convert_paramfloattype
+convolve
+cor
+count
+cov
+cquantile
+create_actor
+create_model
+create_subject
+datavar
+debounce_time
+deep_eltype
+default_form_check_strategy
+default_if_empty
+default_prod_constraint
+default_prod_rule
+defer
+degree
+delay
+diageye
+dim
+dimension
+discontinue
+distribution_typewrapper
+dof
+dot
+dtanh
+entropy
+enumerate
+error!
+error_if
+error_if_empty
+error_if_not
+estimate
+exhaust_map
+expected_logdet
+factorisation
+failprob
+fastcholesky
+fastcholesky!
+faulted
+file
+filter
+filter_type
+find
+find_index
+first
+fisherinformation
+fit
+fit_mle
+from
+functional_dependencies
+functionalform
+fuse_supports
+generate
+getapproximation
+getattributes
+getbasemeasure
+getconditioner
+getconst
+getconstant
+getconstraints
+getdata
+getfisherinformation
+getlayers
+getlogpartition
+getlogscale
+getmapping
+getmarginal
+getmarginals
+getmemory
+getmeta
+getmodel
+getnaturalparameters
+getnode_ids
+getnodes
+getoptions
+getprediction
+getpredictions
+getrandom
+getsufficientstatistics
+getsupport
+getvalues
+getvardict
+getvariables
+ghcubature
+gradlogpdf
+hasconstvar
+hasdatavar
+hasfinitesupport
+hasrandomvar
+huge
+ignore
+inference
+insupport
+interfaces
+interval
+invcov
+invlogccdf
+invlogcdf
+invscale
+is_clamped
+is_initial
+is_marginalisation
+is_moment_matching
+is_point_mass_form_constraint
+isbasemeasureconstant
+isbounded
+isconnected
+isdeterministic
+isequal_typeof
+isleptokurtic
+islowerbounded
+ismesokurtic
+isplatykurtic
+isprobvec
+isproper
+isstochastic
+isupperbounded
+iterable
+keep
+kldivergence
+kurtosis
+labeled
+lambda
+laplace
+last
+lazy
+limit_subscribers
+localmarginalnames
+localmarginals
+location
+location!
+logccdf
+logcdf
+logdetcov
+logdiffcdf
+logger
+loglikelihood
+logmvbeta
+logpartition
+logpdf
+logpdf!
+logpdf_optimized
+logpdf_sampling_optimized
+lowercase
+make
+make_form_constraint
+make_node
+map
+map_to
+marginalrule
+max
+mean
+mean_cov
+mean_invcov
+mean_precision
+mean_std
+mean_var
+meandir
+meanform
+meanlogx
+median
+merge_map
+merged
+metadata
+mgf
+min
+mirrorlog
+mode
+model_name
+modes
+moment
+multicast
+mvtrigamma
+name
+ncategories
+ncomponents
+network
+never
+next!
+noop
+nr_params
+nsamples
+ntrials
+of
+on_call!
+on_complete!
+on_error!
+on_next!
+on_subscribe!
+on_unsubscribe!
+operator_right
+override
+pairwise
+parallel
+paramfloattype
+params
+params!
+partype
+pdf
+pdf!
+pdfsquaredL2norm
+precision
+probs
+probval
+probvec
+prod
+prod!
+product_distribution
+promote_paramfloattype
+promote_samplefloattype
+promote_sampletype
+promote_variate_type
+proxy
+publish
+publish_behavior
+publish_recent
+publish_replay
+qqbuild
+quantile
+race
+rand
+rand!
+randomvar
+rate
+reduce
+ref_count
+release!
+rerun
+resolve_prod_strategy
+rule
+rxinference
+safe
+sample
+sample!
+samplefloattype
+sampler
+sampletype
+sampling_optimized
+scale
+scale!
+scan
+schedule_on
+scheduled
+score
+sdtype
+server
+set!
+setTimeout
+setmarginal!
+setmarginals!
+setmessage!
+setmessages!
+shape
+share
+share_recent
+share_replay
+skewness
+skip_complete
+skip_error
+skip_next
+skipindex
+softdot
+some
+source_proxy!
+span
+sqmahal
+sqmahal!
+srcubature
+start_with
+std
+stdlogx
+storage
+subscribable_extract_type
+subscribe!
+substitute
+succprob
+sufficientstatistics
+suffstats
+sum
+support
+switch_map
+switch_map_to
+sync
+take
+take_until
+tap
+tap_on_complete
+tap_on_subscribe
+tap_on_unsubscribe
+teardown!
+throwError
+timer
+tiny
+to_array
+truncated
+tuple_with_left
+tuple_with_right
+unsubscribe!
+update!
+uppercase
+vague
+value_support
+var
+variate_form
+varlogx
+void
+voidTeardown
+weightedmean
+weightedmean_cov
+weightedmean_invcov
+weightedmean_precision
+weightedmean_std
+weightedmean_var
+weights
+with_latest
+wsample
+wsample!
+xtlog
+zipped
diff --git a/v2.15.0/library/functional-forms/index.html b/v2.15.0/library/functional-forms/index.html new file mode 100644 index 000000000..43c42a02a --- /dev/null +++ b/v2.15.0/library/functional-forms/index.html @@ -0,0 +1,26 @@ + +Built-in functional form constraints · RxInfer.jl
GitHub

Built-in Functional Forms

This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.

Custom functional forms

See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.

UnspecifiedFormConstraint

Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.

@constraints begin 
+    q(x) :: Nothing # This is the default setting
+end

PointMassFormConstraint

The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. 

@constraints begin 
+    q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object
+end
RxInfer.PointMassFormConstraint — Type
PointMassFormConstraint

One of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.

Keyword arguments

  • optimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer
  • starting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point
  • boundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries

Custom optimizer callback interface

# This is an example of the `custom_optimizer` interface
+function custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # should return argmin of the -logpdf(distribution)
+end

Custom starting point callback interface

# This is an example of the `custom_starting_point` interface
+function custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # built-in optimizer expects an array, even for a univariate distribution
+    return [ 0.0 ] 
+end

Custom boundaries callback interface

# This is an example of the `custom_boundaries` interface
+function custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # returns a tuple of `lower` and `upper` boundaries
+    return (-Inf, Inf)
+end

Traits

  • is_point_mass_form_constraint = true
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = PointMass (for use in @constraints macro)
source

SampleListFormConstraint

SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.

@constraints begin 
+    q(x) :: SampleList(1000)
+    # or 
+    q(y) :: SampleList(1000, LeftProposal())
+end
RxInfer.SampleListFormConstraint — Type
SampleListFormConstraint(rng, strategy, method)

One of the form constraint objects. Approximates DistProduct with a SampleList object.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = SampleList (for use in @constraints macro)
source
RxInfer.LeftProposal — Type

Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.

source
RxInfer.RightProposal — Type

Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.

source

FixedMarginalFormConstraint

Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.

@constraints function block_updates(x_posterior = nothing) 
+    # `nothing` returns the computed posterior marginal
+    q(x) :: Marginal(x_posterior)
+end
RxInfer.FixedMarginalFormConstraint — Type
FixedMarginalFormConstraint

One of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = Marginal (for use in @constraints macro)
source

CompositeFormConstraint

It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:

form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()
@constraints begin 
+    q(x) :: SampleList(1000) :: PointMass()
+end
diff --git a/v2.15.0/library/model-specification/index.html b/v2.15.0/library/model-specification/index.html new file mode 100644 index 000000000..790e55b8e --- /dev/null +++ b/v2.15.0/library/model-specification/index.html @@ -0,0 +1,4 @@ + +Model specification · RxInfer.jl
GitHub

Model specification in RxInfer

RxInfer.@model — Macro
@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model description
+end

@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.

Supported alias in the model specification

  • a || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).
  • a && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • a -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • ¬a and !a: alias for NOT(a) node (Unicode \neg, operator precedence ||, &&, -> and ! is the same as in Julia).
  • a + b + c: alias for (a + b) + c
  • a * b * c: alias for (a * b) * c
  • Normal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.
  • Normal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.
  • MvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • Gamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.
  • Gamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.
source
RxInfer.ModelGenerator — Type
ModelGenerator

ModelGenerator is a special object that is used in the inference function to lazily create model later on given constraints, meta and options.

See also: inference

source
RxInfer.create_model — Function
create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)

Creates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.

Returns a tuple of 2 values:

    1. an instance of FactorGraphModel
    1. return value from the @model macro function definition
source
RxInfer.ModelInferenceOptions — Type
ModelInferenceOptions(; kwargs...)

Creates model inference options object. The list of available options is present below.

Options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.
  • warn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.

Advanced options

  • pipeline: changes the default pipeline for each factor node in the graph
  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

See also: inference, rxinference

source
diff --git a/v2.15.0/manuals/background/index.html b/v2.15.0/manuals/background/index.html new file mode 100644 index 000000000..9820f73ca --- /dev/null +++ b/v2.15.0/manuals/background/index.html @@ -0,0 +1,2 @@ + +Background: variational inference · RxInfer.jl
GitHub
diff --git a/v2.15.0/manuals/comparison/index.html b/v2.15.0/manuals/comparison/index.html new file mode 100644 index 000000000..5968ec4d1 --- /dev/null +++ b/v2.15.0/manuals/comparison/index.html @@ -0,0 +1,28 @@ + +RxInfer.jl vs. Others · RxInfer.jl
GitHub

Comparison to other packages

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.

DISCLAIMER:

  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, and we'll be more than willing to rectify.
  2. The comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.
ToolboxUniversalityEfficiencyExpressivenessDebugging & VisualizationModularityInference EngineLanguageCommunity & Ecosystem
RxInfer.jl~✓✓~✗Message-passingJulia✗
ForneyLab.jl✗~✗~✗Message-passingJulia✗
Infer.net~✓✗✓✗Message-passingC#✗
PGMax✗✓✗✓✗Message-passingPython✗
Turing.jl✓✗✓~✗SamplingJulia✓
PyMC✓✗✓✓✗SamplingPython✓
NumPyro✓✓~✓✗SamplingPython✓
TensorFlow Probability✓✗~✓✗SamplingPython✓
Stan✓✗✓✓✗SamplingStan✓

(Date of creation: 20/10/2023)

Legend

  • ✓ : Full capability or feature is present.
  • ~ : Partial capability or feature is present.
  • ✗ : No capability or feature.

Notes:

  • Universality: Denotes the capability to depict a vast array of probabilistic models.
  • Efficiency: Highlights computational competence. A "–" in this context suggests perceived slowness.
  • Expressiveness: Assesses the ability to concisely formulate intricate probabilistic models.
  • Debugging & Visualization: Evaluates the suite of tools for model debugging and visualization.
  • Modularity: Reflects the potential to create models by integrating smaller models.
  • Inference Engines: Pinpoints the primary inference strategy employed by the toolbox.
  • Language: Identifies the programming language integral to the toolbox.
  • Community & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.

RxInfer.jl breakdown

  • Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.

  • Efficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.

  • Modularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:

@model function inner_inner(τ, y)
+    y ~ Normal(τ[1], τ[2])
+end
+
+@model function inner(θ, α)
+    β ~ Normal(0, 1)
+    α ~ Gamma(β, 1)
+    α ~ inner_inner(τ = θ)
+end
+
+@model function outer()
+    local w
+    for i = 1:5
+        w[i] ~ inner(θ = Gamma(1, 1))
+    end
+    y ~ inner(θ = w[2:3])
+end
  • Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(0.0, 1.0)\\ + w & \sim \mathrm{InverseGamma}(1.0, 1.0)\\ + y & \sim \mathrm{Normal}(x, w) +\end{aligned}\]

The model then is expressed in RxInfer.jl as follows:

using RxInfer
+
+@model function example_model()
+    x ~ Normal(mean=0.0, var=1.0)
+    w ~ InverseGamma(α = 1, θ = 1)
+    y ~ Normal(mean = x, var = w)
+end
  • Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.
diff --git a/v2.15.0/manuals/constraints-specification/index.html b/v2.15.0/manuals/constraints-specification/index.html new file mode 100644 index 000000000..a524b412f --- /dev/null +++ b/v2.15.0/manuals/constraints-specification/index.html @@ -0,0 +1,111 @@ + +Constraints specification · RxInfer.jl
GitHub

Constraints Specification

RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.

using RxInfer

General syntax

@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:


+# `functional` style
+@constraints function create_my_constraints(arg1, arg2)
+    ...
+end
+
+# `block` style
+myconstraints = @constraints begin 
+    ...
+end
+

In the first case it returns a function that return constraints upon calling, e.g. 

@constraints function make_constraints(mean_field)
+    q(x) :: PointMass
+
+    if mean_field
+        q(x, y) = q(x)q(y)
+    end
+end
+
+myconstraints = make_constraints(true)
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

and in the second case it evaluates automatically and returns constraints object directly.

myconstraints = @constraints begin
+    q(x) :: PointMass
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

Options specification

@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

myconstraints = @constraints [ warn = false ] begin 
+   ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/constraints specification

Marginal and messages form constraints

To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)

The following constraint:

@constraints begin
+    q(x) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:

\[\mathrm{approximate~} q(x) = \frac{\overrightarrow{\mu}(x)\overleftarrow{\mu}(x)}{\int \overrightarrow{\mu}(x)\overleftarrow{\mu}(x) \mathrm{d}x}\mathrm{~as~PointMass}\]

Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):

@constraints begin
+    q(x) :: PointMass
+    μ(x) :: SampleList(1000)
+    # it is possible to assign different form constraints on the same variable
+    # both for the marginal and for the messages
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+    μ(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) [ prod_constraint = GenericProd() ]
+  factorisation:
+Options:
+  warn = true
+

@constraints macro understands "stacked" form constraints. For example the following form constraint

@constraints begin
+    q(x) :: SampleList(1000) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass.

Note

Not all combinations of "stacked" form constraints are compatible between each other.

You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.

Factorisation constraints on posterior distribution q()

@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:

For example:

@constraints begin
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.

@constraints begin
+    q(x) = q(x[begin])..q(x[end])
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x) = q(x[(begin)..(end)])
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables $x_i$.

Note

@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])

It is possible to write more complex factorisation constraints, for example:

@constraints begin
+    q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x[(begin)..(end)], y[(begin)..(end)])
+Options:
+  warn = true
+

specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is

@constraints function make_constraints(k)
+    q(x) = q(x[begin:k])q(x[k+1:end])
+end
make_constraints (generic function with 1 method)

In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end].

To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+constraints = @constraints begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); constraints = constraints)

Alternatively, it is possible to use constraints directly in the automatic inference and rxinference functions that accepts constraints keyword argument.

diff --git a/v2.15.0/manuals/custom-node/1267bbbc.svg b/v2.15.0/manuals/custom-node/1267bbbc.svg new file mode 100644 index 000000000..9242bc9fc --- /dev/null +++ b/v2.15.0/manuals/custom-node/1267bbbc.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/custom-node/index.html b/v2.15.0/manuals/custom-node/index.html new file mode 100644 index 000000000..90fb87a20 --- /dev/null +++ b/v2.15.0/manuals/custom-node/index.html @@ -0,0 +1,86 @@ + +Defining a custom node and rules · RxInfer.jl
GitHub

Creating your own custom nodes

Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.

To create a custom node in RxInfer, 4 steps are required:

  1. Create your custom node in RxInfer using the @node macro.
  2. Define the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.
  3. Specify computations for marginal distributions of the relevant variables with the @marginalrule macro.
  4. Implement the computation of the Free Energy in a node with the @average_energy macro.

Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!

Problem statement

Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin $K=20$ times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment $x_k\in\{0,1\}$ using the Bernoulli distribution as

\[p(x_k \mid \pi) = \mathrm{Ber}(x_k \mid \pi) = \pi^{x_k} (1-\pi)^{1-x_k},\]

where $\pi \in[0,1]$ denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of $\pi$ which she models using the Beta distribution as

\[p(\pi) = \mathrm{Beta}(\pi \mid 4, 8).\]

With this prior belief, the total probabilistic model that she has for this experiment is given by

\[p(x_{1:K}, \pi) = p(\pi) \prod_{k=1}^K p(x_k \mid \pi).\]

Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of $\pi$, $p(\pi \mid x_{1:K})$, denoting how $\pi$ is distributed after we have seen the data.

Step 1: Creating the custom node

Note

In this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.

First things first, let's import RxInfer:

using RxInfer

In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:

  1. The name of the node. (::Type)
  2. Whether the node is Deterministic or Stochastic.
  3. The interfaces of the node and any potential aliases. (::Vector)

For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as

# struct for Bernoulli distribution with success probability π
+struct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution
+    π :: T
+    new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError("π must be between 0 and 1"))
+end
+
+# for simplicity, let's also specify the mean of the distribution
+Distributions.mean(d::MyBernoulli) = d.π

In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.

Note

You can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)

For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of $\pi$, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.

The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.

Concluding, we can create the MyBernoulli factor node as

@node MyBernoulli Stochastic [out, (π, aliases = [p])]

Cool! Step 1 is done, we have created a custom node.

Step 2: Defining rules for our node

In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as $p(\pi\mid x_{1:K})$, we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.

Sum-product message passing update rules

In sum-product message passing we compute outgoing messages to our node as

\[\vec{\mu}(x) \propto \int \mathrm{Ber}(x\mid \pi) \vec{\mu}(\pi) \mathrm{d}x\]

\[\overleftarrow{\mu}(\pi) \propto \sum_{x \in \{0,1\}} \mathrm{Ber}(x\mid \pi) \overleftarrow{\mu}(x)\]

This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.

For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain $\pi = \frac{\alpha}{\alpha + \beta}$, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as

@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))

Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for "the incoming message on interface π". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.

The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):

@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))

Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:

\[\overleftarrow{\mu}(π) \propto \mathrm{Beta}(1 + x, 2 - x)\]

Which gives us the following update rule:

@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin
+    p = mean(m_out)
+    Beta(one(p) + p, 2one(p) - p)
+end

Variational message passing update rules

We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as

\[\vec{\nu}(x) \propto \exp \int q(\pi) \ln \mathrm{Ber}(x\mid \pi) \mathrm{d}x\]

\[\overleftarrow{\nu}(\pi) \propto \exp \sum_{x \in \{0,1\}} q(x) \ln \mathrm{Ber}(x\mid \pi)\]

These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.

#rules towards out
+@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))
+
+@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin
+    rho_1 = mean(log, q_π)          # E[ln(x)]
+    rho_2 = mean(mirrorlog, q_π)    # E[log(1-x)]
+    m = max(rho_1, rho_2)
+    tmp = exp(rho_1 - m)
+    p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))
+    return Bernoulli(p)
+end
+
+#rules towards π
+@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin
+    p = mean(q_out)
+    return Beta(one(p) + p, 2one(p) - p)
+end
Node

Typically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.

In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.

Step 3: Defining joint marginals for our node

The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by

\[F[q,f] = - \sum_{a\in\mathcal{V}} \mathrm{H}[q_a(s_a)] - \sum_{a\in\mathcal{V}}\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)] + \sum_{i\in\mathcal{E}}\mathrm{H}[q_i(s_i)]\]

Here we call $q_a(s_a)$ the joint marginals around a node and $-\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)]$ we term the average energy.

In order to be able to compute the Bethe free energy, we need to first describe how to compute $q_a(s_a)$, defined in our case as

\[q(x_k, \pi) = \vec{\mu}(\pi) \overleftarrow{\mu}(x_k) \mathrm{Ber}(x_k \mid \pi)\]

To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:

@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin
+    r = mean(m_out)
+    p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)
+    return (out = m_out, p = p)
+end

In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as $q(x_k, \pi) = q(x_k)q(\pi)$. These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing $q(\pi)$ we need to compute the product $\vec{\mu}(\pi)\overleftarrow{\mu}(\pi)$. We already know how $\overleftarrow{\mu}(\pi)$ looks like from the previous step, so we can just use the prod function.

Step 4: Defining the average energy for our node

To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as $-\mathrm{E}_{q(x_k, \pi)}[\ln p(x_k \mid \pi)]$, however, because we know that we observe $x_k$ and therefore $q(x_k, \pi)$ factorizes, we can instead compute $\begin{aligned} -\mathrm{E}_{q(x_k)q(\pi)}[\ln p(x_k \mid \pi)] &= -\mathrm{E}_{q(x_k)q(\pi)} [\ln (\pi^{x_k} (1-\pi)^{1 - x_k})] \\ +&= -\mathrm{E}_{q(x_k)q(\pi)} [x_k \ln(\pi) + (1-x_k) \ln(1-\pi)] \\ +&= -\mathrm{E}_{q(x_k)}[x_k] \mathrm{E}_{q(\pi)} [\ln(\pi)] - (1-\mathrm{E}_{q(x_k)}[x_k]) \mathrm{E}_{q(\pi)}[\ln(1-\pi)] \end{aligned}$

Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to $\mathrm{E}_{q(x)}[1-\log{x}]$.

@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)

In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....

Using our node in a model

With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:

using Random
+
+rng = MersenneTwister(42)
+n = 500
+π_real = 0.75
+distribution = Bernoulli(π_real)
+
+dataset = float.(rand(rng, distribution, n))

Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:

@model function coin_model_mybernoulli(n)
+
+    # `datavar` creates data 'inputs' in our model
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    π ~ Beta(4.0, 8.0)
+
+    # We assume that outcome of each coin flip is governed by the MyBernoulli distribution
+    for i in 1:n
+        y[i] ~ MyBernoulli(π)
+    end
+
+end

Finally, we can run inference with this model and the generated dataset:

result_mybernoulli = inference(
+    model = coin_model_mybernoulli(length(dataset)),
+    data  = (y = dataset, ),
+)
Inference results:
+  Posteriors       | available for (π)
+

We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.

using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label="p(π|x)", c=3)
+vline!([π_real], label="Real π")
Example block output

As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.

@model function coin_model(n)
+
+    y = datavar(Float64, n)
+    p ~ Beta(4.0, 8.0)
+
+    for i in 1:n
+        y[i] ~ Bernoulli(p)
+    end
+
+end
+
+result_bernoulli = inference(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, ),
+)
+
+if !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])
+    error("Results are not identical")
+else
+    println("Results are identical 🎉🎉🎉")
+end
Results are identical 🎉🎉🎉

Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.

diff --git a/v2.15.0/manuals/debugging/1e3146e9.svg b/v2.15.0/manuals/debugging/1e3146e9.svg new file mode 100644 index 000000000..9fcbbd005 --- /dev/null +++ b/v2.15.0/manuals/debugging/1e3146e9.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/debugging/56384dfe.svg b/v2.15.0/manuals/debugging/56384dfe.svg new file mode 100644 index 000000000..6056017f6 --- /dev/null +++ b/v2.15.0/manuals/debugging/56384dfe.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/debugging/index.html b/v2.15.0/manuals/debugging/index.html new file mode 100644 index 000000000..d520d84bf --- /dev/null +++ b/v2.15.0/manuals/debugging/index.html @@ -0,0 +1,60 @@ + +Debugging · RxInfer.jl
GitHub

Debugging

Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. 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

We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a "Memory Addon". Below is an example explaining how you can extract this history and use it to fix a bug.

Consider the coin toss example from earlier in the documentation. We model the binary outcome $x$ (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the $\theta$ parameter, with a known shape 𝑎 and rate 𝑏 parameter.

\[x_i \sim \mathrm{Bernoulli}(\theta)\]

\[\theta \sim \mathrm{Beta}(a, b)\]

where $x_i \in {0, 1}$ are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:

using RxInfer, Random, Plots
+
+n = 4
+θ_real = 0.3
+dataset = convert.(Int64, rand(Bernoulli(θ_real), n))
+
+@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, huge)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = inference(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+

The model will run without errors. But when we plot the posterior distribution for $\theta$, something's wrong. The posterior seems to be a flat distribution:

rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.

result = inference(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+    addons = (AddonMemory(),)
+)
Inference results:
+  Posteriors       | available for (θ)
+

Now we have access to the messages that led to the marginal posterior:

Addons_messages

The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:

\[\underbrace{\overrightarrow{\mu}_{θ}(θ)}_{\substack{ \text{outgoing}\\ \text{message}}} = \sum_{x_1,\ldots,x_n} \underbrace{\overrightarrow{\mu}_{X_1}(x_1)\cdots \overrightarrow{\mu}_{X_n}(x_n)}_{\substack{\text{incoming} \\ \text{messages}}} \cdot \underbrace{f(θ,x_1,\ldots,x_n)}_{\substack{\text{node}\\ \text{function}}}\]

Graph

Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of $\theta$ we used in the code block above. So why does the posterior have this rate parameter?

All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.

@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, 100)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = inference(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+
rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

Now the posterior is visible in the plot.

diff --git a/v2.15.0/manuals/delta-node/index.html b/v2.15.0/manuals/delta-node/index.html new file mode 100644 index 000000000..c0deb165a --- /dev/null +++ b/v2.15.0/manuals/delta-node/index.html @@ -0,0 +1,59 @@ + +Delta node · RxInfer.jl
GitHub

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.

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:

  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.
  3. Stacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.

The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:

MethodsGaussian NodesExponential Family NodesStacking Delta Nodes
Linearization✓✗✓
Unscented✓✗✓
CVI✓✓✗

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.

For clarity, consider the following example:

using RxInfer
+
+@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=0.0, var=1.0)
+    y ~ tanh(x)
+    z ~ Normal(mean=y, var=1.0)
+end

To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:

delta_meta = @meta begin
+    tanh() -> Linearization()
+end
Meta specification:
+  tanh() -> Linearization()
+Options:
+  warn = true

or

delta_meta = @meta begin
+    tanh() -> Unscented()
+end
Meta specification:
+  tanh() -> Unscented{Float64, Float64, Float64, Nothing}(0.001, 2.0, 0.0, nothing)
+Options:
+  warn = true

For a deeper understanding of the Unscented method and its parameters, consult the docstrings.

Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:

delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)
+end
Meta specification:
+  tanh() -> DeltaMeta{Linearization, typeof(atanh)}(Linearization(), atanh)
+Options:
+  warn = true

To execute the inference procedure:

inference(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))
Inference results:
+  Posteriors       | available for (y, x)
+

This methodology is consistent even when the delta node is associated with multiple nodes. For instance:

f(x, g) = x*tanh(g)
f (generic function with 1 method)
@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=1.0, var=1.0)
+    g ~ Normal(mean=1.0, var=1.0)
+    y ~ f(x, g)
+    z ~ Normal(mean=y, var=0.1)
+end

The corresponding meta specification is:

delta_meta = @meta begin
+    f() -> DeltaMeta(method = Linearization())
+end
Meta specification:
+  f() -> DeltaMeta{Linearization, Nothing}(Linearization(), nothing)
+Options:
+  warn = true

or simply

delta_meta = @meta begin
+    f() -> Linearization()
+end
Meta specification:
+  f() -> Linearization()
+Options:
+  warn = true

If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:

delta_meta = @meta begin 
+    f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))
+end

Exponential Family Case

When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:

using RxInfer
+
+@model function delta_node_example1()
+    z = datavar(Float64)
+    x ~ Gamma(shape=1.0, rate=1.0)
+    y ~ tanh(x)
+    z ~ Bernoulli(y)
+end

The corresponding meta specification can be represented as:

using StableRNGs
+using Optimisers
+
+delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))
+end
Meta specification:
+  tanh() -> DeltaMeta{ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}, Nothing}(ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}(StableRNGs.LehmerRNG(state=0x00000000000000000000000000000055), 100, 100, Optimisers.Descent{Float64}(0.01), ForwardDiffGrad{0}(), 1, Val{true}(), true), nothing)
+Options:
+  warn = true

Consult the ProdCVI docstrings for a detailed explanation of these parameters.

diff --git a/v2.15.0/manuals/getting-started/379afd7d.svg b/v2.15.0/manuals/getting-started/379afd7d.svg new file mode 100644 index 000000000..5f89cf6ca --- /dev/null +++ b/v2.15.0/manuals/getting-started/379afd7d.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/getting-started/f41ad4cd.svg b/v2.15.0/manuals/getting-started/f41ad4cd.svg new file mode 100644 index 000000000..26de5dc45 --- /dev/null +++ b/v2.15.0/manuals/getting-started/f41ad4cd.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/getting-started/index.html b/v2.15.0/manuals/getting-started/index.html new file mode 100644 index 000000000..10c45ae51 --- /dev/null +++ b/v2.15.0/manuals/getting-started/index.html @@ -0,0 +1,91 @@ + +Getting started · RxInfer.jl
GitHub

Getting started

RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.

RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.

This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.

Installation

Install RxInfer through the Julia package manager:

] add RxInfer

Importing RxInfer

To add RxInfer package (and all associated packages) into a running Julia session simply run:

using RxInfer

Read more about about using in the Using methods from RxInfer section of the documentation.

Example: Inferring the bias of a coin

The RxInfer approach to solving inference problems consists of three phases:

  1. Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.
  2. Inference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.
  3. Inference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.

Coin flip simulation

Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).

First let's setup our environment by importing all needed packages:

using RxInfer, Distributions, Random

Next, let's define our dataset:

rng = MersenneTwister(42)
+n = 10
+p = 0.75
+distribution = Bernoulli(p)
+
+dataset = float.(rand(rng, Bernoulli(p), n))
10-element Vector{Float64}:
+ 1.0
+ 1.0
+ 1.0
+ 1.0
+ 0.0
+ 0.0
+ 1.0
+ 1.0
+ 0.0
+ 1.0

Model specification

In 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.

Likelihood

We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.

\[y_i \sim \mathrm{Bernoulli}(\theta),\]

where $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]$.

Prior

We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.

\[\theta \sim Beta(a, b),\]

where $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.

Joint probability

The joint probability is given by the multiplication of the likelihood and the prior, i.e.

\[P(y_{1:N}, θ) = P(θ) \prod_{i=1}^N P(y_i | θ).\]

Now let's see how to specify this model using GraphPPL's package syntax.

# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during inference step
+    return y, θ
+end

As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create "clamped" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Inference specification

Automatic inference specification

Once 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 inference function that supports static datasets.

result = inference(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
+
θestimated = result.posteriors[:θ]
Beta{Float64}(α=9.0, β=10.0)
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803

Read more information about the inference function in the Static Inference documentation section.

Manual inference specification

There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:

  1. Return variables of interests from model specification
  2. Subscribe on variables of interests posterior marginal updates
  3. Pass data to the model
  4. Unsubscribe

Here is an example of inference procedure:

function custom_inference(data)
+    n = length(data)
+
+    # `coin_model` function from `@model` macro returns a reference to the model generator object
+    # we need to use the `create_model` function to get actual model object
+    model, (y, θ) = create_model(coin_model(n))
+
+    # Reference for future posterior marginal
+    mθ = nothing
+
+    # `getmarginal` function returns an observable of future posterior marginal updates
+    # We use `Rocket.jl` API to subscribe on this observable
+    # As soon as posterior marginal update is available we just save it in `mθ`
+    subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)
+
+    # `update!` function passes data to our data inputs
+    update!(y, data)
+
+    # It is always a good practice to unsubscribe and to
+    # free computer resources held by the subscription
+    unsubscribe!(subscription)
+
+    # Here we return our resulting posterior marginal
+    return mθ
+end
custom_inference (generic function with 1 method)

Inference execution

Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.

θestimated = custom_inference(dataset)
Marginal(Beta{Float64}(α=9.0, β=10.0))
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title="Prior", fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+p2 = plot(rθ, (x) -> pdf(θestimated, x), title="Posterior", fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+
+plot(p1, p2, layout = @layout([ a; b ]))
Example block output

In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:

dataset_100   = float.(rand(rng, Bernoulli(p), 100))
+dataset_1000  = float.(rand(rng, Bernoulli(p), 1000))
+dataset_10000 = float.(rand(rng, Bernoulli(p), 10000))
θestimated_100   = custom_inference(dataset_100)
+θestimated_1000  = custom_inference(dataset_1000)
+θestimated_10000 = custom_inference(dataset_10000)
p3 = plot(title = "Posterior", legend = :topleft)
+
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_100)", c = 4)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_1000)", c = 5)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_10000)", c = 6)
+
+plot(p1, p3, layout = @layout([ a; b ]))
Example block output

With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.

println("mean: ", mean(θestimated_10000))
+println("std:  ", std(θestimated_10000))
mean: 0.7529223698671196
+std:  0.004310967761308469

Where to go next?

There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.

diff --git a/v2.15.0/manuals/inference/inference/index.html b/v2.15.0/manuals/inference/inference/index.html new file mode 100644 index 000000000..e3b598c83 --- /dev/null +++ b/v2.15.0/manuals/inference/inference/index.html @@ -0,0 +1,60 @@ + +Static dataset · RxInfer.jl
GitHub

Automatic inference specification on static datasets

RxInfer exports the inference function to quickly run and test you model with static datasets. Note, however, that this function does cover almost all capabilities of the inference engine, but for advanced use cases you may want to resort to the manual inference specification.

For running inference on real-time datasets see the Reactive Inference section. For manual inference specification see the Manual Inference section.

RxInfer.inference — Function
inference(
+    model; 
+    data,
+    initmarginals           = nothing,
+    initmessages            = nothing,
+    constraints             = nothing,
+    meta                    = nothing,
+    options                 = nothing,
+    returnvars              = nothing, 
+    predictvars             = nothing, 
+    iterations              = nothing,
+    free_energy             = false,
+    free_energy_diagnostics = BetheFreeEnergyDefaultChecks,
+    showprogress            = false,
+    callbacks               = nothing,
+    addons                  = nothing,
+    postprocess             = DefaultPostprocess()
+)

This function provides a generic way to perform probabilistic inference in RxInfer.jl. Returns InferenceResult.

Arguments

For more information about some of the arguments, please check below.

  • model: specifies a model generator, required
  • data: NamedTuple or Dict with data, required
  • initmarginals = nothing: NamedTuple or Dict with initial marginals, optional
  • initmessages = nothing: NamedTuple or Dict with initial messages, optional
  • constraints = nothing: constraints specification object, optional, see @constraints
  • meta = nothing: meta specification object, optional, may be required for some models, see @meta
  • options = nothing: model creation options, optional, see ModelInferenceOptions
  • returnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information
  • predictvars = nothing: return structure info, optional, see below for more information
  • iterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information
  • free_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl
  • free_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.
  • showprogress = false: show progress module, optional, defaults to false
  • callbacks = nothing: inference cycle callbacks, optional, see below for more info
  • addons = nothing: inject and send extra computation information along messages, see below for more info
  • postprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info
  • warn = true: enables/disables warnings

Note on NamedTuples

When passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.

Extended information about some of the arguments

  • model

The model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:

@model function coin_toss(some_argument, some_keyword_argument = 3)
+   ...
+end
+
+result = inference(
+    model = coin_toss(some_argument; some_keyword_argument = 3)
+)

Note: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.

  • data

The data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.

Note: The behavior of the data keyword argument is different from that which is used in the rxinference function.

  • initmarginals

For specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as

inference(...
+    initmarginals = (
+        # initialize the marginal distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)

This argument needs to be a named tuple, i.e. initmarginals = (a = ..., ), or dictionary.

  • initmessages

For specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the initmessages argument, such as

inference(...
+    initmessages = (
+        # initialize the messages distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)

This argument needs to be a named tuple, i.e. initmessages = (a = ..., ), or dictionary.

  • options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for large models, but reduces the performance of the inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.

  • pipeline: changes the default pipeline for each factor node in the graph

  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

  • returnvars

returnvars specifies the variables of interests and the amount of information to return about their posterior updates.

returnvars accepts a NamedTuple or Dict or return var specification. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Note: if iterations are specified as a number, the inference function tracks and returns every update for each iteration for every random variable in the model (equivalent to KeepEach()). If number of iterations is set to nothing, the inference function saves the 'last' (and the only one) update for every random variable in the model (equivalent to KeepLast()). Use iterations = 1 to force KeepEach() setting when number of iterations is equal to 1 or set returnvars = KeepEach() manually.

Example: 

result = inference(
+    ...,
+    returnvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    )
+)

It is also possible to set either returnvars = KeepLast() or returnvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.

Example:

result = inference(
+    ...,
+    returnvars = KeepLast()
+)
  • predictvars

predictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.

Similar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = inference(
+    ...,
+    predictvars = (
+        o = KeepLast(),
+        τ = KeepEach()
+    )
+)
  • iterations

Specifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration.

  • free_energy

This setting specifies whenever the inference function should return Bethe Free Energy (BFE) values. Note, however, that it may be not possible to compute BFE values for every model.

Additionally, the argument may accept a floating point type, instead of a Bool value. Using his option, e.g.Float64, improves performance of Bethe Free Energy computation, but restricts using automatic differentiation packages.

  • free_energy_diagnostics

This settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.

  • callbacks

The inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.

result = inference(
+    ...,
+    callbacks = (
+        on_marginal_update = (model, name, update) -> println("$(name) has been updated: $(update)"),
+        after_inference    = (args...) -> println("Inference has been completed")
+    )
+)

The callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks and their arguments is present below:

  • on_marginal_update: args: (model::FactorGraphModel, name::Symbol, update)
  • before_model_creation: args: ()
  • after_model_creation: args: (model::FactorGraphModel, returnval)
  • before_inference: args: (model::FactorGraphModel)
  • before_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool
  • before_data_update: args: (model::FactorGraphModel, data)
  • after_data_update: args: (model::FactorGraphModel, data)
  • after_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool
  • after_inference: args: (model::FactorGraphModel)

before_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.

  • addons

The addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.

  • postprocess

The postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.

  • catch_exception

The catch_exception keyword argument specifies whether exceptions during the inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.

See also: InferenceResult, rxinference

source
RxInfer.InferenceResult — Type
InferenceResult

This structure is used as a return value from the inference function.

Public Fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for inference.
  • free_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for inference.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.
  • error: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for inference.

See also: inference

source
diff --git a/v2.15.0/manuals/inference/manual/02a3c4a6.svg b/v2.15.0/manuals/inference/manual/02a3c4a6.svg new file mode 100644 index 000000000..f5675c0da --- /dev/null +++ b/v2.15.0/manuals/inference/manual/02a3c4a6.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/inference/manual/1139e325.svg b/v2.15.0/manuals/inference/manual/1139e325.svg new file mode 100644 index 000000000..d1ca76f46 --- /dev/null +++ b/v2.15.0/manuals/inference/manual/1139e325.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/inference/manual/28a97407.svg b/v2.15.0/manuals/inference/manual/28a97407.svg new file mode 100644 index 000000000..ebf0ae5c4 --- /dev/null +++ b/v2.15.0/manuals/inference/manual/28a97407.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.15.0/manuals/inference/manual/index.html b/v2.15.0/manuals/inference/manual/index.html new file mode 100644 index 000000000..49fab321f --- /dev/null +++ b/v2.15.0/manuals/inference/manual/index.html @@ -0,0 +1,103 @@ + +Manual inference specification · RxInfer.jl
GitHub

Manual inference

For advanced use cases it is advised to use manual inference specification.

Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:

  1. Create a model with @model macro and get a references to random variables and data inputs
  2. Subscribe to random variable posterior marginal updates
  3. Subscribe to Bethe Free Energy updates (optional)
  4. Feed model with observations
  5. Unsubscribe from posterior marginal updates (optional)

It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.

Model creation

During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.

using RxInfer, Distributions, Random
+
+@model function my_model()
+    m2 ~ NormalMeanVariance(0.0, 1.0)
+    m1 ~ NormalMeanVariance(m2, 1.0)
+
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(m1, 1.0)
+
+    # Return variables of interests, optional
+    return m1, y
+end

And later on we may create our model with the create_model function and obtain references for variables of interests:

model, (m1, y) = create_model(my_model())

Alternatively, it is possible to query any variable using squared brackets on model object:

model[:m1] # m1
+model[:y]  # y

@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.

Posterior marginal updates

The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.

We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:

m1_posterior_updates = getmarginal(m1)

After that we can subscribe on new updates and perform some actions based on new values:

m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin
+    println("New posterior for m1: ", new_posterior)
+end)

Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.

@model function my_model()
+    ...
+    m_n = randomvar(n)
+    ...
+    return m_n, ...
+end
+
+model, (m_n, ...) = create_model(my_model())
+
+m_n_updates = getmarginals(m_n)

Feeding observations

By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.

To feed an observation for a specific data input we use update! function:

update!(y, 0.0)
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:

update!(y, 0.0) # Observation didn't change, should result in the same posterior
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

If y is an array of data inputs it is possible to pass an array of observation to update! function:

for i in 1:length(data)
+    update!(y[i], data[i])
+end
+# is an equivalent of
+update!(y, data)

Variational Message Passing

Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.

using RxInfer, Distributions, Random
real_mean      = -4.0
+real_precision = 0.2
+rng            = MersenneTwister(1234)
+
+n    = 100
+data = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)
@model function normal_estimation(n)
+    m ~ NormalMeanVariance(0.0, 10.0)
+    w ~ Gamma(0.1, 10.0)
+
+    y = datavar(Float64, n)
+
+    for i in 1:n
+        y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }
+    end
+
+    return m, w, y
+end

We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:

model, (m, w, y) = create_model(normal_estimation(n))
+
+# We use vague initial marginals
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))

To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:

m_marginals = []
+w_marginals = []
+
+subscriptions = subscribe!([
+    (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),
+    (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),
+])
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(subscriptions)

As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.

using Plots
+
+p1    = plot(title = "'Mean' posterior marginals")
+grid1 = -6.0:0.01:4.0
+
+for iter in [ 1, 2, 10 ]
+
+    estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = "Estimated mean after $iter VMP iterations")
+
+end
+
+plot!(p1, [ real_mean ], seriestype = :vline, label = "Real mean", color = :red4, opacity = 0.7)
Example block output
p2    = plot(title = "'Precision' posterior marginals")
+grid2 = 0.01:0.001:0.35
+
+for iter in [ 2, 3, 10 ]
+
+    estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = "Estimated precision after $iter VMP iterations")
+
+end
+
+plot!(p2, [ real_precision ], seriestype = :vline, label = "Real precision", color = :red4, opacity = 0.7)
Example block output

Computing Bethe Free Energy

VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.

The RxInfer package exports score function for an observable of free energy values:

fe_observable = score(model, BetheFreeEnergy())
# Reset posterior marginals for `m` and `w`
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))
+
+fe_values = []
+
+fe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(fe_subscription)
plot(fe_values, label = "Bethe Free Energy", xlabel = "Iteration #")
Example block output
diff --git a/v2.15.0/manuals/inference/overview/index.html b/v2.15.0/manuals/inference/overview/index.html new file mode 100644 index 000000000..28a9b6043 --- /dev/null +++ b/v2.15.0/manuals/inference/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Inference execution

The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):

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.

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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.

Automatic inference specification on static datasets

RxInfer exports the inference function to quickly run and test you model with static datasets. See more information about the inference function on the separate documentation section.

Automatic inference specification on real-time datasets

RxInfer exports the rxinference function to quickly run and test you model with dynamic and potentially real-time datasets. See more information about the rxinference function on the separate documentation section.

Manual inference specification

While both inference and rxinference use most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.

diff --git a/v2.15.0/manuals/inference/postprocess/index.html b/v2.15.0/manuals/inference/postprocess/index.html new file mode 100644 index 000000000..ca8ad6821 --- /dev/null +++ b/v2.15.0/manuals/inference/postprocess/index.html @@ -0,0 +1,2 @@ + +Inference results postprocessing · RxInfer.jl
GitHub

Inference results postprocessing

Both inference and rxinference allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:

diff --git a/v2.15.0/manuals/inference/rxinference/index.html b/v2.15.0/manuals/inference/rxinference/index.html new file mode 100644 index 000000000..942d2942c --- /dev/null +++ b/v2.15.0/manuals/inference/rxinference/index.html @@ -0,0 +1,120 @@ + +Real-time dataset / reactive inference · RxInfer.jl
GitHub

Automatic inference specification on real-time datasets

RxInfer exports the rxinference function to quickly run and test you model with dynamic and potentially real-time datasets. Note, however, that this function does cover almost all capabilities of the reactive inference engine, but for advanced use cases you may want to resort to the manual inference specification.

For running inference on static datasets see the Static Inference section. For manual inference specification see the Manual Inference section.

RxInfer.rxinference — Function
rxinference(
+    model,
+    data = nothing,
+    datastream = nothing,
+    initmarginals = nothing,
+    initmessages = nothing,
+    autoupdates = nothing,
+    constraints = nothing,
+    meta = nothing,
+    options = nothing,
+    returnvars = nothing,
+    historyvars = nothing,
+    keephistory = nothing,
+    iterations = nothing,
+    free_energy = false,
+    free_energy_diagnostics = BetheFreeEnergyDefaultChecks,
+    autostart = true,
+    events = nothing,
+    callbacks = nothing,
+    addons = nothing,
+    postprocess = DefaultPostprocess(),
+    uselock = false,
+    warn = true
+)

This function provides a generic way to perform probabilistic inference in RxInfer.jl. Returns RxInferenceEngine.

Arguments

For more information about some of the arguments, please check below.

  • model: specifies a model generator, required
  • data: NamedTuple or Dict with data, required (or datastream)
  • datastream: A stream of NamedTuple with data, required (or data)
  • initmarginals = nothing: NamedTuple or Dict with initial marginals, optional
  • initmessages = nothing: NamedTuple or Dict with initial messages, optional
  • autoupdates = nothing: auto-updates specification, required for many models, see @autoupdates
  • constraints = nothing: constraints specification object, optional, see @constraints
  • meta = nothing: meta specification object, optional, may be required for some models, see @meta
  • options = nothing: model creation options, optional, see ModelInferenceOptions
  • returnvars = nothing: return structure info, optional, by default creates observables for all random variables that return posteriors at last vmp iteration, see below for more information
  • historyvars = nothing: history structure info, optional, defaults to no history, see below for more information
  • keephistory = nothing: history buffer size, defaults to empty buffer, see below for more information
  • iterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information
  • free_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl
  • free_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.
  • autostart = true: specifies whether to call RxInfer.start on the created engine automatically or not
  • showprogress = false: show progress module, optional, defaults to false
  • events = nothing: inference cycle events, optional, see below for more info
  • callbacks = nothing: inference cycle callbacks, optional, see below for more info
  • addons = nothing: inject and send extra computation information along messages, see below for more info
  • postprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info
  • uselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock.
  • warn = true: enables/disables warnings

Note on NamedTuples

When passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.

Extended information about some of the arguments

  • data or datastream

Either data or datastream keyword argument is required, but specifying both is not supported and will result in an error.

  • data

The data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds an iterable container with values of type Float64. The elements of such containers in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide an iterable container with elements of type Vector{Float64}.

All entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.

Note: The behavior of the data keyword argument is different from that which is used in the inference function.

  • datastream

The datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.

Note: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the inference function and its data argument. In fact, you can see the rxinference function as an efficient streamed version of the inference function, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.

  • model

The model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:

@model function coin_toss(some_argument, some_keyword_argument = 3)
+   ...
+end
+
+result = rxinference(
+    model = coin_toss(some_argument; some_keyword_argument = 3)
+)

Note: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.

  • initmarginals

For specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as

rxinference(...
+    initmarginals = (
+        # initialize the marginal distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)

This argument needs to be a named tuple, i.e. initmarginals = (a = ..., ), or dictionary.

  • initmessages

For specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the initmessages argument, such as

rxinference(...
+    initmessages = (
+        # initialize the messages distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)

This argument needs to be a named tuple, i.e. initmessages = (a = ..., ), or dictionary.

  • autoupdates

See @autoupdates for more information.

  • options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.

  • pipeline: changes the default pipeline for each factor node in the graph

  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

  • returnvars

returnvars accepts a tuple of symbols and specifies the latent variables of interests. For each symbol in the returnvars specification the rxinference function will prepare an observable stream (see Rocket.jl) of posterior updates. An agent may subscribe on the new posteriors events and perform some actions. For example:

engine = rxinference(
+    ...,
+    returnvars = (:x, :τ),
+    autostart  = false
+)
+
+x_subscription = subscribe!(engine.posteriors[:x], (update) -> println("x variable has been updated: ", update))
+τ_subscription = subscribe!(engine.posteriors[:τ], (update) -> println("τ variable has been updated: ", update))
+
+RxInfer.start(engine)
+
+...
+
+unsubscribe!(x_subscription)
+unsubscribe!(τ_subscription)
+
+RxInfer.stop(engine)
  • historyvars

historyvars specifies the variables of interests and the amount of information to keep in history about the posterior updates. The specification is similar to the returnvars in the inference procedure. The historyvars requires keephistory to be greater than zero.

historyvars accepts a NamedTuple or Dict or return var specification. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = rxinference(
+    ...,
+    historyvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    ),
+    keephistory = 10
+)

It is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.

Example:

result = rxinference(
+    ...,
+    historyvars = KeepLast(),
+    keephistory = 10
+)
  • keep_history

Specifies the buffer size for the updates history both for the historyvars and the free_energy buffers.

  • iterations

Specifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration.

  • free_energy

This setting specifies whenever the inference function should create an observable of Bethe Free Energy (BFE) values. The BFE observable returns a new computed value for each VMP iteration. Note, however, that it may be not possible to compute BFE values for every model. If free_energy = true and keephistory > 0 the engine exposes extra fields to access the history of the Bethe free energy updates:

  • engine.free_energy_history: Returns a free energy history averaged over the VMP iterations
  • engine.free_energy_final_only_history: Returns a free energy history of values computed on last VMP iterations for every observation
  • engine.free_energy_raw_history: Returns a raw free energy history

Additionally, the argument may accept a floating point type, instead of a Bool value. Using this option, e.g.Float64, improves performance of Bethe Free Energy computation, but restricts using automatic differentiation packages.

  • free_energy_diagnostics

This settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.

  • events

The engine from the rxinference function has its own lifecycle. The events can be listened by subscribing to the engine.events field. E.g.

engine = rxinference(
+    ...,
+    autostart = false
+)
+
+subscription = subscribe!(engine.events, (event) -> println(event))
+
+RxInfer.start(engine)

By default all events are disabled, in order to enable an event its identifier must be listed in the Val tuple of symbols passed to the events keyword arguments.

engine = rxinference(
+    events = Val((:on_new_data, :before_history_save, :after_history_save))
+)

The list of all possible events and their event data is present below (see RxInferenceEvent for more information about the type of event data):

  • on_new_data: args: (model::FactorGraphModel, data)

  • before_iteration args: (model::FactorGraphModel, iteration)

  • before_auto_update args: (model::FactorGraphModel, iteration, auto_updates)

  • after_auto_update args: (model::FactorGraphModel, iteration, auto_updates)

  • before_data_update args: (model::FactorGraphModel, iteration, data)

  • after_data_update args: (model::FactorGraphModel, iteration, data)

  • after_iteration args: (model::FactorGraphModel, iteration)

  • before_history_save args: (model::FactorGraphModel, )

  • after_history_save args: (model::FactorGraphModel, )

  • on_tick args: (model::FactorGraphModel, )

  • on_error args: (model::FactorGraphModel, err)

  • on_complete args: (model::FactorGraphModel, )

  • callbacks

The rxinference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the preparation of the inference engine. To inject extra procedures during the inference use the events. Here is the example of the callbacks

result = rxinference(
+    ...,
+    callbacks = (
+        after_model_creation = (model, returnval) -> println("The model has been created. Number of nodes: $(length(getnodes(model)))"),
+    )
+)

The callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks and their input arguments is present below:

  • before_model_creation: args: ()

  • after_model_creation: args: (model::FactorGraphModel, returnval)

  • before_autostart: args: (engine::RxInferenceEngine)

  • after_autostart: args: (engine::RxInferenceEngine)

  • addons

The addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.

  • postprocess

The postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.

See also inference

source
RxInfer.start — Function
start(engine::RxInferenceEngine)

Starts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.stop

source
RxInfer.stop — Function
stop(engine::RxInferenceEngine)

Stops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.start

source
RxInfer.@autoupdates — Macro
@autoupdates

Creates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification.

Each line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.

For example:

@autoupdates begin 
+    x = f(q(z))
+end

This structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically.

As an example consider the following model and auto-update specification:

@model function kalman_filter()
+    x_current_mean = datavar(Float64)
+    x_current_var  = datavar(Float64)
+
+    x_current ~ Normal(mean = x_current_mean, var = x_current_var)
+
+    x_next ~ Normal(mean = x_current, var = 1.0)
+
+    y = datavar(Float64)
+    y ~ Normal(mean = x_next, var = 1.0)
+end

This model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:

autoupdates = @autoupdates begin
+    x_current_mean, x_current_var = mean_cov(q(x_next))
+end

This structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.

See also: rxinference

source
RxInfer.RxInferenceEngine — Type
RxInferenceEngine

The return value of the rxinference function.

Public fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the rxinference.
  • free_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the rxinference.
  • history: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the rxinference.
  • free_energy_history: (optional) Free energy history, average over variational iterations
  • free_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)
  • free_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)
  • events: (optional) A stream of events send by the inference engine. See the events argument for the rxinference.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.

Use the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.

See also: rxinference, RxInferenceEvent, RxInfer.start, RxInfer.stop

source
RxInfer.RxInferenceEvent — Type
RxInferenceEvent{T, D}

The RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.

The events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:

using Rocket
+
+struct MyEventListener <: Rocket.Actor{RxInferenceEvent}
+    # ... extra fields
+end
+
+function Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })
+    model, iteration = event
+    println("Iteration $(iteration) has been finished.")
+end
+
+function Rocket.on_error!(listener::MyEventListener, err)
+    # ...
+end
+
+function Rocket.on_complete!(listener::MyEventListener)
+    # ...
+end
+

and later on:

engine = rxinference(events = Val((:after_iteration, )), ...)
+
+subscription = subscribe!(engine.events, MyEventListener(...))

See also: rxinference, RxInferenceEngine

source
diff --git a/v2.15.0/manuals/meta-specification/index.html b/v2.15.0/manuals/meta-specification/index.html new file mode 100644 index 000000000..4569352d2 --- /dev/null +++ b/v2.15.0/manuals/meta-specification/index.html @@ -0,0 +1,128 @@ + +Meta specification · RxInfer.jl
GitHub

Meta Specification

Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.

General syntax

@meta macro accepts either regular Julia function or a single begin ... end block:

@meta function MyModelMeta(arg1, arg2)
+    Node(y,x) -> MetaObject(arg1, arg2)
+end
+
+my_meta = @meta begin 
+    Node(y,x) -> MetaObject(arg1, arg2)
+end

In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order $5$ can be specified as follows:

@meta function ARmodel_meta(num_order)
+    AR() -> ARMeta(Univariate, num_order, ARsafe())
+end
+
+my_meta = ARmodel_meta(5)

In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:

num_order = 5
+
+my_meta = @meta begin 
+    AR() -> ARMeta(Multivariate, num_order, ARsafe())
+end

Both syntax variations provide the same meta specification and there is no preference given to one over the other.

Options specification

@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

my_meta = @meta [ warn = false ] begin 
+   ...
+end
+
+@meta [ warn = false ] function MyModelMeta()
+    ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/meta specification

Meta specification

First, let's start with an example:

my_meta = @meta begin 
+    GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))
+end

This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.

You can have a list of as many meta specification entries as possible for different nodes:

my_meta = @meta begin 
+    GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))
+    AR() -> ARMeta(Multivariate, 5, ARsafe())
+    MyCustomNode() -> MyCustomMetaObject(arg1, arg2)
+end

To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+my_meta = @meta begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); meta = my_meta)

Alternatively, it is possible to use meta directly in the automatic inference and rxinference functions that accepts meta keyword argument:

inferred_result = inference(
+    model = my_model(arguments...),
+    meta = my_meta,
+    ...
+)
+
+inferred_result = rxinference(
+    model = my_model(arguments...),
+    meta = my_meta,
+    ...
+)

Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:

@model function my_model()
+    ...
+
+    y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }
+
+    ...
+end

If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the inference and rxinference functions.

Create your own meta

Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:

# create your own meta structure for your custom node
+struct MyCustomMeta
+    arg1 
+    arg2 
+end
+
+# apply the new meta structure to your node
+@meta function model_meta(arg1, arg2)
+    MyCustomNode() -> MyCustomMeta(arg1,arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

or create different meta structures for a node, e.g. AR node:

# create your own meta structure for the AR node
+struct MyARMeta
+    arg1
+    arg2
+end
+
+# apply the new meta structure to the AR node
+@meta function model_meta(arg1, arg2)
+    AR() -> MyARMeta(arg1, arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.

Example

This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(2.5, 0.5)\\ + y & \sim \mathrm{Normal}(2*x, 2.0) +\end{aligned}\]

where $y$ is observable data and $x$ is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.

using RxInfer
+
+#create data
+y_data = 4.0
+
+#make model
+@model function gaussian_model()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+#do inference
+inference_result = inference(
+    model = gaussian_model(),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (x)
+

However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean $m$ clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:

#create your new meta structure for Normal node
+struct MetaConstrainedMeanNormal{T}
+    lower_limit :: T
+    upper_limit :: T
+end
+
+#define rules with meta for the Normal node
+@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
+
+@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
#make model
+@model function gaussian_model_with_meta()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+custom_meta = @meta begin
+    NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)
+end
+
+#do inference
+inference_result = inference(
+    model = gaussian_model(),
+    data = (y = y_data,),
+    meta = custom_meta
+)
Inference results:
+  Posteriors       | available for (x)
+

Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.

diff --git a/v2.15.0/manuals/model-specification/index.html b/v2.15.0/manuals/model-specification/index.html new file mode 100644 index 000000000..f2655b949 --- /dev/null +++ b/v2.15.0/manuals/model-specification/index.html @@ -0,0 +1,117 @@ + +Model specification · RxInfer.jl
GitHub

Model Specification

The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: 

@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model specification here
+    return ...
+end

Model options, model_arguments and model_keyword_arguments are optional and may be omitted:

@model function model_name()
+    # model specification here
+    return ...
+end

The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:

@model function my_model(model_arguments...)
+    # model specification here
+    # ...
+    return x, y
+end
generator = my_model(model_arguments...)

In order to create an instance of the model object we should use the create_model function:

model, (x, y) = create_model(generator)

It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.

A full example before diving in

Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:

@model function state_space_model(n_observations, noise_variance)
+
+    c = constvar(1.0)
+    x = randomvar(n_observations)
+    y = datavar(Float64, n_observations)
+
+    x[1] ~ NormalMeanVariance(0.0, 100.0)
+
+    for i in 2:n_observations
+       x[i] ~ x[i - 1] + c
+       y[i] ~ NormalMeanVariance(x[i], noise_var)
+    end
+
+    return x, y
+end

Graph variables creation

Constants

Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).

You can create a constant within a model specification macro with constvar() function. For example:

@model function model_name(...)
+    ...
+    c = constvar(1.0)
+
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0
+    end
+    ...
+end
Note

constvar() function is supposed to be used only within the @model macro.

Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:

@model function model_name(nsamples::Int, c::ConstVariable)
+    ...
+    # no need to call for a constvar() here
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`
+    end
+    ...
+end
Note

::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.

Data variables

It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.

Examples: 

@model function model_name(...)
+    ...
+    y = datavar(Float64) # Creates a single data input with `y` as identificator
+    y = datavar(Float64, n) # Returns a vector of  `y_i` data input objects with length `n`
+    y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`
+    y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

datavar() function is supposed to be used only within the @model macro.

datavar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = datavar(Float64, n) where { allow_missing = true }
+    ...
+end

Data variables available options

  • allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.

Random variables

There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.

Examples: 

@model function model_name(...)
+    ...
+    x = randomvar() # Returns a single random variable which can be used later in the model
+    x = randomvar(n) # Returns an vector of random variables with length `n`
+    x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`
+    x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

randomvar() function is supposed to be used only within the @model macro.

randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = randomvar() where { prod_constraint = ProdGeneric() }
+    ...
+end

Random variables available options

  • prod_constraint
  • prod_strategy
  • marginal_form_constraint
  • marginal_form_check_strategy
  • messages_form_constraint
  • messages_form_check_strategy
  • pipeline

The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.

Node creation

Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables.

Distributions.jl compatibility

For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:

  1. Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.
  2. Depending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.
  3. In certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.

Tilde syntax

We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define

@model function model_name(...)
+    ...
+    m = randomvar()
+    v = randomvar()
+    y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically
+    ...
+end

Another example, but using a deterministic relation between random variables:

@model function model_name(...)
+    ...
+    a = randomvar()
+    b = randomvar()
+    c ~ a + b
+    ...
+end
Note

The RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.

The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:

noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.

It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.

Note

It is forbidden to use random variable within square brackets in the model specification.

y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.
+
+y ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.

It is also possible to return a node reference from the ~ operator. Use the following syntax:

node, y ~ NormalMeanVariance(mean, var)

Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.

Broadcasting syntax

Note

Broadcasting syntax requires at least v2.1.0 of GraphPPL.jl

GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:

y = datavar(Float64, n)
+y .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations

More complex expression are also allowed:

m ~ NormalMeanPrecision(0.0, 0.0001)
+t ~ Gamma(1.0, 1.0)
+
+y = randomvar(Float64, n)
+y .~ NormalMeanPrecision(m, t)
A = constvar(...)
+x = randomvar(n)
+y = datavar(Vector{Float64}, n)
+
+w         ~ Wishart(3, diageye(2))
+x[1]      ~ MvNormalMeanPrecision(zeros(2), diageye(2))
+x[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A
+y        .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix

Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:

# Suppose `x` is a 2-dimensional Gaussian distribution
+z .~ x .+ constvar([ 1, 1 ])
+# Which is equivalent to 
+for i in 1:n
+   z[i] ~ x[i] + constvar([ 1, 1 ])
+end

Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:

# Without explicit `constvar`
+z .~ x .+ [ 1, 1 ]
+# Which is equivalent to 
+array = [1, 1]
+for i in 1:n
+   z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian 
+end

Read more about how broadcasting machinery works in Julia in the official documentation.

Node creation options

To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q

A list of the available options specific to the ReactiveMP inference engine is presented below.

Factorisation constraint option

See also Constraints Specification section.

Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:

variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }

where RecognitionFactorisationConstraint can be the following

  1. MeanField()

Automatically specifies a mean-field factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }
  1. FullFactorisation()

Automatically specifies a full factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }
  1. q(μ)q(v)q(out) or q(μ) * q(v) * q(out)

A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.

Examples: 

# Using interface names of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names for some node
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }
+
+# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names aliases for some node
+# In general aliases correspond to the function names for distribution parameters
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }
+
+# Using random variables names from `~` operator expression
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }
+
+# All methods can be combined easily
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }

Metadata option

Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.

z ~ f(x, y) where { meta = ... }
diff --git a/v2.15.0/search_index.js b/v2.15.0/search_index.js new file mode 100644 index 000000000..009de4b10 --- /dev/null +++ b/v2.15.0/search_index.js @@ -0,0 +1,3 @@ +var documenterSearchIndex = {"docs": +[{"location":"manuals/delta-node/#delta-node-manual","page":"Delta node","title":"Delta node manual","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/#Features-and-Supported-Inference-Scenarios","page":"Delta node","title":"Features and Supported Inference Scenarios","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Gaussian Nodes: For delta nodes linked to strictly multivariate or univariate Gaussian distributions, the recommended methods are Linearization or Unscented transforms.\nExponential Family Nodes: For the delta node connected to nodes from the exponential family, the CVI (Conjugate Variational Inference) is the method of choice.\nStacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Methods Gaussian Nodes Exponential Family Nodes Stacking Delta Nodes\nLinearization ✓ ✗ ✓\nUnscented ✓ ✗ ✓\nCVI ✓ ✓ ✗","category":"page"},{"location":"manuals/delta-node/#Gaussian-Case","page":"Delta node","title":"Gaussian Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For clarity, consider the following example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=0.0, var=1.0)\n y ~ tanh(x)\n z ~ Normal(mean=y, var=1.0)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Unscented()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For a deeper understanding of the Unscented method and its parameters, consult the docstrings.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To execute the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"inference(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"This methodology is consistent even when the delta node is associated with multiple nodes. For instance:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"f(x, g) = x*tanh(g)","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=1.0, var=1.0)\n g ~ Normal(mean=1.0, var=1.0)\n y ~ f(x, g)\n z ~ Normal(mean=y, var=0.1)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification is:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization())\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or simply","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))\nend","category":"page"},{"location":"manuals/delta-node/#Exponential-Family-Case","page":"Delta node","title":"Exponential Family Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example1()\n z = datavar(Float64)\n x ~ Gamma(shape=1.0, rate=1.0)\n y ~ tanh(x)\n z ~ Bernoulli(y)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification can be represented as:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using StableRNGs\nusing Optimisers\n\ndelta_meta = @meta begin \n tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Consult the ProdCVI docstrings for a detailed explanation of these parameters.","category":"page"},{"location":"manuals/inference/postprocess/#user-guide-inference-postprocess","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"","category":"section"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"Both inference and rxinference allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:","category":"page"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"DefaultPostprocess\nUnpackMarginalPostprocess\nNoopPostprocess","category":"page"},{"location":"manuals/inference/postprocess/#RxInfer.DefaultPostprocess","page":"Inference results postprocessing","title":"RxInfer.DefaultPostprocess","text":"DefaultPostprocess picks the most suitable postprocessing step automatically\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.UnpackMarginalPostprocess","page":"Inference results postprocessing","title":"RxInfer.UnpackMarginalPostprocess","text":"This postprocessing step removes the Marginal wrapper type from the result\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.NoopPostprocess","page":"Inference results postprocessing","title":"RxInfer.NoopPostprocess","text":"This postprocessing step does nothing\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/inference/#user-guide-inference","page":"Static dataset","title":"Automatic inference specification on static datasets","text":"","category":"section"},{"location":"manuals/inference/inference/","page":"Static dataset","title":"Static dataset","text":"RxInfer exports the inference function to quickly run and test you model with static datasets. Note, however, that this function does cover almost all capabilities of the inference engine, but for advanced use cases you may want to resort to the manual inference specification. ","category":"page"},{"location":"manuals/inference/inference/","page":"Static dataset","title":"Static dataset","text":"For running inference on real-time datasets see the Reactive Inference section. For manual inference specification see the Manual Inference section.","category":"page"},{"location":"manuals/inference/inference/","page":"Static dataset","title":"Static dataset","text":"inference\nInferenceResult","category":"page"},{"location":"manuals/inference/inference/#RxInfer.inference","page":"Static dataset","title":"RxInfer.inference","text":"inference(\n model; \n data,\n initmarginals = nothing,\n initmessages = nothing,\n constraints = nothing,\n meta = nothing,\n options = nothing,\n returnvars = nothing, \n predictvars = nothing, \n iterations = nothing,\n free_energy = false,\n free_energy_diagnostics = BetheFreeEnergyDefaultChecks,\n showprogress = false,\n callbacks = nothing,\n addons = nothing,\n postprocess = DefaultPostprocess()\n)\n\nThis function provides a generic way to perform probabilistic inference in RxInfer.jl. Returns InferenceResult.\n\nArguments\n\nFor more information about some of the arguments, please check below.\n\nmodel: specifies a model generator, required\ndata: NamedTuple or Dict with data, required\ninitmarginals = nothing: NamedTuple or Dict with initial marginals, optional\ninitmessages = nothing: NamedTuple or Dict with initial messages, optional\nconstraints = nothing: constraints specification object, optional, see @constraints\nmeta = nothing: meta specification object, optional, may be required for some models, see @meta\noptions = nothing: model creation options, optional, see ModelInferenceOptions\nreturnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information\npredictvars = nothing: return structure info, optional, see below for more information\niterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information\nfree_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl\nfree_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.\nshowprogress = false: show progress module, optional, defaults to false\ncallbacks = nothing: inference cycle callbacks, optional, see below for more info\naddons = nothing: inject and send extra computation information along messages, see below for more info\npostprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info\nwarn = true: enables/disables warnings\n\nNote on NamedTuples\n\nWhen passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.\n\nExtended information about some of the arguments\n\nmodel\n\nThe model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:\n\n@model function coin_toss(some_argument, some_keyword_argument = 3)\n ...\nend\n\nresult = inference(\n model = coin_toss(some_argument; some_keyword_argument = 3)\n)\n\nNote: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.\n\ndata\n\nThe data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.\n\nNote: The behavior of the data keyword argument is different from that which is used in the rxinference function.\n\ninitmarginals\n\nFor specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as\n\ninference(...\n initmarginals = (\n # initialize the marginal distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. initmarginals = (a = ..., ), or dictionary.\n\ninitmessages\n\nFor specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the initmessages argument, such as\n\ninference(...\n initmessages = (\n # initialize the messages distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. initmessages = (a = ..., ), or dictionary.\n\noptions\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for large models, but reduces the performance of the inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\nreturnvars\n\nreturnvars specifies the variables of interests and the amount of information to return about their posterior updates. \n\nreturnvars accepts a NamedTuple or Dict or return var specification. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nNote: if iterations are specified as a number, the inference function tracks and returns every update for each iteration for every random variable in the model (equivalent to KeepEach()). If number of iterations is set to nothing, the inference function saves the 'last' (and the only one) update for every random variable in the model (equivalent to KeepLast()). Use iterations = 1 to force KeepEach() setting when number of iterations is equal to 1 or set returnvars = KeepEach() manually.\n\nExample: \n\nresult = inference(\n ...,\n returnvars = (\n x = KeepLast(),\n τ = KeepEach()\n )\n)\n\nIt is also possible to set either returnvars = KeepLast() or returnvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.\n\nExample:\n\nresult = inference(\n ...,\n returnvars = KeepLast()\n)\n\npredictvars\n\npredictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.\n\nSimilar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = inference(\n ...,\n predictvars = (\n o = KeepLast(),\n τ = KeepEach()\n )\n)\n\niterations\n\nSpecifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration. \n\nfree_energy\n\nThis setting specifies whenever the inference function should return Bethe Free Energy (BFE) values. Note, however, that it may be not possible to compute BFE values for every model. \n\nAdditionally, the argument may accept a floating point type, instead of a Bool value. Using his option, e.g.Float64, improves performance of Bethe Free Energy computation, but restricts using automatic differentiation packages.\n\nfree_energy_diagnostics\n\nThis settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.\n\ncallbacks\n\nThe inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.\n\nresult = inference(\n ...,\n callbacks = (\n on_marginal_update = (model, name, update) -> println(\"$(name) has been updated: $(update)\"),\n after_inference = (args...) -> println(\"Inference has been completed\")\n )\n)\n\nThe callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks and their arguments is present below:\n\non_marginal_update: args: (model::FactorGraphModel, name::Symbol, update)\nbefore_model_creation: args: ()\nafter_model_creation: args: (model::FactorGraphModel, returnval)\nbefore_inference: args: (model::FactorGraphModel)\nbefore_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool\nbefore_data_update: args: (model::FactorGraphModel, data)\nafter_data_update: args: (model::FactorGraphModel, data)\nafter_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool\nafter_inference: args: (model::FactorGraphModel)\n\nbefore_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.\n\naddons\n\nThe addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.\n\npostprocess\n\nThe postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.\n\ncatch_exception\n\nThe catch_exception keyword argument specifies whether exceptions during the inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.\n\nSee also: InferenceResult, rxinference\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/inference/#RxInfer.InferenceResult","page":"Static dataset","title":"RxInfer.InferenceResult","text":"InferenceResult\n\nThis structure is used as a return value from the inference function. \n\nPublic Fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for inference.\nfree_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for inference.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\nerror: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for inference.\n\nSee also: inference\n\n\n\n\n\n","category":"type"},{"location":"manuals/model-specification/#user-guide-model-specification","page":"Model specification","title":"Model Specification","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Model options, model_arguments and model_keyword_arguments are optional and may be omitted:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name()\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function my_model(model_arguments...)\n # model specification here\n # ...\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"generator = my_model(model_arguments...)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"In order to create an instance of the model object we should use the create_model function:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"model, (x, y) = create_model(generator)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.","category":"page"},{"location":"manuals/model-specification/#A-full-example-before-diving-in","page":"Model specification","title":"A full example before diving in","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function state_space_model(n_observations, noise_variance)\n\n c = constvar(1.0)\n x = randomvar(n_observations)\n y = datavar(Float64, n_observations)\n\n x[1] ~ NormalMeanVariance(0.0, 100.0)\n\n for i in 2:n_observations\n x[i] ~ x[i - 1] + c\n y[i] ~ NormalMeanVariance(x[i], noise_var)\n end\n\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/#Graph-variables-creation","page":"Model specification","title":"Graph variables creation","text":"","category":"section"},{"location":"manuals/model-specification/#user-guide-model-specification-constant-variables","page":"Model specification","title":"Constants","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"You can create a constant within a model specification macro with constvar() function. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n c = constvar(1.0)\n\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nconstvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(nsamples::Int, c::ConstVariable)\n ...\n # no need to call for a constvar() here\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\n::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-data-variables","page":"Model specification","title":"Data variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64) # Creates a single data input with `y` as identificator\n y = datavar(Float64, n) # Returns a vector of `y_i` data input objects with length `n`\n y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`\n y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\ndatavar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"datavar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64, n) where { allow_missing = true }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Data-variables-available-options","page":"Model specification","title":"Data variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-random-variables","page":"Model specification","title":"Random variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n x = randomvar() # Returns a single random variable which can be used later in the model\n x = randomvar(n) # Returns an vector of random variables with length `n`\n x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`\n x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nrandomvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = randomvar() where { prod_constraint = ProdGeneric() }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Random-variables-available-options","page":"Model specification","title":"Random variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"prod_constraint\nprod_strategy\nmarginal_form_constraint\nmarginal_form_check_strategy\nmessages_form_constraint\nmessages_form_check_strategy\npipeline","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.","category":"page"},{"location":"manuals/model-specification/#Node-creation","page":"Model specification","title":"Node creation","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables. ","category":"page"},{"location":"manuals/model-specification/#Distributions.jl-compatibility","page":"Model specification","title":"Distributions.jl compatibility","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.\nDepending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.\nIn certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.","category":"page"},{"location":"manuals/model-specification/#Tilde-syntax","page":"Model specification","title":"Tilde syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n m = randomvar()\n v = randomvar()\n y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Another example, but using a deterministic relation between random variables:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n a = randomvar()\n b = randomvar()\n c ~ a + b\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nThe RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nIt is forbidden to use random variable within square brackets in the model specification.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.\n\ny ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is also possible to return a node reference from the ~ operator. Use the following syntax:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"node, y ~ NormalMeanVariance(mean, var)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.","category":"page"},{"location":"manuals/model-specification/#Broadcasting-syntax","page":"Model specification","title":"Broadcasting syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nBroadcasting syntax requires at least v2.1.0 of GraphPPL.jl ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y = datavar(Float64, n)\ny .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"More complex expression are also allowed:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"m ~ NormalMeanPrecision(0.0, 0.0001)\nt ~ Gamma(1.0, 1.0)\n\ny = randomvar(Float64, n)\ny .~ NormalMeanPrecision(m, t)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A = constvar(...)\nx = randomvar(n)\ny = datavar(Vector{Float64}, n)\n\nw ~ Wishart(3, diageye(2))\nx[1] ~ MvNormalMeanPrecision(zeros(2), diageye(2))\nx[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A\ny .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Suppose `x` is a 2-dimensional Gaussian distribution\nz .~ x .+ constvar([ 1, 1 ])\n# Which is equivalent to \nfor i in 1:n\n z[i] ~ x[i] + constvar([ 1, 1 ])\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Without explicit `constvar`\nz .~ x .+ [ 1, 1 ]\n# Which is equivalent to \narray = [1, 1]\nfor i in 1:n\n z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian \nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Read more about how broadcasting machinery works in Julia in the official documentation.","category":"page"},{"location":"manuals/model-specification/#Node-creation-options","page":"Model specification","title":"Node creation options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A list of the available options specific to the ReactiveMP inference engine is presented below.","category":"page"},{"location":"manuals/model-specification/#Factorisation-constraint-option","page":"Model specification","title":"Factorisation constraint option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"See also Constraints Specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"where RecognitionFactorisationConstraint can be the following","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"MeanField()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a mean-field factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"FullFactorisation()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a full factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"q(μ)q(v)q(out) or q(μ) * q(v) * q(out)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Using interface names of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names for some node\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }\n\n# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names aliases for some node\n# In general aliases correspond to the function names for distribution parameters\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }\n\n# Using random variables names from `~` operator expression\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }\n\n# All methods can be combined easily\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }","category":"page"},{"location":"manuals/model-specification/#Metadata-option","page":"Model specification","title":"Metadata option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"z ~ f(x, y) where { meta = ... }","category":"page"},{"location":"examples/overview/#examples-overview","page":"Overview","title":"Examples overview","text":"","category":"section"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"Basic examples: Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.\nAdvanced examples: Advanced examples contain more complex inference problems.\nProblem specific: Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference","page":"Manual inference specification","title":"Manual inference","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"For advanced use cases it is advised to use manual inference specification. ","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Create a model with @model macro and get a references to random variables and data inputs\nSubscribe to random variable posterior marginal updates \nSubscribe to Bethe Free Energy updates (optional)\nFeed model with observations \nUnsubscribe from posterior marginal updates (optional)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-model-creation","page":"Manual inference specification","title":"Model creation","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random\n\n@model function my_model()\n m2 ~ NormalMeanVariance(0.0, 1.0)\n m1 ~ NormalMeanVariance(m2, 1.0)\n\n y = datavar(Float64)\n y ~ NormalMeanVariance(m1, 1.0)\n\n # Return variables of interests, optional\n return m1, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"And later on we may create our model with the create_model function and obtain references for variables of interests:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m1, y) = create_model(my_model())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Alternatively, it is possible to query any variable using squared brackets on model object:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model[:m1] # m1\nmodel[:y] # y\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-marginal-updates","page":"Manual inference specification","title":"Posterior marginal updates","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_updates = getmarginal(m1)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"After that we can subscribe on new updates and perform some actions based on new values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin\n println(\"New posterior for m1: \", new_posterior)\nend)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function my_model()\n ...\n m_n = randomvar(n)\n ...\n return m_n, ...\nend\n\nmodel, (m_n, ...) = create_model(my_model())\n\nm_n_updates = getmarginals(m_n)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-observations","page":"Manual inference specification","title":"Feeding observations","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To feed an observation for a specific data input we use update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0) # Observation didn't change, should result in the same posterior\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"If y is an array of data inputs it is possible to pass an array of observation to update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"for i in 1:length(data)\n update!(y[i], data[i])\nend\n# is an equivalent of\nupdate!(y, data)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp","page":"Manual inference specification","title":"Variational Message Passing","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"real_mean = -4.0\nreal_precision = 0.2\nrng = MersenneTwister(1234)\n\nn = 100\ndata = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function normal_estimation(n)\n m ~ NormalMeanVariance(0.0, 10.0)\n w ~ Gamma(0.1, 10.0)\n\n y = datavar(Float64, n)\n\n for i in 1:n\n y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }\n end\n\n return m, w, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m, w, y) = create_model(normal_estimation(n))\n\n# We use vague initial marginals\nsetmarginal!(m, vague(NormalMeanVariance)) \nsetmarginal!(w, vague(Gamma))\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m_marginals = []\nw_marginals = []\n\nsubscriptions = subscribe!([\n (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),\n (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),\n])\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(subscriptions)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using Plots\n\np1 = plot(title = \"'Mean' posterior marginals\")\ngrid1 = -6.0:0.01:4.0\n\nfor iter in [ 1, 2, 10 ]\n\n estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = \"Estimated mean after $iter VMP iterations\")\n\nend\n\nplot!(p1, [ real_mean ], seriestype = :vline, label = \"Real mean\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"p2 = plot(title = \"'Precision' posterior marginals\")\ngrid2 = 0.01:0.001:0.35\n\nfor iter in [ 2, 3, 10 ]\n\n estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = \"Estimated precision after $iter VMP iterations\")\n\nend\n\nplot!(p2, [ real_precision ], seriestype = :vline, label = \"Real precision\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp-bfe","page":"Manual inference specification","title":"Computing Bethe Free Energy","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer package exports score function for an observable of free energy values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"fe_observable = score(model, BetheFreeEnergy())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"# Reset posterior marginals for `m` and `w`\nsetmarginal!(m, vague(NormalMeanVariance))\nsetmarginal!(w, vague(Gamma))\n\nfe_values = []\n\nfe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(fe_subscription)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"plot(fe_values, label = \"Bethe Free Energy\", xlabel = \"Iteration #\")","category":"page"},{"location":"contributing/new-package/#Contributing-to-the-dependencies","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.","category":"page"},{"location":"contributing/new-package/#The-benefits-of-small-packages-for-the-ecosystem","page":"Contributing to the dependencies","title":"The benefits of small packages for the ecosystem","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.\nCollaboration: Teams can work on different packages concurrently, speeding up development.\nVersion Control: Precise versioning and fewer dependencies lead to leaner projects.\nPerformance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.\nFlexibility: Developers can select and customize packages for their needs.\nCommunity: Smaller packages attract contributors, fostering collaboration and faster feedback.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.","category":"page"},{"location":"contributing/new-package/#Use-[PkgTemplates](https://github.com/JuliaCI/PkgTemplates.jl)","page":"Contributing to the dependencies","title":"Use PkgTemplates","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> using PkgTemplates\n\njulia> USER = \"your github user name\" # Use `biaslab` if developing within the BIASlab organisation\n\njulia> template = Template(\n user = USER, \n plugins = [\n CompatHelper(), \n ProjectFile(), \n SrcDir(), \n Git(), \n License(), \n Readme(), \n Tests(), \n GitHubActions(), \n Codecov(), \n Documenter{GitHubActions}(), \n Formatter(style=\"blue\"), \n BlueStyleBadge(), \n PkgEvalBadge()\n])\n\njulia> template(\"MyNewCoolPackage\")","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the minimum supported version of Julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9.2\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Try to be conservative and set as low version of Julia as possible.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the authors of the package","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The authors field is present in the Project.toml, e.g ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"authors = [\"John Wick \", ...]","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Add requires dependencies and their [compat] bounds","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"or ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] activate .","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Then, add dependencies like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] add SomeCoolDependency, SomeOtherCoolDependency","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9\"\nSomeCoolDependency = \"0.19.2\"\nSomeOtherCoolDependency = \"1.3.12\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For more details on compat bounds, check the official Julia documentation.","category":"page"},{"location":"contributing/new-package/#Adjust-README.md","page":"Contributing to the dependencies","title":"Adjust README.md","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"note: Note\nSome badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.","category":"page"},{"location":"contributing/new-package/#Write-code-and-tests","page":"Contributing to the dependencies","title":"Write code and tests","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.","category":"page"},{"location":"contributing/new-package/#Simplify-Testing-with-ReTestItems","page":"Contributing to the dependencies","title":"Simplify Testing with ReTestItems","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.","category":"page"},{"location":"contributing/new-package/#Write-code-and-the-documentation","page":"Contributing to the dependencies","title":"Write code and the documentation","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=docs docs/make.jl","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.","category":"page"},{"location":"contributing/new-package/#Hosting-Documentation-with-GitHub-Actions","page":"Contributing to the dependencies","title":"Hosting Documentation with GitHub Actions","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.","category":"page"},{"location":"contributing/new-package/#Enable-GitHub-Pages-in-Repository-Settings","page":"Contributing to the dependencies","title":"Enable GitHub Pages in Repository Settings","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Navigate to the GitHub Pages settings of your repository.\nChoose the Deploy from a branch option.\nSelect the gh-pages branch.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#examples-assessing-people’s-skills","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of \"Model-Based Machine Learning\" by Winn et al.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Problem-Statement","page":"Assessing People’s Skills","title":"Problem Statement","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We model the result for question i as a continuous variable r_iin01, and skill/attitude as a binary variable s_i in 0 1, where s_1 represents whether the student has partied, and s_2 and s_3 represent whether the student has studied the chapters for the corresponding questions.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We assume the following logic:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"If the student is alert (has not partied), then they will score on the first question;\nIf the student is alert or has studied chapter two, then they will score on question two;\nIf the student can answer question two and has studied chapter three, then they will score on question three.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Definition","page":"Assessing People’s Skills","title":"Generative Model Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"To model the probability for correct answers, we assume a latent state variable t_i in 01. The dependencies between the variables can then be modeled by the following Bayesian network:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"(s_1) (s_2) (s_3)\n | | |\n v v v\n(t_1)-->(t_2)-->(t_3)\n | | |\n v v v\n(r_1) (r_2) (r_3)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"As prior beliefs, we assume that a student is equally likely to study/party or not: s_i sim Ber(05) for all i. Next, we model the domain logic as beginaligned t_1 = s_1\n t_2 = t_1 s_2\n t_3 = t_2 s_3 endaligned For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as t_i sim Ber(s_i) for all i.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Custom-Nodes-and-Rules","page":"Assessing People’s Skills","title":"Custom Nodes and Rules","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"using RxInfer, Random\n\n# Create Score node\nstruct Score end\n\n@node Score Stochastic [out, in]","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Adding update rule for the Score node\n@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin \n return Bernoulli(mean(q_out))\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Specification","page":"Assessing People’s Skills","title":"Generative Model Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now build the full generative model.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# GraphPPL.jl exports the `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function skill_model()\n s = randomvar(3)\n t = randomvar(3)\n r = datavar(Float64, 3)\n\n # Priors\n for i=1:3\n s[i] ~ Bernoulli(0.5)\n end\n\n # Domain logic\n t[1] ~ ¬s[1]\n t[2] ~ t[1] || s[2]\n t[3] ~ t[2] && s[3]\n \n # Results\n for i=1:3\n r[i] ~ Score(t[i])\n end\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Inference-Specification","page":"Assessing People’s Skills","title":"Inference Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"test_results = [0.1, 0.1, 0.1]\ninference_result = inference(\n model = skill_model(),\n data = (r = test_results, )\n)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Inference results:\n Posteriors | available for (s, t)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Results","page":"Assessing People’s Skills","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Inspect the results\nmap(params, inference_result.posteriors[:s])","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"3-element Vector{Tuple{Float64}}:\n (0.9872448979591837,)\n (0.06377551020408162,)\n (0.4719387755102041,)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"These results suggest that this particular student was very likely out on the town last night.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#examples-predicting-bike-rental-demand","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using RxInfer","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Preamble:-Enabling-Predictions","page":"Predicting Bike Rental Demand","title":"Preamble: Enabling Predictions","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"RxInfer.jl facilitates predictions in two primary ways. ","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.\nExplicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Example","page":"Predicting Bike Rental Demand","title":"Example","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Consider the following model:","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"@model function example_model()\n y = datavar(Float64) where {allow_missing = true}\n\n h ~ NormalMeanPrecision(0, 1.0)\n x ~ NormalMeanPrecision(h, 1.0)\n y ~ NormalMeanPrecision(x, 10.0)\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Implicit Prediction\nresult = inference(model = example_model(), data = (y = missing,))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Explicit Prediction\nresult = inference(model = example_model(), predictvars = (y = KeepLast(),))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using CSV, DataFrames, Plots","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Objective","page":"Predicting Bike Rental Demand","title":"Objective","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Dataset-Source","page":"Predicting Bike Rental Demand","title":"Dataset Source","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Load the data\ndf = CSV.read(\"../data/bike_count/modified_bicycle.csv\", DataFrame)\ndf[1:10, :]","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"10×6 DataFrame\n Row │ datetime temp atemp humidity windspeed count\n │ String31 Float64 Float64 Float64 Float64 Int64\n─────┼──────────────────────────────────────────────────────────────────\n 1 │ 2011-01-01 0:00:00 9.84 14.395 81.0 0.0 16\n 2 │ 2011-01-01 1:00:00 9.02 13.635 80.0 0.0 40\n 3 │ 2011-01-01 2:00:00 9.02 13.635 80.0 0.0 32\n 4 │ 2011-01-01 3:00:00 9.84 14.395 75.0 0.0 13\n 5 │ 2011-01-01 4:00:00 9.84 14.395 75.0 0.0 1\n 6 │ 2011-01-01 5:00:00 9.84 12.88 75.0 6.0032 1\n 7 │ 2011-01-01 6:00:00 9.02 13.635 80.0 0.0 2\n 8 │ 2011-01-01 7:00:00 8.2 12.88 86.0 0.0 3\n 9 │ 2011-01-01 8:00:00 9.84 14.395 75.0 0.0 8\n 10 │ 2011-01-01 9:00:00 13.12 17.425 76.0 0.0 14","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# we reserve few samples for prediction\nn_future = 24\n\nX = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]\ny = Union{Float64, Missing}[df[:, \"count\"]...][1:end-n_future]\n\nstate_dim = length(X[1]); # dimensionality of feature space","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Generative-Model-with-Priors","page":"Predicting Bike Rental Demand","title":"Generative Model with Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"We present a generative model that delineates the latent dynamics of feature evolution, represented by mathbfh_t, and their link to the bike rental counts, mathbfy_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Equations-and-Priors","page":"Predicting Bike Rental Demand","title":"Equations and Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Feature Dynamics with Prior:\nPrior: mathbfa sim mathcalN(mathbf0 mathbfI)\nDynamics: mathbfh_t sim mathcalN(mathbfA h_t-1 mathbfQ)\nmathbfA\nis the transition matrix, reshaped from the prior vector mathbfa, and mathbfQ represents process noise.\nNoisy Observations:\nmathbfx_t sim mathcalN(mathbfh_t mathbfP)\nRepresents the observed noisy state of the features.\nCount Prediction with Prior:\nPrior: boldsymboltheta sim mathcalN(mathbf0 mathbfI)\nPrediction: y_t sim mathcalN(textsoftplus(boldsymboltheta^topmathbfh_t) sigma^2)\nModels the bike rental count as influenced by a non-linear transformation of the hidden state.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Interpretation","page":"Predicting Bike Rental Demand","title":"Interpretation","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This framework aims to simultaneously infer the transition matrix mathbfA and the regression parameters boldsymboltheta, providing a comprehensive view of the feature space dynamics and the count prediction.\nBy employing Gaussian priors on both mathbfa and boldsymboltheta, we incorporate beliefs about their distributions.\nThe inference process aims to discover these underlying dynamics, enabling predictions of both features mathbfx_t and counts y_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We augument the dataset with missing entries for 24 hours ahead\nappend!(X, repeat([missing], n_future))\nappend!(y, repeat([missing], n_future));","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Function to perform the state transition in the model.\n# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.\nfunction transition(a, x)\n nm, n = length(a), length(x)\n m = nm ÷ n # Calculate the number of rows for reshaping 'a' into a matrix\n A = reshape(a, (m, n)) \n return A * x\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"transition (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# The dotsoftplus function combines a dot product and softplus transformation.\n# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,\n# especially if the data suggests other forms of relationships or distributions.\nfunction dotsoftplus(a, x)\n log(1 + exp(dot(a, x)))\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"dotsoftplus (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# model definction\n@model function bicycle_ssm(n, h0, θ0, a0, Q, P)\n\n # `h` is a sequence of hidden states\n h = randomvar(n)\n\n # `x` is a sequence of observed states (features)\n x = datavar(Vector{Float64}, n) where {allow_missing = true}\n # `y` is a sequence of \"count\" bicycles\n y = datavar(Float64, n) where {allow_missing = true}\n\n a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))\n\n θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))\n\n h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))\n h_prev = h_prior\n \n for i in 1:n\n \n h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)\n \n x[i] ~ MvNormal(μ=h[i], Σ=P)\n \n y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)\n \n h_prev = h[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.\n# However, alternative methods like Unscented or CVI approximations can also be considered.\ntransition_meta = @meta begin \n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Meta specification:\n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We define rather uninformative priors \nprior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))\nprior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))\nprior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"MvNormalMeanCovariance(\nμ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0\n.0, 0.0]\nΣ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … \n0.0 1.0]\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages\nimessages = ( h = prior_h, a = prior_a, θ = prior_θ,)\n\nbicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))\n\nresult = inference(\n model = bicycle_model,\n data = (y = y, x=X), \n options = (limit_stack_depth = 500, ), \n returnvars = KeepLast(),\n initmessages = imessages,\n meta = transition_meta,\n iterations = 20,\n showprogress=true,\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (a, h, h_prior, θ)\n Predictions | available for (y, x)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# For a sake of this example, we extract only predictions\nmean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])\nmean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])\n\nmean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)\nmean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)\nmean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)\nmean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"slice = (300, length(y))\ndata = df[:, \"count\"][length(y)-n_future:length(y)]\n\np = scatter(y, \n color=:darkblue, \n markerstrokewidth=0,\n label=\"Observed Count\", \n alpha=0.6)\n\n# Plotting the mean prediction with variance ribbon\nplot!(mean_y, ribbon=sqrt.(cov_y), \n color=:orange, \n fillalpha=0.3,\n label=\"Predicted Mean ± Std Dev\")\n\n# Adding a vertical line to indicate the start of the future prediction\nvline!([length(y)-n_future], \n label=\"Prediction Start\", \n linestyle=:dash, \n linecolor=:green)\n\n# Future (unobserved) data\nplot!(length(y)-n_future:length(y), data, label=\"Future Count\")\n\n# Adjusting the limits\nxlims!(slice)\n\n# Enhancing the plot with titles and labels\ntitle!(\"Bike Rental Demand Prediction\")\nxlabel!(\"Time\")\nylabel!(\"Bike Count\")\n\n# Adjust the legend\nlegend=:topright\n\n# Show the final plot\ndisplay(p)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using Plots\n\n# Define a color palette\npalette = cgrad(:viridis)\n\n# Plot the hidden states with observations\np1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label=\"Hidden State 1\", legend=:topleft)\nplot!(df[!, :temp], color=:grey, label=\"Temperature\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Temperature vs Hidden State 1\")\n\np2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label=\"Hidden State 2\", legend=:topleft)\nplot!(df[!, :atemp], color=:grey, label=\"Feels-Like Temp\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Feels-Like Temp vs Hidden State 2\")\n\np3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label=\"Hidden State 3\", legend=:topleft)\nplot!(df[!, :humidity], color=:grey, label=\"Humidity\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Humidity vs Hidden State 3\")\n\np4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label=\"Hidden State 4\", legend=:topleft)\nplot!(df[!, :windspeed], color=:grey, label=\"Windspeed\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Windspeed vs Hidden State 4\")\n\nfor p in [p1, p2, p3, p4]\n xlims!(p, first(slice), last(slice))\nend\n\nplot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Conclusion","page":"Predicting Bike Rental Demand","title":"Conclusion","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.","category":"page"},{"location":"manuals/comparison/#comparison","page":"RxInfer.jl vs. Others","title":"Comparison to other packages","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"DISCLAIMER: ","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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, and we'll be more than willing to rectify.\nThe comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Toolbox Universality Efficiency Expressiveness Debugging & Visualization Modularity Inference Engine Language Community & Ecosystem\nRxInfer.jl ~ ✓ ✓ ~ ✗ Message-passing Julia ✗\nForneyLab.jl ✗ ~ ✗ ~ ✗ Message-passing Julia ✗\nInfer.net ~ ✓ ✗ ✓ ✗ Message-passing C# ✗\nPGMax ✗ ✓ ✗ ✓ ✗ Message-passing Python ✗\nTuring.jl ✓ ✗ ✓ ~ ✗ Sampling Julia ✓\nPyMC ✓ ✗ ✓ ✓ ✗ Sampling Python ✓\nNumPyro ✓ ✓ ~ ✓ ✗ Sampling Python ✓\nTensorFlow Probability ✓ ✗ ~ ✓ ✗ Sampling Python ✓\nStan ✓ ✗ ✓ ✓ ✗ Sampling Stan ✓","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"(Date of creation: 20/10/2023)","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Legend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"✓ : Full capability or feature is present.\n~ : Partial capability or feature is present.\n✗ : No capability or feature.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Notes:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: Denotes the capability to depict a vast array of probabilistic models.\nEfficiency: Highlights computational competence. A \"–\" in this context suggests perceived slowness.\nExpressiveness: Assesses the ability to concisely formulate intricate probabilistic models.\nDebugging & Visualization: Evaluates the suite of tools for model debugging and visualization.\nModularity: Reflects the potential to create models by integrating smaller models.\nInference Engines: Pinpoints the primary inference strategy employed by the toolbox.\nLanguage: Identifies the programming language integral to the toolbox.\nCommunity & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"","category":"page"},{"location":"manuals/comparison/#RxInfer.jl-breakdown","page":"RxInfer.jl vs. Others","title":"RxInfer.jl breakdown","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.\nEfficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.\nModularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"@model function inner_inner(τ, y)\n y ~ Normal(τ[1], τ[2])\nend\n\n@model function inner(θ, α)\n β ~ Normal(0, 1)\n α ~ Gamma(β, 1)\n α ~ inner_inner(τ = θ)\nend\n\n@model function outer()\n local w\n for i = 1:5\n w[i] ~ inner(θ = Gamma(1, 1))\n end\n y ~ inner(θ = w[2:3])\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"beginaligned\n x sim mathrmNormal(00 10)\n w sim mathrmInverseGamma(10 10)\n y sim mathrmNormal(x w)\nendaligned","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"The model then is expressed in RxInfer.jl as follows:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"using RxInfer\n\n@model function example_model()\n x ~ Normal(mean=0.0, var=1.0)\n w ~ InverseGamma(α = 1, θ = 1)\n y ~ Normal(mean = x, var = w)\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#examples-infinite-data-stream","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"using RxInfer, Plots, Random, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"mutable struct Environment\n rng :: AbstractRNG\n current_state :: Float64\n observation_precision :: Float64\n history :: Vector{Float64}\n observations :: Vector{Float64}\n \n Environment(current_state, observation_precision; seed = 123) = begin \n return new(StableRNG(seed), current_state, observation_precision, [], [])\n end\nend\n\nfunction getnext!(environment::Environment)\n environment.current_state = environment.current_state + 1.0\n nextstate = 10sin(0.1 * environment.current_state)\n observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))\n push!(environment.history, nextstate)\n push!(environment.observations, observation)\n return observation\nend\n\nfunction gethistory(environment::Environment)\n return environment.history\nend\n\nfunction getobservations(environment::Environment)\n return environment.observations\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"getobservations (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Model-specification","page":"Infinite Data Stream","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"@model function kalman_filter()\n \n # Prior for the previous state\n x_prev_mean = datavar(Float64)\n x_prev_var = datavar(Float64)\n \n x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)\n \n # Prior for the observation noise\n τ_shape = datavar(Float64)\n τ_rate = datavar(Float64)\n \n τ ~ Gamma(shape = τ_shape, rate = τ_rate)\n \n # Random walk with fixed precision\n x_current ~ Normal(mean = x_prev, precision = 1.0)\n \n # Noisy observation\n y = datavar(Float64)\n y ~ Normal(mean = x_current, precision = τ)\n \nend\n\n# We assume the following factorisation between variables \n# in the variational distribution\n@constraints function filter_constraints()\n q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"filter_constraints (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Prepare-environment","page":"Infinite Data Stream","title":"Prepare environment","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"initial_state = 0.0\nobservation_precision = 0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"After we have created the environment we can observe how our signal behaves:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"testenvironment = Environment(initial_state, observation_precision);\n\nanimation = @animate for i in 1:100\n getnext!(testenvironment)\n \n history = gethistory(testenvironment)\n observations = getobservations(testenvironment)\n \n p = plot(size = (1000, 300))\n \n p = plot!(p, 1:i, history[1:i], label = \"Hidden signal\")\n p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = \"Observation\")\nend\n\ngif(animation, \"../pics/infinite-data-stream.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-static-dataset","page":"Infinite Data Stream","title":"Filtering on static dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"n = 300\nstatic_environment = Environment(initial_state, observation_precision);\n\nfor i in 1:n\n getnext!(static_environment)\nend\n\nstatic_history = gethistory(static_environment)\nstatic_observations = getobservations(static_environment);\nstatic_datastream = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_static(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n engine = rxinference(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n keephistory = 10_000,\n historyvars = (x_current = KeepLast(), τ = KeepLast()),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n free_energy = true,\n autostart = true,\n )\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_static (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"result = run_static(static_environment, static_datastream);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"static_inference = @animate for i in 1:n\n estimated = result.history[:x_current]\n p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = \"Estimation\")\n p = plot!(static_history[1:i], label = \"Real states\") \n p = scatter!(static_observations[1:i], ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\nend\n\ngif(static_inference, \"../pics/infinite-data-stream-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"plot(result.free_energy_history, label = \"Bethe Free Energy (averaged)\")","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-realtime-dataset","page":"Infinite Data Stream","title":"Filtering on realtime dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"Next lets create a \"real\" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_and_plot(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n posteriors = []\n \n plotfn = (q_current) -> begin \n IJulia.clear_output(true)\n \n push!(posteriors, q_current)\n\n p = plot(mean.(posteriors), ribbon = var.(posteriors), label = \"Estimation\")\n p = plot!(gethistory(environment), label = \"Real states\") \n p = scatter!(getobservations(environment), ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\n\n display(p)\n end\n \n engine = rxinference(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n autostart = false,\n )\n \n qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)\n \n RxInfer.start(engine)\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_and_plot (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# This example runs in our documentation pipeline, which does not support \"real-time\" execution context\n# We skip this code if run not in Jupyter notebook (see below an example with gif)\nengine = nothing \nif isdefined(Main, :IJulia)\n timegen = 41 # 41 ms\n environment = Environment(initial_state, observation_precision);\n observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations\n datastream = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));\n engine = run_and_plot(environment, datastream)\nend;","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"if !isnothing(engine) && isdefined(Main, :IJulia)\n RxInfer.stop(engine)\n IJulia.clear_output(true)\nend;","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#examples-universal-mixtures","page":"Universal Mixtures","title":"Universal Mixtures","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"using RxInfer, Distributions, Random, Plots","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y_i mid theta) = mathrmBer(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where y_i in 01 are the outcomes of the coin tosses, i.e. heads or tails, and where theta is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter theta, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of thetain01 they come up with the prior beliefs:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJohn) = mathrmBeta(theta mid 7 2)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJane) = mathrmBeta(theta mid 2 7)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior beliefs\")\nplot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) John\", c=1)\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"p(θ) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"true_coin = Bernoulli(0.25)\nnr_throws = 10\ndataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))\nnr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)\nprintln(\"experimental outcome: \\n - heads: \", nr_heads, \"\\n - tails: \", nr_tails);","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"experimental outcome: \n - heads: 3\n - tails: 7","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"For computing the posterior beliefs p(theta mid y) about the parameter theta, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#John's-model:","page":"Universal Mixtures","title":"John's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJohn) = p(theta mid textJohn) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_john(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's prior model over θ\n θ ~ Beta(7.0, 2.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#Jane's-model:","page":"Universal Mixtures","title":"Jane's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJane) = p(theta mid textJane) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_jane(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify Jane's prior model over θ\n θ ~ Beta(2.0, 7.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy mathrmF_B bounds the model evidence p(y) as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"mathrmF_Bpq geq - ln p(y)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_john = inference(\n model = beta_model_john(nr_throws), \n data = (y = dataset, ),\n free_energy = true,\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[8.96366]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_jane = inference(\n model = beta_model_jane(nr_throws), \n data = (y = dataset, ),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[6.63988]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying theta parameter. They formulate this through the posterior distributions p(theta mid y textJohn) and p(theta mid y textJane):","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior beliefs\")\nplot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) John\", c=1)\nplot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"p(θ|y) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over theta, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta c mid textMary) = p(c mid textMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where c describes the probability of John being correct as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(c mid textMary) = mathrmBer(c mid 07)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"The predictive distribution p(theta mid textMary) for theta (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over c as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textMary) = sum_cin01 p(cmidtextMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c = 07 cdot p(theta mid textJohn) + 03 cdot p(theta mid textJane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior belief\")\nplot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) Mary\", c=1)\nplot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label=\"\")\nplot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label=\"\")","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_mary(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's and Jane's prior models over θ\n θ_jane ~ Beta(2.0, 7.0)\n θ_john ~ Beta(7.0, 2.0)\n\n # specify initial guess as to who is right\n john_is_right ~ Bernoulli(0.7) \n\n # specify mixture prior Distribution\n θ ~ Mixture(john_is_right, (θ_jane, θ_john))\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This Mixture node updates the belief over c on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_mary = inference(\n model = beta_model_mary(nr_throws), \n data = (y = dataset, ),\n returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),\n addons = AddonLogScale(),\n postprocess = UnpackMarginalPostprocess(),\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (john_is_right, θ_john, θ, θ_jane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over theta also changed, and as expected the estimate from Jane was more prominent.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior belief\")\nplot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) Mary\", c=1)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label=\"\", c=3)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label=\"\", c=3)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/overview/#examples-basic_examples-overview","page":"Overview","title":"Basic examples","text":"","category":"section"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.\nBayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.\nKalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations\nPredicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.\nHow to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#examples-global-parameter-optimisation","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Univariate-State-Space-Model","page":"Global Parameter Optimisation","title":"Univariate State Space Model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us try use the following simple state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n x_t = x_t-1 + c \n y_t sim mathcalNleft(x_t p right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Our goal is to optimize parameters c and m_x_0.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)\n \n x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n)\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ x_prev + c\n y[i] ~ NormalMeanVariance(x[i], P)\n \n x_prev = x[i]\n end\n\n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"rng = MersenneTwister(42)\n\nP = 1.0\nn = 250\nc_real = -5.0\ndata = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# c[1] is C\n# c[2] is μ0\nfunction f(c)\n x0_prior = NormalMeanVariance(c[2], 100.0)\n result = inference(\n model = smoothing(n, x0_prior, c[1], P), \n data = (y = data,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using Optim","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 3.651509e+02 1.001412e+03\n * time: 0.04605293273925781\n * Status: success\n\n * Candidate solution\n Final objective value: 3.645772e+02\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.18e-06 ≰ 0.0e+00\n |x - x'|/|x'| = 2.30e-07 ≰ 0.0e+00\n |f(x) - f(x')| = 9.13e-07 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00\n |g(x)| = 2.56e-06 ≤ 1.0e-03\n\n * Work counters\n Seconds run: 6 (vs limit Inf)\n Iterations: 9\n f(x) calls: 67\n ∇f(x) calls: 67","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"2-element Vector{Float64}:\n 1.0007749243942134\n -5.14368311177876","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", [ 1.0, c_real ])\nprintln(\"Optimized: \", res.minimizer)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: [1.0, -5.0]\nOptimized: [1.0007749243942134, -5.14368311177876]","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Multivariate-state-space-model","page":"Global Parameter Optimisation","title":"Multivariate state space model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us consider the multivariate state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n mathbfx_t sim mathcalNleft(mathbfAx_t-1 mathbfQ right) \n mathbfy_t sim mathcalNleft(mathbfx_t mathbfP right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfx_0 sim mathcalN(mathbfm_x_0 mathbfV_x_0)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"and transition matrix ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfA = beginbmatrix costheta -sintheta sintheta costheta endbmatrix\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Covariance matrices mathbfV_x_0, mathbfP and mathbfQ are known. Our goal is to optimize parameters mathbfm_x_0 and theta.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)\n \n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n \n x_prev = x_prior\n \n A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)\n y[i] ~ MvNormalMeanCovariance(x[i], P)\n \n x_prev = x[i]\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Generate data\nfunction generate_rotate_ssm_data()\n rng = MersenneTwister(1234)\n\n θ = π / 8\n A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\n Q = Matrix(Diagonal(1.0 * ones(2)))\n P = Matrix(Diagonal(1.0 * ones(2)))\n\n n = 300\n\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n \n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(x[i], Q))\n \n x_prev = x[i]\n end\n\n return θ, A, Q, P, n, x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"generate_rotate_ssm_data (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"θ, A, Q, P, n, x, y = generate_rotate_ssm_data();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function f(θ)\n x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))\n result = inference(\n model = rotate_ssm(n, θ[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 2.192003e+04 9.032537e+04\n * time: 7.200241088867188e-5\n * Status: success\n\n * Candidate solution\n Final objective value: 1.161372e+03\n\n * Found with\n Algorithm: L-BFGS\n\n * Convergence measures\n |x - x'| = 5.09e-09 ≰ 0.0e+00\n |x - x'|/|x'| = 4.48e-10 ≰ 0.0e+00\n |f(x) - f(x')| = 0.00e+00 ≤ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14\n |g(x)| = 5.63e-07 ≰ 1.0e-12\n\n * Work counters\n Seconds run: 19 (vs limit Inf)\n Iterations: 9\n f(x) calls: 58\n ∇f(x) calls: 58","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", θ)\nprintln(\"Optimized: \", res.minimizer[1])\n\n@show sin(θ), sin(res.minimizer[1])\n@show cos(θ), cos(res.minimizer[1])","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: 0.39269908169872414\nOptimized: 0.3929332481380117\n(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)\n(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)\n(0.9238795325112867, 0.9237898955654058)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))\n\nresult = inference(\n model = rotate_ssm(n, res.minimizer[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n)\n\nxmarginals = result.posteriors[:x]\n\npx = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"inf₁\")\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"inf₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Learning-Kalman-filter-with-LSTM-driven-dynamic","page":"Global Parameter Optimisation","title":"Learning Kalman filter with LSTM driven dynamic","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Our objective is to compute the marginal posterior distribution of the latent (hidden) state x_k at each time step k, considering the history of measurements up to that time step:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"\np(x_k y_1k)\n\n\nThe above expression represents the probability distribution of the latent state x_k given the measurements y_1k up to time step k\n\njulia\nusing RxInfer BenchmarkTools Flux ReverseDiff Random Plots LinearAlgebra ProgressMeter JLD StableRNGs\n\n\n\n\n Generate data\n\njulia\n Lorenz system equations to be used to generate dataset\nBasekwdef mutable struct Lorenz\n dtFloat64\n σFloat64\n ρFloat64\n βFloat64\n xFloat64\n yFloat64\n zFloat64\nend\n\nfunction step(lLorenz)\n dx = lσ * (ly - lx) lx += ldt * dx\n dy = lx * (lρ - lz) - ly ly += ldt * dy\n dz = lx * ly - lβ * lz lz += ldt * dz\nend\n\n\n\n\njulia\n Dataset\nrng = StableRNG(999)\n\nordered_dataset = \nordered_parameters = \nfor σ = 1115\n for ρ = 2327\n for β_nom = 69\n attractor = Lorenz(002 σ ρ β_nom30 1 1 1)\n noise_free_data = 10 10 10\n for i=199\n step(attractor)\n push(noise_free_data attractorx attractory attractorz)\n end\n push(ordered_dataset noise_free_data)\n push(ordered_parameters σ ρ β_nom30)\n end\n end\nend\n\nnew_order = collect(1100)\nshuffle(rngnew_order)\n\ndataset = noisy dataset\nnoise_free_dataset = noise free dataset\nlorenz_parameters = \n\nfor i in new_order\n local data = \n push(noise_free_dataset ordered_dataseti)\n push(lorenz_parameters ordered_parametersi)\n for nfd in ordered_dataseti\n push(datanfd+randn(rng3))\n end\n push(dataset data)\nend\n\ntrainset = dataset160\nvalidset = dataset6180\ntestset = dataset81end\n\nnoise_free_trainset = noise_free_dataset160\nnoise_free_validset = noise_free_dataset6180\nnoise_free_testset = noise_free_dataset81end\n\n\n\n\n\n Data visualization\n\njulia\none_nonoise=noise_free_trainset1\none=trainset1\ngx gy gz = zeros(100) zeros(100) zeros(100)\nrx ry rz = zeros(100) zeros(100) zeros(100)\nfor i=1100\n rxi ryi rzi = onei1 onei2 onei3\n gxi gyi gzi = one_nonoisei1 one_nonoisei2 one_nonoisei3\nend\np1=plot(rxrylabel=Noise observations)\np1=plot(gxgylabel=True state)\nxlabel(x)\nylabel(y)\np2=plot(rxrzlabel=Noise observations)\np2=plot(gxgzlabel=True state)\nxlabel(x)\nylabel(z)\np3=plot(ryrzlabel=Noise observations)\np3=plot(gygzlabel=True state)\nxlabel(y)\nylabel(z)\nplot(p1 p2 p3 size = (800 200)layout=(13))\n\n\n(assetsexamplesGlobal Parameter Optimisation_22_1png)\n\n\n Inference\n\n\nWe use the following state-space model representation\n\nbeginaligned\nx_k sim p(x_k x_k-1) \ny_k sim p(y_k x_k)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where x_k sim p(x_k x_k-1) represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k-1=NN(y_k-1) \np(x_k x_k-1)=mathcalN(x_k A_k-1x_k-1 Q) \np(y_k x_k)=mathcalN(y_k Bx_k R)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where NN is the neural network. The input is the observation y_k-1, and output is the trasition matrix A_k-1. B denote distortion or measurment matrix. Q and R are covariance matrices. Note that the hidden state x_k comprises three coordinates, i.e. x_k = (rx_k ry_k rz_k)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Neural Network model\nmutable struct NN\n InputLayer\n OutputLater\n g\n params\n function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n InputLayer = Dense(W1, b1, relu)\n Lstm = LSTM(W2_1,W2_2,b2,s2_1)\n OutputLayer = Dense(W3, b3)\n g = Chain(InputLayer, OutputLayer);\n new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))\n end\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Model-specification","page":"Global Parameter Optimisation","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Note that we treat the trasition matrix A_k-1 as time-varying.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#State Space Model\n@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)\n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior_mean = zeros(3)\n x_prior_cov = Matrix(Diagonal(ones(3)))\n \n x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)\n y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }\n \n for i in 2:n\n x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }\n y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }\n end\n \n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We set distortion matrix B and the covariance matrices Q and R as identity matrix.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Q = Matrix(Diagonal(ones(3)))*2\nB = Matrix(Diagonal(ones(3)))\nR = Matrix(Diagonal(ones(3)))\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix A output by the neural network. And the A is treated as a datavar in the inference function.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n n = length(data)\n neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])\n return As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"get_matrix_AS (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"The weights of neural network NN are initialized as follows:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Initial model parameters\nW1, b1 = randn(5, 3)./100, randn(5)./100\nW2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)\nW3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Before network training, we show the inference results for the hidden states:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset before training\nindex = 1\ndata=testset[index]\nn=length(data)\nresult = inference(\n model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training-network","page":"Global Parameter Optimisation","title":"Training network","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this part, we use the Free Energy as the objective function to optimize the weights of network.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# free energy objective to be optimized during training\nfunction fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n fe_ = 0\n for train_instance in trainset\n result = inference(\n model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = train_instance, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n )\n fe_ += result.free_energy[end]\n end\n return fe_\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"fe_tot_est (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training","page":"Global Parameter Optimisation","title":"Training","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights\n# Uncomment the following code to train the network manually\n# opt = Flux.Optimise.RMSProp(0.006, 0.95)\n# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n# @showprogress for epoch in 1:800\n# grads = ReverseDiff.gradient(fe_tot_est, params);\n# for i=1:length(params)\n# Flux.Optimise.update!(opt,params[i],grads[i])\n# end\n# end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Test","page":"Global Parameter Optimisation","title":"Test","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Import the weights of neural network that we have trained.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load(\"../data/nn_prediction/weights.jld\")[\"data\"];","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset after training\nindex = 1\ndata = testset[index]\nn = length(data)\nresult = inference(\n model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\n\ngx, gy, gz = zeros(100), zeros(100), zeros(100)\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Prediction","page":"Global Parameter Optimisation","title":"Prediction","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill k and estimate the future state at time k+1, k+2, dots,k+T.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k=NN(x_k) \np(x_k+1 x_k)=mathcalN(x_k+1 A_kx_k Q) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#Define the prediction function\nmultiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))\nsumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)\n\nfunction runForward(A,B,Q,R,mh_old,Vh_old)\n mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)\n mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)\nend\n\nfunction g_predict(mh_old,Vh_old,Q)\n neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)\n # Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])\n As = As[1]\n return runForward(As,B,Q,R,mh_old,Vh_old), As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"g_predict (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"After k=75, the observations are not available, and we predict the future state from k=76 to the end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"tt = 75\nmh = mean(x_est[tt])\nVh = cov(x_est[tt])\nmo_list, Vo_list, A_list = [], [], [] \ninv_Q = inv(Q)\nfor t=1:100-tt\n (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)\n push!(mo_list, mo)\n push!(Vo_list, Vh)\n push!(A_list, A_t)\n global mh = mo\n global Vh = Vo\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Prediction visualization\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\nfor i=1:tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\nfor i=tt+1:100\n ii=i-tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]\nend\np1 = plot(rx,label=\"Ground truth rx\")\np1 = plot!(rx_est_m,label=\"Inffered state rx\",ribbon=rx_est_var)\np1 = scatter!(first.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Ground truth ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index][1:tt], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Ground truth rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#examples-autoregressive-models","page":"Autoregressive Models","title":"Autoregressive Models","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\np(gamma) = mathrmGamma(gammaa b)\np(mathbftheta) = mathcalN(mathbfthetamathbfmu Sigma)\np(x_tmathbfx_t-1t-k) = mathcalN(x_tmathbftheta^Tmathbfx_t-1t-k gamma^-1)\np(y_tx_t) = mathcalN(y_tx_t tau^-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where x_t is a current state of our system, mathbfx_t-1t-k is a sequence of k previous states, k is an order of autoregression process, mathbftheta is a vector of transition coefficients, gamma is a precision of state transition process, y_k is a noisy observation of x_k with precision tau.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's generate some synthetic dataset, we use a predefined sets of coeffcients for k = 1, 3 and 5 respectively:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The following coefficients correspond to stable poles\ncoefs_ar_1 = [-0.27002517200218096]\ncoefs_ar_2 = [0.4511170798064709, -0.05740081602446657]\ncoefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"function generate_ar_data(rng, n, θ, γ, τ)\n order = length(θ)\n states = Vector{Vector{Float64}}(undef, n + 3order)\n observations = Vector{Float64}(undef, n + 3order)\n \n γ_std = sqrt(inv(γ))\n τ_std = sqrt(inv(τ))\n \n states[1] = randn(rng, order)\n \n for i in 2:(n + 3order)\n states[i] = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])\n observations[i] = rand(rng, Normal(states[i][1], τ_std))\n end\n \n return states[1+3order:end], observations[1+3order:end]\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"generate_ar_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Seed for reproducibility\nseed = 123\nrng = MersenneTwister(seed)\n\n# Number of observations in synthetic dataset\nn = 500\n\n# AR process parameters\nreal_γ = 1.0\nreal_τ = 0.5\nreal_θ = coefs_ar_5\n\nstates, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's plot our synthetic dataset:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(first.(states), label = \"Hidden states\")\nscatter!(observations, label = \"Observations\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order k > 1 and for Univariate AR (reduces to simple State-Space-Model) with order k = 1.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function lar_model(T::Type, n, order, c, τ)\n \n \n # We create a sequence of random variables for hidden states\n x = randomvar(n)\n # As well a sequence of observartions\n y = datavar(Float64, n)\n \n ct = constvar(c)\n # We assume observation noise to be known\n cτ = constvar(τ)\n \n γ = randomvar()\n θ = randomvar()\n x0 = randomvar()\n \n # Prior for first state\n if T === Multivariate\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n else\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ Normal(μ = 0.0, γ = 1.0)\n x0 ~ Normal(μ = 0.0, γ = 1.0)\n end\n \n x_prev = x0\n \n for i in 1:n\n \n x[i] ~ AR(x_prev, θ, γ) \n \n if T === Multivariate\n y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)\n else\n y[i] ~ Normal(μ = ct * x[i], γ = cτ)\n end\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@constraints function ar_constraints() \n q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_constraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@meta function ar_meta(artype, order, stype)\n AR() -> ARMeta(artype, order, stype)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_meta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"morder = 5\nmartype = Multivariate\nmc = ReactiveMP.ar_unit(martype, morder)\nmconstraints = ar_constraints()\nmmeta = ar_meta(martype, morder, ARsafe())\n\nmoptions = (limit_stack_depth = 100, )\n\nmmodel = lar_model(martype, length(observations), morder, mc, real_τ)\nmdata = (y = observations, )\nminitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))\nmreturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\n# First execution is slow due to Julia's initial compilation \n# Subsequent runs will be faster (benchmarks are below)\nmresult = inference(\n model = mmodel, \n data = mdata,\n constraints = mconstraints,\n meta = mmeta,\n options = moptions,\n initmarginals = minitmarginals,\n returnvars = mreturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@unpack x, γ, θ = mresult.posteriors","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Dict{Symbol, Vector} with 3 entries:\n :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)\n, Ga…\n :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…\n :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We will use different initial marginals depending on type of our AR process","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p1 = plot(first.(states), label=\"Hidden state\")\np1 = scatter!(p1, observations, label=\"Observations\")\np1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label=\"Inferred states\", legend = :bottomright)\n\np2 = plot(mean.(γ), ribbon = std.(γ), label = \"Inferred transition precision\", legend = :topright)\np2 = plot!([ real_γ ], seriestype = :hline, label = \"Real transition precision\")\n\np3 = plot(mresult.free_energy, label = \"Bethe Free Energy\")\n\nplot(p1, p2, p3, layout = @layout([ a; b c ]))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's also plot a subrange of our results:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"subrange = div(n,5):(div(n, 5) + div(n, 5))\n\nplot(subrange, first.(states)[subrange], label=\"Hidden state\")\nscatter!(subrange, observations[subrange], label=\"Observations\")\nplot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label=\"Inferred states\", legend = :bottomright)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"It is also interesting to see where our AR coefficients converge to:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"let\n pθ = plot()\n\n θms = mean.(θ)\n θvs = var.(θ)\n \n l = length(θms)\n\n edim(e) = (a) -> map(r -> r[e], a)\n\n for i in 1:length(first(θms))\n pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = \"Estimated θ[$i]\")\n end\n \n for i in 1:length(real_θ)\n pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = \"Real θ[$i]\")\n end\n \n plot(pθ, legend = :outertopright, size = (800, 300))\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"$(length(real_θ))-order AR inference Bethe Free Energy: \", last(mresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"5-order AR inference Bethe Free Energy: 1024.0766194723828","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can also run a 1-order AR inference on 5-order AR data:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"uorder = 1\nuartype = Univariate\nuc = ReactiveMP.ar_unit(uartype, uorder)\nuconstraints = ar_constraints()\numeta = ar_meta(uartype, uorder, ARsafe())\n\nuoptions = (limit_stack_depth = 100, )\n\numodel = lar_model(uartype, length(observations), uorder, uc, real_τ)\nudata = (y = observations, )\nuinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))\nureturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\nuresult = inference(\n model = umodel, \n data = udata,\n meta = umeta,\n constraints = uconstraints,\n initmarginals = uinitmarginals,\n returnvars = ureturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"1-order AR inference Bethe Free Energy: \", last(uresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1-order AR inference Bethe Free Energy: 1025.8792949319954","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"if uresult.free_energy[end] > mresult.free_energy[end]\n println(\"We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.\")\nelse\n error(\"AR-1 performs better than AR-5...\") \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can see that, according to final Bethe Free Energy value, in this exampl\ne 5-order AR process can describe data better than 1-order AR.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Autoregressive-Moving-Average-Model","page":"Autoregressive Models","title":"Autoregressive Moving Average Model","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\ne_t sim mathcalN(0 gamma^-1) quad\ntheta sim mathcalMN(mathbf0 mathbfI) quad\neta sim mathcalMN(mathbf0 mathbfI) \nmathbfh_0 sim mathcalMNleft(beginbmatrix\ne_-1 \ne_-2\nendbmatrix mathbfIright) \nmathbfh_t = mathbfSmathbfh_t-1 + mathbfc e_t-1 \nmathbfx_t = boldsymboltheta^topmathbfx_t-1 + boldsymboleta^topmathbfh_t + e_t \nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where shift matrix mathbfS is","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfS = beginpmatrix\n0 0 \n1 0 \nendpmatrix\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"and unit vector mathbfc: ","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfc=1 0\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"when MA order is 2","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this way, mathbfh_t containing errors e_t can be viewed as hidden state.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., boldsymboleta^topmathbfh_t, (2) induced by errors e_t that prevents analytical update of precision parameter gamma (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Load packages\nusing RxInfer, LinearAlgebra, CSV, DataFrames, Plots","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Define shift function\nfunction shift(dim)\n S = Matrix{Float64}(I, dim, dim)\n for i in dim:-1:2\n S[i,:] = S[i-1, :]\n end\n S[1, :] = zeros(dim)\n return S\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"shift (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)\n \n c = zeros(p); c[1] = 1.0; # AR\n b = zeros(q); b[1] = 1.0; # MA\n S = shift(q); # MA\n \n # initialize variables\n h = randomvar(n-1)\n e = randomvar(n)\n z = randomvar(n)\n \n x = datavar(Float64, n) where { allow_missing = true }\n \n # priors\n γ ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))\n η ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))\n θ ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))\n τ ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))\n \n # initial\n h_0 ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))\n z[1] ~ AR(h_0, η, τ)\n e[1] ~ Normal(mean = 0.0, precision = γ)\n\n x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]\n \n h_prev = h_0\n for t in 1:n-1\n \n e[t+1] ~ Normal(mean = 0.0, precision = γ)\n h[t] ~ S*h_prev + b*e[t]\n z[t+1] ~ AR(h[t], η, τ)\n x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]\n h_prev = h[t]\n end\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"x_df = CSV.read(\"../data/arma/aal_stock.csv\", DataFrame)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1259×7 DataFrame\n Row │ date open high low close volume Name\n │ Date Float64 Float64 Float64 Float64 Int64 String3\n──────┼───────────────────────────────────────────────────────────────────\n 1 │ 2013-02-08 15.07 15.12 14.63 14.75 8407500 AAL\n 2 │ 2013-02-11 14.89 15.01 14.26 14.46 8882000 AAL\n 3 │ 2013-02-12 14.45 14.51 14.1 14.27 8126000 AAL\n 4 │ 2013-02-13 14.3 14.94 14.25 14.66 10259500 AAL\n 5 │ 2013-02-14 14.94 14.96 13.16 13.99 31879900 AAL\n 6 │ 2013-02-15 13.93 14.61 13.93 14.5 15628000 AAL\n 7 │ 2013-02-19 14.33 14.56 14.08 14.26 11354400 AAL\n 8 │ 2013-02-20 14.17 14.26 13.15 13.33 14725200 AAL\n ⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮\n 1253 │ 2018-01-30 52.45 53.05 52.36 52.59 4741808 AAL\n 1254 │ 2018-01-31 53.08 54.71 53.0 54.32 5962937 AAL\n 1255 │ 2018-02-01 54.0 54.64 53.59 53.88 3623078 AAL\n 1256 │ 2018-02-02 53.49 53.99 52.03 52.1 5109361 AAL\n 1257 │ 2018-02-05 51.99 52.39 49.75 49.76 6878284 AAL\n 1258 │ 2018-02-06 49.32 51.5 48.79 51.18 6782480 AAL\n 1259 │ 2018-02-07 50.91 51.98 50.89 51.4 4845831 AAL\n 1244 rows omitted","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# we will use \"close\" column\nx_data = filter(!ismissing, x_df[:, 5]);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Plot data\nplot(x_data, xlabel=\"day\", ylabel=\"price\", label=false)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p_order = 10 # AR\nq_order = 4 # MA","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"4","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Training set\ntrain_size = 1000\nx_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]\nx_train = Float64.(x_data[p_order+1:end])[1:train_size];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Test set\nx_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]\nx_test = Float64.(x_data[p_order+1:end])[train_size+1:end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Inference","page":"Autoregressive Models","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Constraints are needed for performing VMP\narma_constraints = @constraints begin\n q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)\nend;","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# This cell defines prior knowledge for model parameters\nh_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nγ_prior = GammaShapeRate(1e4, 1.0)\nτ_prior = GammaShapeRate(1e2, 1.0)\nη_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nθ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Model's graph has structural loops, hence, it requires pre-initialisation\narma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);\narma_imessages = (h_0 = h_prior, h = h_prior);\narma_meta = ar_meta(Multivariate, q_order, ARsafe());","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"result = inference(\n model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), \n data = (x = x_train, ),\n initmarginals = arma_imarginals,\n initmessages = arma_imessages,\n constraints = arma_constraints,\n meta = arma_meta,\n iterations = 50,\n options = (limit_stack_depth = 400, ),\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = \"eₜ\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# extract posteriors\nh_posterior = result.posteriors[:h][end][end]\nγ_posterior = result.posteriors[:γ][end]\nτ_posterior = result.posteriors[:τ][end]\nη_posterior = result.posteriors[:η][end]\nθ_posterior = result.posteriors[:θ][end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Prediction","page":"Autoregressive Models","title":"Prediction","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Here we are going to use our inference results in order to predict the dataset itself","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The prediction function is aimed at approximating the predictive posterior distribution\n# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)\nfunction prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)\n h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))\n ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))\n c = zeros(p); c[1] = 1.0\n b = zeros(q); b[1] = 1.0\n ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)\n θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))\n ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)\n e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))\n ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out) \n @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out) \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"prediction (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"predictions = []\nfor x_prev in x_prev_test\n push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))\n # after every new prediction we can actually \"retrain\" the model to use the power of Bayesian approach\n # we will skip this part at this notebook\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(x_test, label=\"test data\", legend=:topleft)\nplot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label=\"predicted\", xlabel=\"day\", ylabel=\"price\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/#examples-how-to-train-your-hidden-markov-model","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"","category":"section"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate()\n;","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time t, let's call the estimate of the Roomba's position s_t.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call A.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"At time t, we will call our observations x_t and encode the mapping from the Roomba's position to the observations in a matrix we call B. B also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"beginaligned\n s_t sim mathcalCat(A s_t-1)\n x_t sim mathcalCat(B s_t)\nendaligned","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices A and B so we can use them to track the whereabouts of our little cleaning agent.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"To generate our observation data, we'll follow these steps:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.\nDetermine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.\nDetermine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.\nRepeat steps 2-3 for as many samples as we want.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"The following code implements this process and generates our observation data:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"\"\"\"\n rand_vec(rng, distribution::Categorical)\n\nThis function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.\n\"\"\"\nfunction rand_vec(rng, distribution::Categorical) \n k = ncategories(distribution)\n s = zeros(k)\n drawn_category = rand(rng, distribution)\n s[drawn_category] = 1.0\n return s\nend\n\nfunction generate_data(n_samples; seed = 42)\n \n rng = MersenneTwister(seed)\n \n # Transition probabilities \n state_transition_matrix = [0.9 0.0 0.1;\n 0.0 0.9 0.1; \n 0.05 0.05 0.9] \n # Observation noise\n observation_distribution_matrix = [0.9 0.05 0.05;\n 0.05 0.9 0.05;\n 0.05 0.05 0.9] \n # Initial state\n s_initial = [1.0, 0.0, 0.0] \n \n states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states\n observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations\n \n s_prev = s_initial\n \n for t = 1:n_samples\n s_probvec = state_transition_matrix * s_prev\n states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))\n obs_probvec = observation_distribution_matrix * states[t]\n observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))\n s_prev = states[t]\n end\n \n return observations, states\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Test data\nN = 100\nx_data, s_data = generate_data(N);\n\nscatter(argmax.(s_data), leg=false, xlabel=\"Time\",yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the A and B matrices we can use MatrixDirichlet priors. For the A-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on A with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on B. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Model specification\n@model function hidden_markov_model(n)\n \n A ~ MatrixDirichlet(ones(3,3))\n B ~ MatrixDirichlet([ 10.0 1.0 1.0; \n 1.0 10.0 1.0; \n 1.0 1.0 10.0 ])\n \n s_0 ~ Categorical(fill(1.0 / 3.0, 3))\n \n s = randomvar(n)\n x = datavar(Vector{Float64}, n)\n \n s_prev = s_0\n \n for t in 1:n\n s[t] ~ Transition(s_prev, A) \n x[t] ~ Transition(s[t], B)\n s_prev = s[t]\n end\n \nend\n\n# Constraints specification\n@constraints function hidden_markov_model_constraints()\n q(s_0, s, A, B) = q(s_0, s)q(A)q(B)\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"hidden_markov_model_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"imodel = hidden_markov_model(N)\nidata = (x = x_data,)\n\nimarginals = (\n A = vague(MatrixDirichlet, 3, 3), \n B = vague(MatrixDirichlet, 3, 3), \n s = vague(Categorical, 3)\n)\n\nireturnvars = (\n A = KeepLast(),\n B = KeepLast(),\n s = KeepLast()\n)\n\nresult = inference(\n model = imodel, \n data = idata,\n constraints = hidden_markov_model_constraints(),\n initmarginals = imarginals, \n returnvars = ireturnvars, \n iterations = 20, \n free_energy = true\n);","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over A) and about the uncertainty in the roombas observations (A good posterior over B). Let's see if it worked","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for A:\")\nmean(result.posteriors[:A])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for A:\n3×3 Matrix{Float64}:\n 0.871955 0.0290008 0.0572283\n 0.0349989 0.817591 0.135675\n 0.0930457 0.153408 0.807097","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for B:\")\nmean(result.posteriors[:B])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for B:\n3×3 Matrix{Float64}:\n 0.949636 0.0974741 0.0518997\n 0.0244903 0.833632 0.0277884\n 0.0258734 0.0688939 0.920312","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"p1 = scatter(argmax.(s_data), \n title=\"Inference results\", \n label = \"Real\", \n ms = 6, \n legend=:right,\n xlabel=\"Time\" ,\n yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]),\n size=(900,550)\n )\n\np1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),\n label = \"Inferred\",\n ms = 3\n )\n\np2 = plot(result.free_energy, \n label=\"Free energy\",\n xlabel=\"Iteration Number\"\n )\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#examples-rts-vs-bifm-smoothing","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"___Credits to Martin de Quincey___","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762\nH. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"We perform Kalman smoothing in the linear state space model, represented by:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n Z_k+1 = A Z_k + B U_k \n Y_k = C Z_k + W_k\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"with observations Y_k, latent states Z_k and inputs U_k. W_k is the observation noise. A in mathrmR^n times n, B in mathrmR^n times m and C in mathrmR^d times n are the transition matrices in the model. Here n, m and d denote the dimensionality of the latent, input and output dimension, respectively.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"The corresponding probabilistic model can be represented as ","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n p(y z u)\n = p(z_0) prod_k=1^N p(y_k mid z_k) p(z_kmid z_k-1 u_k-1) p(u_k-1) \n = mathcalN(z_0 mid mu_z_0 Sigma_z_0) left( prod_k=1^N mathcalN(y_k mid C z_k Sigma_W) delta(z_k - (Az_k-1 + Bu_k-1)) mathcalN(u_k-1 mid mu_i_k-1 Sigma_u_k-1) right)\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Import-packages","page":"RTS vs BIFM Smoothing","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Data-generation","page":"RTS vs BIFM Smoothing","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)\n \n # define noise levels\n input_noise = 500.0\n output_noise = 50.0\n\n # create random generator for reproducibility\n rng = MersenneTwister(seed)\n\n # generate matrices, input statistics and noise matrices\n A = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat)) # size (dim_lat x dim_lat)\n B = rand(dim_lat, dim_in) # size (dim_lat x dim_in)\n C = rand(dim_out, dim_lat) # size (dim_out x dim_lat)\n μu = rand(dim_in) .* collect(1:dim_in) # size (dim_in x 1)\n Σu = input_noise .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in)))) # size (dim_in x dim_in)\n Σy = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out)))) # size (dim_out x dim_out)\n Wu = inv(Σu)\n Wy = inv(Σy)\n \n # return parameters\n return A, B, C, μu, Σu, Σy, Wu, Wy\n\nend;","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)\n \n # create random data generator\n rng = StableRNG(seed)\n \n # preallocate space for variables\n z = Vector{Vector{Float64}}(undef, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n u = rand(rng, MvNormal(μu, Σu), nr_samples)'\n \n # set initial value of latent states\n z_prev = zeros(size(A,1))\n \n # generate data\n for i in 1:nr_samples\n\n # generate new latent state\n z[i] = A * z_prev + B * u[i,:]\n\n # generate new observation\n y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))\n \n # generate new observation\n z_prev .= z[i]\n \n end\n \n # return generated data\n return z, y, u\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# specify settings\nnr_samples = 200\ndim_out = 3\ndim_in = 3\ndim_lat = 25\n\n# generate parameters\nA, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);\n \n# generate data\ndata_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);\n\n# visualise data\np = Plots.plot(xlabel = \"sample\", ylabel = \"observations\")\n# plot each dimension independently\nfor i in 1:dim_out\n Plots.scatter!(p, getindex.(data_y, i), label = \"y_$i\", alpha = 0.5, ms = 2)\nend\np","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Model-specification","page":"RTS vs BIFM Smoothing","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n \n # fetch dimensionality\n dim_lat = size(A, 1)\n dim_out = size(C, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # hidden states (random variable)\n u = randomvar(nr_samples) # inputs (random variable)\n y = datavar(Vector{Float64}, nr_samples) # outputs (observed variables)\n \n # set initial hidden state\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n \n # update last/previous hidden state\n z_prev = z_prior\n\n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n \n # specify updated hidden state\n z[i] ~ A * z_prev + B * u[i]\n \n # specify observation\n y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n\n # fetch dimensionality\n dim_lat = size(A, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # latent states\n yt = randomvar(nr_samples) # latent observations\n y = datavar(Vector{Float64}, nr_samples) # actual observations\n u = randomvar(nr_samples) # inputs\n \n # set priors\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n z_tmp ~ BIFMHelper(z_prior) where { q = MeanField() }\n \n # update last/previous hidden state\n z_prev = z_tmp\n \n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n\n # specify observation\n yt[i] ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }\n y[i] ~ MvNormalMeanPrecision(yt[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \n # set final value\n z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Probabilistic-inference","page":"RTS vs BIFM Smoothing","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_RTS(data_y, A, B, C, μu, Wu, Wy)\n \n # In this task the inference is unstable and can diverge\n meta = @meta begin \n *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)\n end\n \n result = inference(\n model = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast()),\n meta = meta\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_RTS (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)\n result = inference(\n model = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast())\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_BIFM (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Experiments-for-200-observations","page":"RTS vs BIFM Smoothing","title":"Experiments for 200 observations","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)\nz_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\n\nmz_RTS = mean.(z_RTS)\nmz_BIFM = mean.(z_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:5\n Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\n\nrdata_u = collect(eachrow(data_u))\nmu_RTS = mean.(u_RTS)\nmu_BIFM = mean.(u_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:1\n Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Benchmark","page":"RTS vs BIFM Smoothing","title":"Benchmark","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation\n# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`\nrun_benchmark = false\n\nif run_benchmark\n trials_range = 30\n trials_n = 500\n trials_RTS = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n\n\n @showprogress for k = 1 : trials_range\n\n # generate parameters\n local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);\n \n # generate data|\n local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);\n\n # run inference\n trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n\n end\n\n m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9\n q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9\n m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9\n q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;\n\n p = Plots.plot(ylabel = \"duration [sec]\", xlabel = \"latent state dimension\", title = \"Benchmark\", yscale = :log)\n p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = \"blue\", label = \"mean (RTS)\")\n p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = \"orange\", label = \"mean (BIFM)\")\n Plots.savefig(p, \"../pics/rts_bifm_benchmark.png\")\n p\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"manuals/meta-specification/#user-guide-meta-specification","page":"Meta specification","title":"Meta Specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.","category":"page"},{"location":"manuals/meta-specification/#General-syntax","page":"Meta specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts either regular Julia function or a single begin ... end block:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function MyModelMeta(arg1, arg2)\n Node(y,x) -> MetaObject(arg1, arg2)\nend\n\nmy_meta = @meta begin \n Node(y,x) -> MetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order 5 can be specified as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function ARmodel_meta(num_order)\n AR() -> ARMeta(Univariate, num_order, ARsafe())\nend\n\nmy_meta = ARmodel_meta(5)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"num_order = 5\n\nmy_meta = @meta begin \n AR() -> ARMeta(Multivariate, num_order, ARsafe())\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Both syntax variations provide the same meta specification and there is no preference given to one over the other. ","category":"page"},{"location":"manuals/meta-specification/#Options-specification","page":"Meta specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta [ warn = false ] begin \n ...\nend\n\n@meta [ warn = false ] function MyModelMeta()\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"List of available options:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/meta specification","category":"page"},{"location":"manuals/meta-specification/#Meta-specification","page":"Meta specification","title":"Meta specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"First, let's start with an example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"You can have a list of as many meta specification entries as possible for different nodes:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))\n AR() -> ARMeta(Multivariate, 5, ARsafe())\n MyCustomNode() -> MyCustomMetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model(arguments...)\n ...\nend\n\nmy_meta = @meta begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); meta = my_meta)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Alternatively, it is possible to use meta directly in the automatic inference and rxinference functions that accepts meta keyword argument:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"inferred_result = inference(\n model = my_model(arguments...),\n meta = my_meta,\n ...\n)\n\ninferred_result = rxinference(\n model = my_model(arguments...),\n meta = my_meta,\n ...\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model()\n ...\n\n y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }\n\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the inference and rxinference functions.","category":"page"},{"location":"manuals/meta-specification/#Create-your-own-meta","page":"Meta specification","title":"Create your own meta","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for your custom node\nstruct MyCustomMeta\n arg1 \n arg2 \nend\n\n# apply the new meta structure to your node\n@meta function model_meta(arg1, arg2)\n MyCustomNode() -> MyCustomMeta(arg1,arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"or create different meta structures for a node, e.g. AR node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for the AR node\nstruct MyARMeta\n arg1\n arg2\nend\n\n# apply the new meta structure to the AR node\n@meta function model_meta(arg1, arg2)\n AR() -> MyARMeta(arg1, arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.","category":"page"},{"location":"manuals/meta-specification/#Example","page":"Meta specification","title":"Example","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"beginaligned\n x sim mathrmNormal(25 05)\n y sim mathrmNormal(2*x 20)\nendaligned","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"where y is observable data and x is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"using RxInfer\n\n#create data\ny_data = 4.0 \n\n#make model\n@model function gaussian_model()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\n#do inference\ninference_result = inference(\n model = gaussian_model(),\n data = (y = y_data,)\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean m clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#create your new meta structure for Normal node\nstruct MetaConstrainedMeanNormal{T}\n lower_limit :: T\n upper_limit :: T\nend\n\n#define rules with meta for the Normal node\n@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))\nend\n\n@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#make model\n@model function gaussian_model_with_meta()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\ncustom_meta = @meta begin\n NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)\nend\n\n#do inference\ninference_result = inference(\n model = gaussian_model(),\n data = (y = y_data,),\n meta = custom_meta\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution","page":"Overview","title":"Inference execution","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"Belief Propagation\nVariational Message Passing","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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.","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-static","page":"Overview","title":"Automatic inference specification on static datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer exports the inference function to quickly run and test you model with static datasets. See more information about the inference function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-realtime","page":"Overview","title":"Automatic inference specification on real-time datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer exports the rxinference function to quickly run and test you model with dynamic and potentially real-time datasets. See more information about the rxinference function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-manual-specification","page":"Overview","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"While both inference and rxinference use most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#examples-chance-constrained-active-inference","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, \"Chance-constrained active inference\") and discussion with John Boik.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Plots, Distributions, StatsFuns, RxInfer","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Chance-Constraint-Node-Definition","page":"Chance-Constrained Active Inference","title":"Chance-Constraint Node Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not \"overflow\" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"struct ChanceConstraint end \n\n# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol\n@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Function to compute normalizing constant and central moments of a truncated Gaussian distribution\nfunction truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)\n V = clamp(V, tiny, huge)\n StdG = Distributions.Normal(m, sqrt(V))\n TrG = Distributions.Truncated(StdG, a, b)\n \n Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a) # safe mass for standard Gaussian\n \n if Z < tiny\n # Invalid region; return undefined mean and variance of truncated distribution\n Z = 0.0\n m_tr = 0.0\n V_tr = 0.0\n else\n m_tr = Distributions.mean(TrG)\n V_tr = Distributions.var(TrG)\n end\n \n return (Z, m_tr, V_tr)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@rule ChanceConstraint(:out, Marginalisation) (\n m_out::UnivariateNormalDistributionsFamily, # Require inbound message\n q_lo::PointMass, \n q_hi::PointMass, \n q_epsilon::PointMass, \n q_atol::PointMass) = begin \n\n # Extract parameters\n lo = mean(q_lo)\n hi = mean(q_hi)\n epsilon = mean(q_epsilon)\n atol = mean(q_atol)\n \n (m_bw, V_bw) = mean_var(m_out)\n (xi_bw, W_bw) = (m_bw, 1. /V_bw) # check division by zero\n (m_tilde, V_tilde) = (m_bw, V_bw)\n \n # Compute statistics (and normalizing constant) of q in safe region G\n # Phi_G is called the \"safe mass\" \n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)\n\n xi_fw = xi_bw\n W_fw = W_bw\n if epsilon <= 1.0 - Phi_G # If constraint is active\n # Initialize statistics of uncorrected belief\n m_tilde = m_bw\n V_tilde = V_bw\n for i = 1:100 # Iterate at most this many times\n (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G\n (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G\n\n # Compute moments of non-G region as a mixture of left and right truncations\n Phi_nG = Phi_lG + Phi_rG\n m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG\n V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2\n\n # Compute moments of corrected belief as a mixture of G and non-G regions\n m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG\n V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2\n # Re-compute statistics (and normalizing constant) of corrected belief\n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)\n if (1.0 - Phi_G) < (1.0 + atol)*epsilon\n break # Break the loop if the belief is sufficiently corrected\n end\n end\n \n # Convert moments of corrected belief to canonical form\n W_tilde = inv(V_tilde)\n xi_tilde = W_tilde * m_tilde\n\n # Compute canonical parameters of forward message\n xi_fw = xi_tilde - xi_bw\n W_fw = W_tilde - W_bw\n end\n\n return NormalWeightedMeanPrecision(xi_fw, W_fw)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Definition-of-the-Environment","page":"Chance-Constrained Active Inference","title":"Definition of the Environment","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile\n\nfunction initializeWorld()\n x_0 = 0.0 # Initial elevation\n \n x_t_last = x_0\n function execute(t::Int64, a_t::Float64)\n x_t = x_t_last + a_t + wind(t) # Update elevation\n \n x_t_last = x_t # Reset state\n \n return x_t\n end\n\n x_t = x_0 # Predefine outcome variable\n observe() = x_t # State is fully observed\n\n return (execute, observe)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Generative-Model-for-Regulator","page":"Chance-Constrained Active Inference","title":"Generative Model for Regulator","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@model function regulator_model(; T, lo, hi, epsilon, atol)\n # Fully observed state\n x_t = datavar(Float64)\n\n # Control prior statistics\n m_u = datavar(Float64, T)\n v_u = datavar(Float64, T) \n \n # Random variables\n u = randomvar(T) # Control\n x = randomvar(T) # Elevation\n \n # Loop over horizon\n x_k_last = x_t\n for k = 1:T\n u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior\n x[k] ~ x_k_last + u[k] # Transition model\n x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state\n pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency\n x_k_last = x[k]\n end\n \n return (u, x)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Reactive-Agent-Definition","page":"Chance-Constrained Active Inference","title":"Reactive Agent Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"function initializeAgent()\n # Set control prior statistics\n m_u = zeros(T)\n v_u = lambda^(-1)*ones(T)\n \n function infer(x_t::Float64)\n model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)\n data_t = (m_u = m_u, v_u = v_u, x_t = x_t)\n \n result = inference(\n model = model_t, \n data = data_t,\n iterations = n_its)\n\n # Extract policy from inference results\n pol = mode.(result.posteriors[:u][end])\n\n return pol\n end\n\n pol = zeros(T) # Predefine policy variable\n act() = pol[1]\n\n return (infer, act)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Action-Perception-Cycle","page":"Chance-Constrained Active Inference","title":"Action-Perception Cycle","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Simulation parameters\nN = 160 # Total simulation time\nT = 1 # Lookahead time horizon\nlambda = 1.0 # Control prior precision\nlo = 1.0 # Chance region lower bound\nhi = Inf # Chance region upper bound\nepsilon = 0.01 # Allowed chance violation\natol = 0.01 # Convergence tolerance for chance constraints\nn_its = 10; # Number of inference iterations","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(execute, observe) = initializeWorld() # Let there be a world\n(infer, act) = initializeAgent() # Let there be an agent\n\na = Vector{Float64}(undef, N) # Actions\nx = Vector{Float64}(undef, N) # States\nfor t = 1:N\n a[t] = act()\n execute(t, a[t])\n x[t] = observe()\n infer(x[t])\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Results","page":"Chance-Constrained Active Inference","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Results show that the agent does not allow the wind to push it all the way to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"p1 = plot(1:N, wind.(1:N), color=\"blue\", label=\"Wind\", ylabel=\"Velocity\", lw=2)\nplot!(p1, 1:N, a, color=\"red\", label=\"Control\", lw=2)\np2 = plot(1:N, x, color=\"black\", lw=2, label=\"Agent\", ylabel=\"Elevation\")\nplot(p1, p2, layout=(2,1))","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#examples-gamma-mixture-model","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Load-packages","page":"Gamma Mixture Model","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"using RxInfer, Random, StatsPlots","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# create custom structure for model parameters for simplicity\nstruct GammaMixtureModelParameters\n nmixtures # number of mixtures\n priors_as # tuple of priors for variable a\n priors_bs # tuple of priors for variable b\n prior_s # prior of variable s\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Model-specification","page":"Gamma Mixture Model","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)\n\n # fetch information from struct\n nmixtures = parameters.nmixtures\n priors_as = parameters.priors_as\n priors_bs = parameters.priors_bs\n prior_s = parameters.prior_s\n\n # set prior on global selection variable\n s ~ Dirichlet(probvec(prior_s))\n\n # allocate vectors of random variables\n as = randomvar(nmixtures)\n bs = randomvar(nmixtures)\n\n # set priors on variables of mixtures\n for i in 1:nmixtures\n as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))\n bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))\n end\n\n # introduce random variables for local selection variables and data\n z = randomvar(nobservations)\n y = datavar(Float64, nobservations)\n\n # convert vector to tuples for proper functioning of GammaMixture node\n tas = tuple(as...)\n tbs = tuple(bs...)\n\n # specify local selection variable and data generating process\n for i in 1:nobservations\n z[i] ~ Categorical(s)\n y[i] ~ GammaMixture(z[i], tas, tbs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"constraints = @constraints begin \n\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n\n q(as) = q(as[begin])..q(as[end])\n q(bs) = q(bs[begin])..q(bs[end])\n \n q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Constraints:\n marginals form:\n q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n q(as) = q(as[(begin)..(end)])\n q(bs) = q(bs[(begin)..(end)])\nOptions:\n warn = true","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify seed and number of data points\nrng = MersenneTwister(43)\nn_samples = 2500\n\n# specify parameters of mixture model that generates the data\n# Note that mixture components have exactly the same means\nmixtures = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]\nnmixtures = length(mixtures)\nmixing = rand(rng, nmixtures)\nmixing = mixing ./ sum(mixing)\nmixture = MixtureModel(mixtures, mixing)\n\n# generate data set\ndataset = rand(rng, mixture, n_samples);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify priors of probabilistic model\n# NOTE: As the means of the mixtures \"collide\", we specify informative prior for selector variable\nnmixtures = 2\ngpriors = GammaMixtureModelParameters(\n nmixtures, # number of mixtures\n [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ], # priors on variables a\n [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ], # priors on variables b\n Dirichlet(1e3*mixing) # prior on variable s\n)\n\ngmodel = gamma_mixture_model(length(dataset), gpriors)\ngdata = (y = dataset, )\nginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))\ngreturnvars = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())\n\ngoptions = (\n \n default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently\n)\n\ngresult = inference(\n model = gmodel, \n data = gdata,\n constraints = constraints,\n options = (limit_stack_depth = 100,),\n initmarginals = ginitmarginals,\n returnvars = greturnvars,\n free_energy = true,\n iterations = 250, \n showprogress = true\n);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# extract inferred parameters\n_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])\n_dists = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))\n_mixing = mean(gresult.posteriors[:s])\n\n# create model from inferred parameters\n_mixture = MixtureModel(_dists, _mixing);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# report on outcome of inference\nprintln(\"Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))\")\nprintln(\"Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))\")\nprintln(\"========\")\nprintln(\"Generated mixing: $(mixing)\")\nprintln(\"Inferred mixing: $(_mixing)\")","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Generated means: 0.3333333333333333 and 0.33333333333333337\nInferred means: 0.33821706692775155 and 0.33305593557019114\n========\nGenerated mixing: [0.18923488676601088, 0.8107651132339891]\nInferred mixing: [0.11397705903361303, 0.886022940966387]","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# plot results\np1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np1 = plot!(mixture, label=false, title=\"Generated mixtures\", linewidth=3.0)\n\np2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np2 = plot!(_mixture, label=false, title=\"Inferred mixtures\", linewidth=3.0)\n\n# evaluate the convergence of the algorithm by monitoring the BFE\np3 = plot(gresult.free_energy, label=false, xlabel=\"iterations\", title=\"Bethe FE\")\n\nplot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#examples-gaussian-mixture","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Load-packages","page":"Gaussian Mixture","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Univariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Univariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Consider the data set of length N observed below.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_univariate_data(nr_samples; rng = MersenneTwister(123))\n\n # data generating parameters\n class = [1/3, 2/3]\n mean1, mean2 = -10, 10\n precision = 1.777\n\n # generate data\n z = rand(rng, Categorical(class), nr_samples)\n y = zeros(nr_samples)\n for k in 1:nr_samples\n y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_univariate = generate_univariate_data(100)\nhistogram(data_univariate, bins=50, label=\"data\", normed=true)\nxlims!(minimum(data_univariate), maximum(data_univariate))\nylims!(0, Inf)\nylabel!(\"relative occurrence [%]\")\nxlabel!(\"y\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m w z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(w_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmBeta(s mid alpha_s beta_s) \n p(m_k) = mathcalN(m_k mid mu_k sigma_k^2) p(w_k) = Gamma(w_k mid alpha_k beta_k) \n p(z_n mid s) = mathrmBer(z_n mid s) \n p(y_n mid m w z_n) = prod_k=1^K mathcalNleft(y_n mid m_k w_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions w = w_1 w_2 ldots w_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Here we implement the following model with uninformative values for the hyperparameters as","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function univariate_gaussian_mixture_model(nr_samples)\n \n s ~ Beta(1.0, 1.0)\n \n m1 ~ Normal(mean = -2.0, var = 1e3)\n w1 ~ Gamma(shape = 0.01, rate = 0.01)\n \n m2 ~ Normal(mean = 2.0, var = 1e3)\n w2 ~ Gamma(shape = 0.01, rate = 0.01)\n \n z = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n \n for n in 1:nr_samples\n z[n] ~ Bernoulli(s)\n y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m w mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m w mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(w_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmBeta(s mid hatalpha_s hatbeta_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatsigma^2_k) \n q(w_k) = Gamma (w_k mid hatalpha_k hatbeta_k) \n q(z_n) = mathrmBer(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"results_univariate = inference(\n model = univariate_gaussian_mixture_model(length(data_univariate)), \n constraints = MeanField(),\n data = (y = data_univariate,), \n initmarginals = (\n s = vague(Beta), \n m1 = NormalMeanVariance(-2.0, 1e3), \n m2 = NormalMeanVariance(2.0, 1e3), \n w1 = vague(GammaShapeRate), \n w2 = vague(GammaShapeRate)\n ), \n iterations = 10, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m2, m1, s, w2, w1, z)\n Free Energy: | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.\n277, 135.277, 135.277, 135.277, 135.277]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen as a function of the iterations","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L\"posterior $m_1$\")\nmp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L\"posterior $m_2$\")\nmp = plot!(mp, [ -10 ], seriestype = :hline, label = L\"true $m_1$\")\nmp = plot!(mp, [ 10 ], seriestype = :hline, label = L\"true $m_2$\")\n\nwp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L\"posterior $w_1$\", legend = :bottomright, ylim = (-1, 3))\nwp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L\"posterior $w_2$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_1$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_2$\")\n\nswp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L\"posterior $s$\")\nswp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L\"true $s$\")\n\nfep = plot(results_univariate.free_energy, label = \"Free Energy\", legend = :topright)\n\nplot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))\nxlabel!(\"iteration\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Multivariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Multivariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The above example can also be extended to the multivariate case. Consider the data set below","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))\n\n L = 50.0\n nr_mixtures = 6\n\n probvec = normalize!(ones(nr_mixtures), 1)\n\n switch = Categorical(probvec)\n\n gaussians = map(1:nr_mixtures) do index\n angle = 2π / nr_mixtures * (index - 1)\n basis_v = L * [ 1.0, 0.0 ]\n R = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]\n mean = R * basis_v \n covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))\n return MvNormal(mean, covariance)\n end\n\n z = rand(rng, switch, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n\n for n in 1:nr_samples\n y[n] = rand(rng, gaussians[z[n]])\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_multivariate = generate_multivariate_data(500)\n\nsdim(n) = (a) -> map(d -> d[n], a) # helper function\nscatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)\nxlabel!(L\"y_1\")\nylabel!(L\"y_2\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification-2","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m W z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(W_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmDir(s mid alpha_s) \n p(m_k) = mathcalN(m_k mid mu_k Sigma_k) p(W_k) = mathcalW(W_k mid V_k nu_k) \n p(z_n mid s) = mathrmCat(z_n mid s) \n p(y_n mid m W z_n) = prod_k=1^K mathcalNleft(y_n mid m_k W_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions W = W_1 W_2 ldots W_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)\n \n z = randomvar(nr_samples)\n m = randomvar(nr_mixtures)\n w = randomvar(nr_mixtures)\n y = datavar(Vector{Float64}, nr_samples)\n \n for k in 1:nr_mixtures \n m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])\n w[k] ~ Wishart(3, 1e2*diagm(ones(2)))\n end\n \n s ~ Dirichlet(ones(nr_mixtures))\n \n means = tuple(m...)\n precs = tuple(w...)\n \n for n in 1:nr_samples\n z[n] ~ Categorical(s) \n y[n] ~ NormalMixture(z[n], means, precs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference-2","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m W mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m W mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(W_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmDir(s mid hatalpha_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatSigma_k) \n q(w_k) = mathcalW(W_k mid hatV_k hatnu_k) \n q(z_n) = mathrmCat(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"rng = MersenneTwister(121)\nm = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]\nresults_multivariate = inference(\n model = multivariate_gaussian_mixture_model(\n 6, \n length(data_multivariate), \n m,\n [diagm(1e2 * ones(2)) for k in 1:6]\n ), \n data = (y = data_multivariate,), \n constraints = MeanField(),\n initmarginals = (\n s = vague(Dirichlet, 6), \n m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], \n w = Wishart(3, diagm(1e2 * ones(2)))\n ), \n iterations = 50, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m, w, s, z)\n Free Energy: | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49 … 3894.49, 3894.49, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results-2","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title=\"Data\", xlims=(-75, 75), ylims=(-75, 75))\np_result = plot(xlims = (-75, 75), ylims = (-75, 75), title=\"Inference result\", legend=false, colorbar = false)\nfor (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])\n gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))\n global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title=\"Inference result\", legend=false, levels = 7, colorbar = false)\nend\np_fe = plot(results_multivariate.free_energy, label = \"Free Energy\")\n\nplot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#examples-kalman-filtering-and-smoothing","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We then solve an identification problem which does not have an analytical solution.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Utimately, we show how RxInfer.jl can deal with missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Gaussian-Linear-Dynamical-System","page":"Kalman filtering and smoothing","title":"Gaussian Linear Dynamical System","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"LGSSM can be described with the following equations:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n p(x_ix_i - 1) = mathcalN(x_iA * x_i - 1 mathcalP)\n p(y_ix_i) = mathcalN(y_iB * x_i mathcalQ)\nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"where x_i are hidden states, y_i are noisy observations, A, B are state transition and observational matrices, mathcalP and mathcalQ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(rng, A, B, Q, P)\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(B * x[i], P))\n x_prev = x[i]\n end\n \n return x, y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Seed for reproducibility\nseed = 1234\n\nrng = MersenneTwister(1234)\n\n# We will model 2-dimensional observations with rotation matrix `A`\n# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`\n# are known and fixed for all time-steps\nθ = π / 35\nA = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\nB = diageye(2)\nQ = diageye(2)\nP = 25.0 .* diageye(2)\n\n# Number of observations\nn = 300;","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x, y = generate_data(rng, A, B, Q, P);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\npx = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To create a model we use GraphPPL package and @model macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rotate_ssm(n, x0, A, B, Q, P)\n \n # We create constvar references for better efficiency\n cA = constvar(A)\n cB = constvar(B)\n cQ = constvar(Q)\n cP = constvar(P)\n \n # `x` is a sequence of hidden states\n x = randomvar(n)\n # `y` is a sequence of \"clamped\" observations\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n x_prev = x_prior\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)\n y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)\n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference we also specify prior for out first hidden state:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. \n# inference(..., options = (limit_stack_depth = 500, ))`\nresult = inference(\n model = rotate_ssm(length(y), x0, A, B, Q, P), \n data = (y = y,),\n free_energy = true\n);\n\nxmarginals = result.posteriors[:x]\nlogevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\n\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :teal)\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :violet)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"logevidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"1-element Vector{Float64}:\n -1882.2434870099778","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We may be also interested in performance of our resulting Belief Propagation algorithm:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@benchmark inference(\n model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), \n data = (y = $y,)\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"BenchmarkTools.Trial: 145 samples with 1 evaluation.\n Range (min … max): 25.289 ms … 105.283 ms ┊ GC (min … max): 0.00% … 17.2\n5%\n Time (median): 30.949 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 34.474 ms ± 9.607 ms ┊ GC (mean ± σ): 8.58% ± 12.6\n6%\n\n ▆▅█▁ \n ▃▁▄▇████▇▃▃▁▃▃▃▁▃▃▄▃▄▃▄▃▄▄▃▃▃▃▃▁▁▃▁▁▃▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▃ ▃\n 25.3 ms Histogram: frequency by time 75.6 ms <\n\n Memory estimate: 9.65 MiB, allocs estimate: 223850.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#System-Identification-Problem","page":"Kalman filtering and smoothing","title":"System Identification Problem","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Distributions, StableRNGs, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)\n\n rng = StableRNG(seed)\n\n real_x = Vector{Float64}(undef, n)\n real_w = Vector{Float64}(undef, n)\n real_y = Vector{Float64}(undef, n)\n\n for i in 1:n\n real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))\n real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))\n real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))\n\n x_i_min = real_x[i]\n w_i_min = real_w[i]\n end\n \n return real_x, real_w, real_y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-1:-y-x-w","page":"Kalman filtering and smoothing","title":"Combination 1: y = x + w","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 250\nreal_x, real_w, real_y = generate_data(+, n);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, real_x, label = \"x\")\npl = plot!(pl, real_w, label = \"w\")\n\npr = plot(title = \"Combined y = x + w\")\npr = scatter!(pr, real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x = randomvar(n)\n w = randomvar(n)\n s = randomvar(n)\n y = datavar(Float64, n)\n \n x_i_min = x0\n w_i_min = w0\n \n for i in 1:n\n x[i] ~ Normal(mean = x_i_min, precision = τ_x)\n w[i] ~ Normal(mean = w_i_min, precision = τ_w)\n s[i] ~ f(x[i], w[i])\n y[i] ~ Normal(mean = s[i], precision = τ_y)\n \n x_i_min = x[i]\n w_i_min = w[i]\n end\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin \n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y\n)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The next step is to assign priors, initialise needed messages and marginals and call the inference function:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"m_x_0, τ_x_0 = -20.0, 1.0\nm_w_0, τ_w_0 = 20.0, 1.0\n\n# We set relatively strong priors for random walk noise components\n# and sort of vague prior for the noise of the observations\na_x, b_x = 0.01, 0.01var(real_x)\na_w, b_w = 0.01, 0.01var(real_w)\na_y, b_y = 1.0, 1.0\n\n# We set relatively strong priors for messages\nxinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))\nwinit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))\n\nimessages = (x = xinit, w = winit)\nimarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))\n\nresult = inference(\n model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),\n data = (y = real_y,), \n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = imessages, \n initmarginals = imarginals, \n iterations = 50\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's examine our inference results:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"τ_x_marginals = result.posteriors[:τ_x]\nτ_w_marginals = result.posteriors[:τ_w]\nτ_y_marginals = result.posteriors[:τ_y]\n\nsmarginals = result.posteriors[:s]\nxmarginals = result.posteriors[:x]\nwmarginals = result.posteriors[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-2:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Combination 2: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Smoothed version of `min` without zero-ed derivatives\nfunction smooth_min(x, y) \n if x < y\n return x + 1e-4 * y\n else\n return y + 1e-4 * x\n end\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"smooth_min (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_meta = @meta begin \n # In this example we are going to use a simple `Linearization` method\n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 200\nmin_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, min_real_x, label = \"x\")\npl = plot!(pl, min_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, min_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_m_x_0, min_τ_x_0 = -1.0, 1.0\nmin_m_w_0, min_τ_w_0 = 1.0, 1.0\n\nmin_a_x, min_b_x = 1.0, 1.0\nmin_a_w, min_b_w = 1.0, 1.0\nmin_a_y, min_b_y = 1.0, 1.0\n\nmin_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))\nmin_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))\n\nmin_result = inference(\n model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),\n data = (y = min_real_y,), \n meta = min_meta,\n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = min_imessages, \n initmarginals = min_imarginals, \n iterations = 100\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_τ_x_marginals = min_result.posteriors[:τ_x]\nmin_τ_w_marginals = min_result.posteriors[:τ_w]\nmin_τ_y_marginals = min_result.posteriors[:τ_y]\n\nmin_smarginals = min_result.posteriors[:s]\nmin_xmarginals = min_result.posteriors[:x]\nmin_wmarginals = min_result.posteriors[:w]\n\npx1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, min_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, min_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, min_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks). ","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Online-(filtering)-identification:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Online (filtering) identification: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rx_identification(f)\n \n # We are going to continuosly update our priors\n # based on new posteriors\n m_x_0 = datavar(Float64) \n τ_x_0 = datavar(Float64)\n m_w_0 = datavar(Float64) \n τ_w_0 = datavar(Float64)\n a_x = datavar(Float64) \n b_x = datavar(Float64)\n a_y = datavar(Float64) \n b_y = datavar(Float64)\n a_w = datavar(Float64) \n b_w = datavar(Float64)\n s = randomvar()\n y = datavar(Float64)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x ~ Normal(mean = x0, precision = τ_x)\n w ~ Normal(mean = w0, precision = τ_w)\n\n s ~ f(x, w)\n y ~ Normal(mean = s, precision = τ_y)\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We impose structured mean-field assumption for this model as well:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_constraints = @constraints begin \n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ\n_y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"autoupdates = @autoupdates begin \n m_x_0, τ_x_0 = mean_precision(q(x))\n m_w_0, τ_w_0 = mean_precision(q(w))\n a_x = shape(q(τ_x)) \n b_x = rate(q(τ_x))\n a_y = shape(q(τ_y))\n b_y = rate(q(τ_y))\n a_w = shape(q(τ_w)) \n b_w = rate(q(τ_w))\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_\nx = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_\ny)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_meta = @meta begin \n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step is to generate our dataset and to run the actual inference procedure! For that we use the rxinference function, which has a similar API as the inference function:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 300\nrx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, rx_real_x, label = \"x\")\npl = plot!(pl, rx_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"engine = rxinference(\n model = rx_identification(smooth_min),\n constraints = rx_constraints,\n data = (y = rx_real_y,),\n autoupdates = autoupdates,\n meta = rx_meta,\n returnvars = (:x, :w, :τ_x, :τ_w, :τ_y, :s),\n keephistory = 1000,\n historyvars = KeepLast(),\n initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),\n iterations = 10,\n free_energy = true, \n free_energy_diagnostics = nothing,\n autostart = true,\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInferenceEngine:\n Posteriors stream | enabled for (w, s, τ_x, τ_w, τ_y, x)\n Free Energy stream | enabled\n Posteriors history | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)\n Free Energy history | available\n Enabled events | [ ]","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_smarginals = engine.history[:s]\nrx_xmarginals = engine.history[:x]\nrx_wmarginals = engine.history[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, rx_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = \"Estimated X\")\n\npx1 = plot!(px1, rx_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = \"Estimated W\")\n\npx2 = scatter!(px2, rx_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the \"disabled\" state, does not infer anything and simply increases its variance (which is expected for the random walk).","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Handling-Missing-Data","page":"Kalman filtering and smoothing","title":"Handling Missing Data","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let us assume that the following model generates the data","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n x_t sim mathcalNleft(x_t-1 10right) \n y_t sim mathcalNleft(x_t P right) \nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation haty_t in mathrmR we sometimes will catch missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function smoothing(n, x0)\n \n P ~ Gamma(shape = 0.001, scale = 0.001)\n x_prior ~ Normal(mean = mean(x0), var = var(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ Normal(mean = x_prev, precision = 1.0)\n y[i] ~ Normal(mean = x[i], precision = P)\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We need to manually extend the set of rules to support ::Missing values","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"P = 1.0\nn = 250\n\nreal_signal = map(e -> sin(0.05 * e), collect(1:n))\nnoisy_data = real_signal + rand(Normal(0.0, sqrt(P)), n);\nmissing_indices = 100:125\nmissing_data = similar(noisy_data, Union{Float64, Missing}, )\n\ncopyto!(missing_data, noisy_data)\n\nfor index in missing_indices\n missing_data[index] = missing\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0_prior = NormalMeanVariance(0.0, 1000.0)\n\nresult = inference(\n model = smoothing(n, x0_prior), \n data = (y = missing_data,), \n constraints = constraints,\n initmarginals = (P = Gamma(0.001, 0.001), ),\n returnvars = (x = KeepLast(),),\n iterations = 20\n);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"plot(real_signal, label = \"Noisy signal\", legend = :bottomright)\nscatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = \"Missing region\")\nplot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = \"Estimated hidden state\")","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#examples-conjugate-computational-variational-message-passing-(cvi)","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#An-example:-nonlinear-dynamical-system","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"An example: nonlinear dynamical system","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position z_t at time t. Instead they have access to the observed squared distance y_t between the object and some reference point s. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# data generating process\nnr_observations = 50\nreference_point = 53\nhidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)\nmeasurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot hidden location and reference frame\np1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label=\"hidden location\")\nhline!([reference_point], linewidth=3, label=\"reference point\")\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot measurements\np2 = scatter(1:nr_observations, measurements, linewidth=3, label=\"measurements\")\nxlabel!(\"time [sec]\"), ylabel!(\"squared distance [cm2]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"beginaligned\n p(tau) = Gamma(tau mid alpha_tau beta_tau)\n p(gamma) = Gamma(gamma mid alpha_gamma beta_gamma)\n p(z_t mid z_t - 1 tau) = mathcalN(z_t mid z_t - 1 + 1 tau^-1)\n p(y_t mid z_t gamma) = mathcalN(y_t mid (z_t - s)^2 gamma^-1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"where the researchers put priors on the process and measurement noise parameters, tau and gamma, respectively. They do this, because they do not know the accuracy of their devices.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"function compute_squared_distance(z)\n (z - reference_point)^2\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function measurement_model(nr_observations)\n\n # allocate random variables and observations\n z = randomvar(nr_observations)\n y = datavar(Float64, nr_observations)\n\n # set priors on precision parameters\n τ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n γ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n \n # specify estimate of initial location\n z[1] ~ Normal(mean = 0, precision = τ)\n y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)\n\n # loop over observations\n for t in 2:nr_observations\n\n # specify state transition model\n z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)\n\n # specify non-linear observation model\n y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)\n \n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)\n compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function model_meta(...)\n f() -> CVI(args...)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"See ?CVI for more information about the args....","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In the above example, we will assume the following posterior factorization:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function measurement_constraints()\n q(z, τ, γ) = q(z)q(τ)q(γ)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function posterior_constraints() begin\n q(z, γ) = q(z)q(γ) # CVI\n q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"results = inference(\n model = measurement_model(nr_observations),\n data = (y = measurements,),\n iterations = 5,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = measurement_constraints(),\n meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),\n initmessages = (z = NormalMeanVariance(0, 5),),\n initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),\n)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Inference results:\n Posteriors | available for (z)\n Free Energy: | Real[1241.91, 429.933, 376.869, 365.774, 362.879]","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot estimates for location\np1 = plot(collect(1:nr_observations), hidden_location, label = \"hidden location\", legend=:topleft, linewidth=3, color = :red)\nplot!(map(mean, results.posteriors[:z]), label = \"estimated location (±2σ)\", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot Bethe free energy\np2 = plot(results.free_energy, linewidth=3, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size = (1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Requirements","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Requirements","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"There are several main requirements for the CVI procedure to satisfy:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The out interface of the non-linearity must be independently factorized with respect to other variables in the model.\nThe messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function model(...)\n ...\n y ~ f(x1, x2, ..., xN)\n ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity\n ... \nend\n\n@constraints function constraints_meta() begin\n q(y, z1, ..., zn) = q(y)q(z1,...,zM)\n ...\nend;\n\n@meta function model_meta(...)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer))\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note that not all exponential family distributions are implemented.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Extensions","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Extensions","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Using-a-custom-optimizer","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Using a custom optimizer","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"CVI only supports Optimisers optimizers out of the box.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Below an explanation on how to extend to it to a custom optimizer.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Suppose we have CustomDescent structure which we want to use inside CVI for optimization.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"ReactiveMP.cvi_update! incapsulates the gradient step:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"opt is used to select your optimizer structure\nλ is the current value\n∇ is a gradient value computed inside CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"struct CustomDescent \n learning_rate::Float64\nend\n\n# Must return an optimizer and its initial state\nfunction ReactiveMP.cvi_setup(opt::CustomDescent, q)\n return (opt, nothing)\nend\n\n# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)\nfunction ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)\n opt, _ = opt_and_state\n λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))\n copyto!(new_λ, λ̂)\n return opt_and_state, new_λ\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's try to apply it to a model: beginaligned p(x) = mathcalN(0 1)\n p(y_imid x) = mathcalN(y_i mid x^2 1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's generate some synthetic data for the model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# generate data\ny = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)\nhistogram(y)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Again we can create the corresponding model as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# specify non-linearity\nf(x) = x ^ 2\n\n# specify model\n@model function normal_square_model(nr_observations)\n\n # allocate observations\n y = datavar(Float64, nr_observations)\n\n # describe prior on latent state\n x ~ NormalMeanPrecision(0, 100)\n\n # transform latent state\n mean ~ f(x)\n\n # observation model\n y .~ NormalMeanVariance(mean, 1)\n\nend\n\n# specify meta\n@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"normal_square_meta (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"res = inference(\n model = normal_square_model(1000),\n data = (y = y,),\n iterations = 10,\n free_energy = true,\n initmessages = (x = NormalMeanVariance(0, 100),),\n meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))\n)\n\nmean(res.posteriors[:x][end])","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"-18.998075156688632","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working! ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note: x^2 can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"page"},{"location":"library/functional-forms/#lib-forms","page":"Built-in functional form constraints","title":"Built-in Functional Forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.","category":"page"},{"location":"library/functional-forms/#lib-forms-custom-constraints","page":"Built-in functional form constraints","title":"Custom functional forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.","category":"page"},{"location":"library/functional-forms/#lib-forms-unspecified-constraint","page":"Built-in functional form constraints","title":"UnspecifiedFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: Nothing # This is the default setting\nend","category":"page"},{"location":"library/functional-forms/#lib-forms-point-mass-constraint","page":"Built-in functional form constraints","title":"PointMassFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. ","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.PointMassFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.PointMassFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.PointMassFormConstraint","text":"PointMassFormConstraint\n\nOne of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.\n\nKeyword arguments\n\noptimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer\nstarting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point\nboundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries\n\nCustom optimizer callback interface\n\n# This is an example of the `custom_optimizer` interface\nfunction custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # should return argmin of the -logpdf(distribution)\nend\n\nCustom starting point callback interface\n\n# This is an example of the `custom_starting_point` interface\nfunction custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # built-in optimizer expects an array, even for a univariate distribution\n return [ 0.0 ] \nend\n\nCustom boundaries callback interface\n\n# This is an example of the `custom_boundaries` interface\nfunction custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # returns a tuple of `lower` and `upper` boundaries\n return (-Inf, Inf)\nend\n\nTraits\n\nis_point_mass_form_constraint = true\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = PointMass (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-sample-list-constraint","page":"Built-in functional form constraints","title":"SampleListFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000)\n # or \n q(y) :: SampleList(1000, LeftProposal())\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.SampleListFormConstraint\nRxInfer.AutoProposal\nRxInfer.LeftProposal\nRxInfer.RightProposal","category":"page"},{"location":"library/functional-forms/#RxInfer.SampleListFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.SampleListFormConstraint","text":"SampleListFormConstraint(rng, strategy, method)\n\nOne of the form constraint objects. Approximates DistProduct with a SampleList object. \n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = SampleList (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.AutoProposal","page":"Built-in functional form constraints","title":"RxInfer.AutoProposal","text":"Tries to determine the proposal distribution in the SampleList approximation automatically.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.LeftProposal","page":"Built-in functional form constraints","title":"RxInfer.LeftProposal","text":"Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.RightProposal","page":"Built-in functional form constraints","title":"RxInfer.RightProposal","text":"Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-fixed-marginal-constraint","page":"Built-in functional form constraints","title":"FixedMarginalFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints function block_updates(x_posterior = nothing) \n # `nothing` returns the computed posterior marginal\n q(x) :: Marginal(x_posterior)\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.FixedMarginalFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.FixedMarginalFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.FixedMarginalFormConstraint","text":"FixedMarginalFormConstraint\n\nOne of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.\n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = Marginal (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-composite-constraint","page":"Built-in functional form constraints","title":"CompositeFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass()\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/#examples-hierarchical-gaussian-filter","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"","category":"section"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Simple HGF model can be defined as:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n x^(j)_k sim mathcalN(x^(j)_k - 1 f_k(x^(j - 1)_k)) \n y_k sim mathcalN(x^(j)_k tau_k)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"where j is an index of layer in hierarchy, k is a time step and f_k is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with f_k = exp(kappa x + omega) variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n z_k sim mathcalN(z_k - 1 mathcaltau_z) \n x_k sim mathcalN(x_k - 1 exp(kappa z_k + omega)) \n y_k sim mathcalN(x_k mathcaltau_y)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"For simplicity we will consider tau_z, tau_y, kappa and omega known and fixed, but there are no principled limitations to make them random variables too.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"using RxInfer, BenchmarkTools, Random, Plots","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function generate_data(rng, k, w, zv, yv)\n z_prev = 0.0\n x_prev = 0.0\n\n z = Vector{Float64}(undef, n)\n v = Vector{Float64}(undef, n)\n x = Vector{Float64}(undef, n)\n y = Vector{Float64}(undef, n)\n\n for i in 1:n\n z[i] = rand(rng, Normal(z_prev, sqrt(zv)))\n v[i] = exp(k * z[i] + w)\n x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))\n y[i] = rand(rng, Normal(x[i], sqrt(yv)))\n\n z_prev = z[i]\n x_prev = x[i]\n end \n \n return z, x, y\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Seed for reproducibility\nseed = 42\n\nrng = MersenneTwister(seed)\n\n# Parameters of HGF process\nreal_k = 1.0\nreal_w = 0.0\nz_variance = abs2(0.2)\ny_variance = abs2(0.1)\n\n# Number of observations\nn = 300\n\nz, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n scatter!(px, 1:n, y, label = \"y_i\", color = :red, ms = 2, alpha = 0.2)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To create a model we use the @model macro:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# We create a single-time step of corresponding state-space process to\n# perform online learning (filtering)\n@model function hgf(real_k, real_w, z_variance, y_variance)\n \n # Priors from previous time step for `z`\n zt_min_mean = datavar(Float64)\n zt_min_var = datavar(Float64)\n \n # Priors from previous time step for `x`\n xt_min_mean = datavar(Float64)\n xt_min_var = datavar(Float64)\n\n zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)\n xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)\n\n # Higher layer is modelled as a random walk \n zt ~ NormalMeanVariance(zt_min, z_variance)\n \n # Lower layer is modelled with `GCV` node\n gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)\n \n # Noisy observations \n y = datavar(Float64)\n y ~ NormalMeanVariance(xt, y_variance)\n \n return gcvnode\nend\n\n@constraints function hgfconstraints() \n q(xt, zt, xt_min) = q(xt, xt_min)q(zt)\nend\n\n@meta function hgfmeta()\n # Lets use 31 approximation points in the Gauss Hermite cubature approximation method\n GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) \nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"hgfmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function run_inference(data, real_k, real_w, z_variance, y_variance)\n\n autoupdates = @autoupdates begin\n zt_min_mean, zt_min_var = mean_var(q(zt))\n xt_min_mean, xt_min_var = mean_var(q(xt))\n end\n\n return rxinference(\n model = hgf(real_k, real_w, z_variance, y_variance),\n constraints = hgfconstraints(),\n meta = hgfmeta(),\n data = (y = data, ),\n autoupdates = autoupdates,\n keephistory = length(data),\n historyvars = (\n xt = KeepLast(),\n zt = KeepLast()\n ),\n initmarginals = (\n zt = NormalMeanVariance(0.0, 5.0),\n xt = NormalMeanVariance(0.0, 5.0),\n ), \n iterations = 5,\n free_energy = true,\n autostart = true,\n callbacks = (\n after_model_creation = (model, returnval) -> begin \n gcvnode = returnval\n setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))\n end,\n )\n )\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"run_inference (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"result = run_inference(y, real_k, real_w, z_variance, y_variance);\n\nmz = result.history[:zt];\nmx = result.history[:xt];","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = \"estimated z_i\", color = :teal)\n \n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = \"estimated x_i\", color = :violet)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"plot(result.free_energy_history, label = \"Bethe Free Energy\")","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see BetheFreeEnergy converges nicely to a stable point.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"At final, lets check the overall performance of our resulting Variational Message Passing algorithm:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"BenchmarkTools.Trial: 64 samples with 1 evaluation.\n Range (min … max): 59.119 ms … 128.093 ms ┊ GC (min … max): 0.00% … 0.00\n%\n Time (median): 77.214 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 79.066 ms ± 13.156 ms ┊ GC (mean ± σ): 6.22% ± 6.90\n%\n\n ▂ ▂▂ ▂▂ ▅█▅ ▂▂▂▂ \n ▅█▅▅▅▅█▅▅██▁▁███▅███▁▅▅▅▅▁▅████▁▅▁▁▁▁▁▅▅▁▁▁▁▅▅▁▁▁▁▁▁▁▁▁▁▁▁▁▅ ▁\n 59.1 ms Histogram: frequency by time 119 ms <\n\n Memory estimate: 18.64 MiB, allocs estimate: 447879.","category":"page"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = RxInfer","category":"page"},{"location":"#RxInfer","page":"Home","title":"RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"Julia package for automatic Bayesian inference on a factor graph with reactive message passing.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.","category":"page"},{"location":"#Package-Features","page":"Home","title":"Package Features","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"User friendly syntax for specification of probabilistic models.\nAutomatic generation of message passing algorithms including\nBelief propagation\nVariational message passing\nExpectation maximization\nSupport for hybrid models combining discrete and continuous latent variables.\nSupport for hybrid distinct message passing inference algorithm under a unified paradigm.\nFactorisation and functional form constraints specification.\nEvaluation of Bethe free energy as a model performance measure.\nSchedule-free reactive message passing API.\nHigh performance.\nScalability for large models with millions of parameters and observations.\nInference procedure is differentiable.\nEasy to extend with custom nodes and message update rules.","category":"page"},{"location":"#Why-RxInfer","page":"Home","title":"Why RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a \"variational Free Energy\" cost function. For large models, manual derivation of these gradients might not be feasible, while automated \"black-box\" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.","category":"page"},{"location":"","page":"Home","title":"Home","text":"RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different \"what-if\" scenarios and enables very efficient inference in specific cases.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.","category":"page"},{"location":"#How-to-get-started?","page":"Home","title":"How to get started?","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"manuals/background.md\",\n \"manuals/comparison.md\",\n \"manuals/getting-started.md\",\n \"manuals/model-specification.md\",\n \"manuals/constraints-specification.md\",\n \"manuals/meta-specification.md\",\n \"manuals/inference-execution.md\",\n \"manuals/custom-node.md\",\n \"manuals/debugging.md\",\n \"manuals/delta-node.md\",\n \"examples/overview.md\",\n \"library/exported-methods.md\",\n \"library/functional-forms.md\",\n \"contributing/overview.md\",\n \"contributing/new-example.md\"\n]\nDepth = 2","category":"page"},{"location":"#References","page":"Home","title":"References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RxInfer: A Julia package for reactive real-time Bayesian inference - a reference paper for the RxInfer.jl framwork.\nVariational Message Passing and Local Constraint Manipulation in Factor Graphs - describes theoretical aspects of the underlying Bayesian inference method.\nReactive Message Passing for Scalable Bayesian Inference - describes implementation aspects of the Bayesian inference engine and performs benchmarks and accuracy comparison on various models.\nA Julia package for reactive variational Bayesian inference - a reference paper for the ReactiveMP.jl package, the underlying inference engine.\nThe Factor Graph Approach to Model-Based Signal Processing - an introduction to message passing and FFGs.","category":"page"},{"location":"#Ecosystem","page":"Home","title":"Ecosystem","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ReactiveMP.jl - core package for efficient and scalable for reactive message passing \nGraphPPL.jl - package for model and constraints specification\nRocket.jl - reactive programming tools","category":"page"},{"location":"#Index","page":"Home","title":"Index","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"examples/advanced_examples/overview/#examples-advanced_examples-overview","page":"Overview","title":"Advanced examples","text":"","category":"section"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Advanced examples contain more complex inference problems.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.\nAdvanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.\nAssessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.\nChance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.\nConjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.\nGlobal Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.\nSolve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.\nInfinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.\nNonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors","category":"page"},{"location":"manuals/constraints-specification/#user-guide-constraints-specification","page":"Constraints specification","title":"Constraints Specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"using RxInfer","category":"page"},{"location":"manuals/constraints-specification/#General-syntax","page":"Constraints specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"\n# `functional` style\n@constraints function create_my_constraints(arg1, arg2)\n ...\nend\n\n# `block` style\nmyconstraints = @constraints begin \n ...\nend\n","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In the first case it returns a function that return constraints upon calling, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(mean_field)\n q(x) :: PointMass\n\n if mean_field\n q(x, y) = q(x)q(y)\n end\nend\n\nmyconstraints = make_constraints(true)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"and in the second case it evaluates automatically and returns constraints object directly.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints begin \n q(x) :: PointMass\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/#Options-specification","page":"Constraints specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints [ warn = false ] begin \n ...\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"List of available options:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/constraints specification","category":"page"},{"location":"manuals/constraints-specification/#Marginal-and-messages-form-constraints","page":"Constraints specification","title":"Marginal and messages form constraints","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"The following constraint:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"mathrmapproximate q(x) = fracoverrightarrowmu(x)overleftarrowmu(x)int overrightarrowmu(x)overleftarrowmu(x) mathrmdxmathrmasPointMass","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\n μ(x) :: SampleList(1000)\n # it is possible to assign different form constraints on the same variable \n # both for the marginal and for the messages \nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro understands \"stacked\" form constraints. For example the following form constraint","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\nNot all combinations of \"stacked\" form constraints are compatible between each other.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.","category":"page"},{"location":"manuals/constraints-specification/#Factorisation-constraints-on-posterior-distribution-q()","page":"Constraints specification","title":"Factorisation constraints on posterior distribution q()","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"For example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) = q(x[begin])..q(x[end])\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables x_i.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\n@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"It is possible to write more complex factorisation constraints, for example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(k)\n q(x) = q(x[begin:k])q(x[k+1:end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end]. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model function my_model(arguments...)\n ...\nend\n\nconstraints = @constraints begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); constraints = constraints)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Alternatively, it is possible to use constraints directly in the automatic inference and rxinference functions that accepts constraints keyword argument. ","category":"page"},{"location":"contributing/overview/#contributing-overview","page":"Overview","title":"Contributing","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.","category":"page"},{"location":"contributing/overview/#Reporting-bugs","page":"Overview","title":"Reporting bugs","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.","category":"page"},{"location":"contributing/overview/#Nightly-Julia-status","page":"Overview","title":"Nightly Julia status","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"(Image: PkgEval)","category":"page"},{"location":"contributing/overview/#Suggesting-features","page":"Overview","title":"Suggesting features","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome new feature proposals. However, before submitting a feature request, consider a few things:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.\nIf you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.","category":"page"},{"location":"contributing/overview/#Contributing-code","page":"Overview","title":"Contributing code","text":"","category":"section"},{"location":"contributing/overview/#Installing-RxInfer","page":"Overview","title":"Installing RxInfer","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] dev git@github.com:your_username/RxInfer.jl.git","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nIt is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.","category":"page"},{"location":"contributing/overview/#Core-dependencies","page":"Overview","title":"Core dependencies","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.","category":"page"},{"location":"contributing/overview/#Committing-code","page":"Overview","title":"Committing code","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well. ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.","category":"page"},{"location":"contributing/overview/#Style-conventions","page":"Overview","title":"Style conventions","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Use 4 spaces for indentation\nType names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..\nFunction names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..\nVariable names and function arguments use snake_case\nThe name of a method that modifies its argument(s) must end in !","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nRxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.","category":"page"},{"location":"contributing/overview/#Unit-tests","page":"Overview","title":"Unit tests","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The tests can be evaluated by running following command in the Julia REPL:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] test RxInfer","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"In addition tests can be evaluated by running following command in the RxInfer root directory:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make test","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make devtest to use local dev-ed versions of the core packages.","category":"page"},{"location":"contributing/overview/#Makefile","page":"Overview","title":"Makefile","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl uses Makefile for most common operations:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make help: Shows help snippet\nmake test: Run tests, supports extra arguments\nmake test test_args=\"distributions:normal_mean_variance\" would run tests only from distributions/test_normal_mean_variance.jl\nmake test test_args=\"distributions:normal_mean_variance models:lgssm\" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl\nmake test dev=true would run tests while using dev-ed versions of core packages\nmake devtest: Alias for the make test dev=true ...\nmake docs: Compile documentation\nmake devdocs: Same as make docs, but uses dev-ed versions of core packages\nmake examples: Run all examples and put them in the docs/ folder if successfull \nmake devexamples: Same as make examples, but uses dev-ed versions of core packages\nmake lint: Check codestyle\nmake format: Check and fix codestyle ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nCore packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.","category":"page"},{"location":"contributing/new-release/#contributing-new-release","page":"Publishing a new release","title":"Publishing a new release","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.","category":"page"},{"location":"contributing/new-release/#Start-the-release-process","page":"Publishing a new release","title":"Start the release process","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"In order to start the release process a person with the associated permissions should: ","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Open a commit page on GitHub\nWrite the @JuliaRegistrator register comment for the commit:","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"(Image: Release comment)","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#examples-solve-gp-regression-by-sde","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"In this notebook, we solve a GP regression problem by using \"Stochastic Differential Equation\" (SDE). This method is well described in the dissertation \"Stochastic differential equation methods for spatio-temporal Gaussian process regression.\" by Arno Solin and \"Sequential Inference for Latent Temporal Gaussian Process Models\" by Jouni Hartikainen. The idea of the method is as follows.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Suppose a function f(x) follows a zero-mean Gaussian Process beginaligned f(x) sim mathcalGP(0 k(xx)) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"When the dimensionality of x is 1, we can consider f(x) as a stochastic process over time, i.e. f(t). For a certain classses of covariance functions, f(t) is a solution to an m-th order linear stochastic differential equation (SDE) beginaligned a_0 f(t) + a_1 fracd f(t)dt + dots + a_m fracd^m f(t)dt^m = w(t) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where w(t) is a zero-mean white noise process with spectral density Q_c. If we define a vector-valued function mathbff(t) = (f(t) ddt f(t)dots d^m-1dt^m-1f(t)), then we can rewrite the above SDE under the companion form","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracd mathbff(t)dt = mathbfF mathbff(t) + mathbfL w(t) quad (1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfF and mathbfL are defined based on the choice of covariance functions. From (1), we have the following state-space model: beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) quad(2a) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) quad(2b) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfA_k = exp(mathbfFDelta t_k), with Delta t_k = t_k+1 - t_k, is called the discrete-time state transition matrix, and mathbfQ_k the process noise covariance matrix. For the computation of mathbfQ_k, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state f_0 sim mathcalN(mathbf0 mathbfP_0). For stationary covariance function, the SDE has a stationary state f_infty sim mathcalN(mathbf0 mathbfP_infty), where mathbfP_infty is the solution to beginaligned fracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0 quad (mathrmLyapunov equation) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"With this stationary condition, the process noise covariance mathbfQ_k is computed as follows beginaligned mathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"For one-dimensional problem the SDE representation of the GP is defined by the matrices mathbfF mathbfL mathbfQ_c mathbfP_0 and mathbfH. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"using RxInfer, Random, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Create-state-space-model-for-GP-regression","page":"Solve GP regression by SDE","title":"Create state space model for GP regression","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Here we create a state-space model beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) \nendaligned where y_k is the noisy observation of the function f at time t_k, and sigma^2_noise is the noise variance and assumed to be known.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"@model function gp_regression(n, P∞, A, Q, H, σ²_noise)\n f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)\n f = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n \n f_prev = f_0\n\n for i=1:n\n f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])\n y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)\n f_prev = f[i]\n end\n return f, y\nend","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Generate-data","page":"Solve GP regression by SDE","title":"Generate data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Random.seed!(10)\nn = 100\nσ²_noise = 0.04;\nt = collect(range(-2, 2, length=n)); #timeline\nf_true = sinc.(t); # true process\nf_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process\n\npos = sort(randperm(75)[1:2:75]); \nt_obser = t[pos]; # time where we observe data\n\ny_data = Array{Union{Float64,Missing}}(missing, n)\nfor i in pos \n y_data[i] = f_noisy[i]\nend\n\nθ = [1., 1.]; # store [l, σ²]\nΔt = [t[1]]; # time difference\nappend!(Δt, t[2:end] - t[1:end-1]);","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Let's-visualize-our-data","page":"Solve GP regression by SDE","title":"Let's visualize our data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"plot(t, f_true, label=\"True process f(t)\")\nscatter!(t_obser, y_data[pos], label = \"Noisy observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-3/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-3/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"The Matern is a stationary covariance function and defined as follows beginaligned k(tau) = sigma^2 frac2^1-nuGamma(nu) left(fracsqrt2nutaul right)^nu K_nuleft(fracsqrt2nutaul right) endaligned where beginaligned sigma^2 textthe magnitude scale hyperparameter\nl textthe characteristic length-scale\nnu textthe smoothness hyperparameter\nK_nu() textthe modified Bessel function of the second kind endaligned When we say the Matern-3/2, we mean nu=32. The matrices for the state space model are computed as follows beginaligned mathbfF = beginpmatrix 0 1\n-lambda^2 -2lambda endpmatrix quad quad mathbfL = beginpmatrix 0 1 endpmatrix quad quad mathbfP_infty = beginpmatrix sigma^2 0 0 lambda^2sigma^2 endpmatrix quad quad mathbfH = beginpmatrix 1 0 endpmatrix quad quad Q_c = 4lambda^3sigma^2 endaligned where lambda = fracsqrt3l From these matrices we can define mathbfA_k and mathbfQ_k.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(3)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 1.];\nH = [1., 0.];\nF = [0. 1.; -λ^2 -2λ]\nP∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_32 = inference(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-5/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-5/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfF = beginpmatrix\n0 1 0\n0 0 1 \n-lambda^3 -3lambda^2 -3lambda\nendpmatrix quad quad mathbfL = beginpmatrix\n0 0 1\nendpmatrix quad quad mathbfH = beginpmatrix\n1 0 0\nendpmatrix quad quad Q_c = frac163 sigma^2 lambda^5 \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where lambda = sqrt5 l. To find mathbfP_infty, we solve the Lyapunov equation","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"of which the solution is","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nvec(mathbfP_infty) = (mathbfI otimes mathbfF + mathbfFotimesmathbfI)^-1 vec(-mathbfLQ_cmathbfL^T)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where vec() is the vectorization operator and otimes denotes the Kronecker product. Now we can find mathbfA_k and mathbfQ_k ","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfA_k = exp(mathbfFDelta t_k) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(5)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 0., 1.];\nH = [1., 0., 0.];\nF = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]\nQc = 16/3 * θ[2] * λ^5;\n\nI = diageye(3) ; \nvec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); \nP∞ = reshape(vec_P,3,3);\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_52 = inference(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Result","page":"Solve GP regression by SDE","title":"Result","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"slicedim(dim) = (a) -> map(e -> e[dim], a)\n\nplot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M32\", title = \"Matern-3/2\", legend =false, lw = 2)\nplot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M52\",legend = :bottomleft, title = \"GPRegression by SSM\", lw = 2)\nplot!(t, f_true,label=\"true process\", lw = 2)\nscatter!(t_obser, f_noisy[pos], label=\"Observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"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. ","category":"page"},{"location":"contributing/new-documentation/#guide-docs-contributing","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.\nIdentify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.\nFork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.\nMake Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.\nSubmit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.\nReview and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.\nMerging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.","category":"page"},{"location":"contributing/new-documentation/#Use-[LiveServer.jl](https://github.com/tlienart/LiveServer.jl)","page":"Contributing to the documentation","title":"Use LiveServer.jl","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"To use LiveServer.jl, simply follow these steps[1]","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"[1]: Make sure to install the LiveServer and Documenter in your current working environment.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Make sure to import the required packages ","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> using LiveServer, Documenter","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"After importing the required packages, you can start the live server with the following command:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> servedocs()","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#examples-bayesian-linear-regression-tutorial","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The first part uses a regular Bayesian Linear Regression on a simple application of fuel consumption for a car with synthetic data.\nThe second part is an adaptation of a tutorial from NumPyro and uses Hierarchical Bayesian linear regression on the OSIC pulmonary fibrosis progression dataset from Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-1.-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 1. Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-known-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He records the speed and fuel consumption for the urban road which is the xdata and ydata.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results = inference(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b)\n Free Energy: | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184\n.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821\n, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a\\mid y)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0,Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b)\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b\\mid y)\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"a = results.posteriors[:a]\nb = results.posteriors[:b]\n\nprintln(\"Real a: \", 0.5, \" | Estimated a: \", mean_var(a), \" | Error: \", abs(mean(a) - 0.5))\nprintln(\"Real b: \", 25.0, \" | Estimated b: \", mean_var(b), \" | Error: \", abs(mean(b) - 25.0))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err\nor: 0.001490188462705988\nReal b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error\n: 0.18735789804394898","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-unknown-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with unknown noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. beginaligned p(y_n mid a b s) = mathcalN(y_n mid ax_n + b s)\np(s) = mathcalIG(smidalpha theta)\np(a) = mathcalN(a mid m_a v_a) \np(b) = mathcalN(b mid m_b v_b) endaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_unknown_noise(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n s ~ InverseGamma(1.0, 1.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = s)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)\n\nscatter(x_data_un, y_data_un, title = \"Dateset with unknown noise (mountain road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_unknown_noise = inference(\n model = linear_regression_unknown_noise(length(x_data_un)), \n data = (y = y_data_un, x = x_data_un), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast(), s = KeepLast()), \n iterations = 20,\n constraints = MeanField(),\n initmarginals = (s = vague(InverseGamma), ),\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, s)\n Free Energy: | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125\n.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56\n, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"plot(results_unknown_noise.free_energy, title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Below he visualizes the obtained posterior distributions for parameters:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(a)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(b)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25.0 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(b)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25.0 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L\"Prior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(s)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 200 ], label=L\"True $s$\", c = 3)\npsb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L\"Posterior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(s)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 200 ], label=L\"True $s$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$s$\", ylabel=L\"$p(s)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He sees that in the presence of more noise the inference result is more uncertain about the actual values for a and b parameters.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John samples a and b and plot many possible regression lines on the same plot:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"as = rand(results_unknown_noise.posteriors[:a], 100)\nbs = rand(results_unknown_noise.posteriors[:b], 100)\np = scatter(x_data_un, y_data_un, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)\nend\n\nplot(p, size = (900, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"From this plot John can see that many lines do fit the data well and there is no definite \"best\" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Multivariate-linear-regression","page":"Bayesian Linear Regression Tutorial","title":"Multivariate linear regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_multivariate(dim, nr_samples)\n a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))\n b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))\n W ~ InverseWishart(dim + 2, 100 * diageye(dim))\n\n # Here is a small trick to make the example work\n # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`\n x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n z = randomvar(nr_samples)\n\n z .~ x .* a .+ b\n y .~ MvNormal(mean = z, covariance = W)\n\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"After received all the measurement records, he plots the measurements and performance index:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dim_mv = 6\nnr_samples_mv = 50\nrng_mv = StableRNG(42)\na_mv = randn(rng_mv, dim_mv)\nb_mv = 10 * randn(rng_mv, dim_mv)\nv_mv = 100 * rand(rng_mv, dim_mv)\n\nx_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft)\n\nplt = palette(:tab10)\n\ndata_set_label = [\"\"]\n\nfor k in 1:dim_mv\n global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\nxlabel!(L\"$x$\")\nylabel!(L\"$y$\")\np","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Before this data can be used to perform inference, John needs to change its format slightly.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)\ny_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_mv = inference(\n model = linear_regression_multivariate(dim_mv, nr_samples_mv),\n data = (y = y_data_mv_processed, x = x_data_mv_processed),\n initmarginals = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),\n initmessages = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),\n returnvars = (a = KeepLast(), b = KeepLast(), W = KeepLast()),\n free_energy = true,\n iterations = 50,\n constraints = MeanField()\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, W)\n Free Energy: | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7\n22, 712.341, 700.865, 690.782, 682.505 … 664.434, 664.434, 664.434, 664.4\n34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft, xlabel=L\"$x$\", ylabel=L\"$y$\")\n\n# how many lines to plot\nr = 50\n\ni_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))\ni_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))\n\nplt = palette(:tab10)\n\nfor k in 1:dim_mv\n x_mv_k = x_data_mv[k]\n y_mv_k = y_data_mv[k]\n\n for i in 1:r\n global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])\n end\n\n global p = scatter!(p, x_mv_k, y_mv_k, label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\n\n# truncate the init step\nf = plot(results_mv.free_energy[2:end], title =\"Bethe free energy convergence\", label = nothing, xlabel = \"Iteration\", ylabel = \"Bethe free energy [nats]\") \n\nplot(p, f, size = (1000, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_a_mv = results_mv.posteriors[:a]\n\nps_a = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $a_{%$k}$\", xlabel=L\"$a_{%$k}$\", ylabel=L\"$p(a_{%$k})$\", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])\n\n local m_a_mv_k = mean(i_a_mv)[k]\n local v_a_mv_k = std(i_a_mv)[k, k]\n \n _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(a_{%$k})$\", c=2,)\n _p = vline!(_p, [ a_mv[k] ], label=L\"True $a_{%$k}$\", c = 3)\n \n push!(ps_a, _p)\nend\n\nplot(ps_a...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_b_mv = results_mv.posteriors[:b]\n\nps_b = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $b_{%$k}$\", xlabel=L\"$b_{%$k}$\", ylabel=L\"$p(b_{%$k})$\", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])\n local m_b_mv_k = mean(i_b_mv)[k]\n local v_b_mv_k = std(i_b_mv)[k, k]\n\n _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(b_{%$k})$\", c=2,)\n _p = vline!(_p, [ b_mv[k] ], label=L\"Real $b_{%$k}$\", c = 3)\n \n push!(ps_b, _p)\nend\n\nplot(ps_b...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L\"True $s_d$\")\nscatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L\"$\\mathrm{E}[s_d] \\pm \\sigma$\")\nplot!(; xlabel=L\"Dimension $d$\", ylabel=\"Variance\", title=\"Estimated variance of the noise\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-2.-Hierarchical-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 2. Hierarchical Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using NumPyro. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# https://www.machinelearningplus.com/linear-regression-in-julia/\n# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Understanding-the-Task","page":"Bayesian Linear Regression Tutorial","title":"Understanding the Task","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's explore the data and delve deeper into the problem involved.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dataset = CSV.read(\"../data/hbr/osic_pulmonary_fibrosis.csv\", DataFrame);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"describe(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"7×7 DataFrame\n Row │ variable mean min median max \n ⋯\n │ Symbol Union… Any Union… Any \n ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ Patient ID00007637202177411956430 ID004266\n372 ⋯\n 2 │ Weeks 31.8618 -5 28.0 133\n 3 │ FVC 2690.48 827 2641.0 6399\n 4 │ Percent 77.6727 28.8776 75.6769 153.145\n 5 │ Age 67.1885 49 68.0 88 \n ⋯\n 6 │ Sex Female Male\n 7 │ SmokingStatus Currently smokes Never sm\noke\n 3 columns om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"first(dataset, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5×7 DataFrame\n Row │ Patient Weeks FVC Percent Age Sex Sm\noki ⋯\n │ String31 Int64 Int64 Float64 Int64 String7 St\nrin ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ ID00007637202177411956430 -4 2315 58.2536 79 Male Ex\n-sm ⋯\n 2 │ ID00007637202177411956430 5 2214 55.7121 79 Male Ex\n-sm\n 3 │ ID00007637202177411956430 7 2061 51.8621 79 Male Ex\n-sm\n 4 │ ID00007637202177411956430 9 2144 53.9507 79 Male Ex\n-sm\n 5 │ ID00007637202177411956430 11 2069 52.0634 79 Male Ex\n-sm ⋯\n 1 column om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart(dataset, patient_id; line_kws = true)\n info = patientinfo(dataset, patient_id)\n x = info[!, \"Weeks\"]\n y = info[!, \"FVC\"]\n\n p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)\n p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = \"Weeks\", ylabel = \"FVC\")\n \n if line_kws\n # Use the `GLM.jl` package to estimate linear regression\n linearFormulae = @formula(FVC ~ Weeks)\n linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))\n linearPredicted = predict(linearRegressor)\n p = plot!(p, x, linearPredicted, color = :red, lw = 3)\n end\n\n return p\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart(dataset, \"ID00007637202177411956430\")\np2 = patientchart(dataset, \"ID00009637202177434476278\")\np3 = patientchart(dataset, \"ID00010637202177584971671\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modelling:-Bayesian-Hierarchical-Linear-Regression-with-Partial-Pooling","page":"Bayesian Linear Regression Tutorial","title":"Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the \"pooled model.\" On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the \"unpooled model,\" where each patient has completely separate regression lines.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In this analysis, we will adopt a middle ground approach known as \"Partial pooling.\" Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Mathematically, the model is described by the following equations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n mu_alpha sim mathcalN(mathrmmean = 00 mathrmvariance = 2500000) \n sigma_alpha sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mu_beta sim mathcalN(mathrmmean = 00 mathrmvariance = 90) \n sigma_beta sim mathcalGamma(mathrmshape = 175 mathrmscale = 136) \n alpha_i sim mathcalN(mathrmmean = mu_alpha mathrmprecision = sigma_alpha) \n beta sim mathcalN(mathrmmean = mu_beta mathrmprecision = sigma_beta) \n sigma sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mathrmFVC_ij sim mathcalN(mathrmmean = alpha_i + t beta_i mathrmprecision = sigma)\n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Implementing this model in RxInfer is pretty straightforward:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled(patient_codes, weeks)\n μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β ~ Normal(mean = 0.0, var = 9.0) # Prior for the mean of β (slope)\n σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)\n σ_β ~ Gamma(shape = 1.75, scale = 1.36) # Prior for the precision of β (slope)\n\n n_codes = length(patient_codes) # Total number of data points\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution\n β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the standard deviation of the error term\n \n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes) # Observed FVC measurements\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@constraints function partially_pooled_constraints()\n # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent\n q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)\n # Assume that `μ_α`, `σ_α`, `α` are jointly independent\n q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)\n # Assume that `μ_β`, `σ_β`, `β` are jointly independent\n q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)\n # Assume that `FVC_est`, `σ` are jointly independent\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inference-in-the-model","page":"Bayesian Linear Regression Tutorial","title":"Inference in the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patient_ids = dataset[!, \"Patient\"] # get the column of all patients\npatient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));\npatient_code_column = map(patient -> patient_code_encoder[patient], patient_ids)\n\ndataset[!, :PatientCode] = patient_code_column\n\nfirst(patient_code_encoder, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5-element Vector{Pair{InlineStrings.String31, Int64}}:\n \"ID00197637202246865691526\" => 85\n \"ID00388637202301028491611\" => 160\n \"ID00341637202287410878488\" => 142\n \"ID00020637202178344345685\" => 9\n \"ID00305637202281772703145\" => 127","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_inference(dataset)\n\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n\n results = inference(\n model = partially_pooled(patient_codes, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n σ = vague(Gamma),\n σ_α = vague(Gamma),\n σ_β = vague(Gamma),\n ),\n returnvars = KeepLast(),\n iterations = 100\n )\n \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference_results = partially_pooled_inference(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Checking-the-model","page":"Bayesian Linear Regression Tutorial","title":"Checking the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspecting-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspecting the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)\n local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Looks like our model learned personalized alphas and betas for each patient!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Visualizing-FVC-decline-curves-for-some-patients","page":"Bayesian Linear Regression Tutorial","title":"Visualizing FVC decline curves for some patients","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)\n info = patientinfo(dataset, patient_id)\n patient_code_id = encoder[patient_id]\n\n patient_α = results.posteriors[:α][patient_code_id]\n patient_β = results.posteriors[:β][patient_code_id]\n \n predict_weeks = range(-12, 134)\n\n predicted = map(predict_weeks) do week\n pm = mean(patient_α) + mean(patient_β) * week\n pv = var(patient_α) + var(patient_β) * week ^ 2\n return pm, sqrt(pv)\n end\n \n p = patientchart(dataset, patient_id; kwargs...)\n \n return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart_bayesian (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\")\np2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\")\np3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The results match our expectations perfectly! Let's highlight the observations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.\nThe model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.\nAdditionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Computing-the-modified-Laplace-Log-Likelihood-and-RMSE","page":"Bayesian Linear Regression Tutorial","title":"Computing the modified Laplace Log Likelihood and RMSE","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n sigma_mathrmclipped = max(sigma 70) \n delta = min(vert mathrmFVC_mathrmtrue - mathrmFVC_mathrmpredvert 1000) \n mathrmmetric = -fracsqrt2deltasigma_mathrmclipped - mathrmln(sqrt2sigma_mathrmclipped) \n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function FVC_predict(results)\n return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s\n return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"FVC_predict (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function compute_rmse(results, dataset)\n FVC_predicted = FVC_predict(results)\n return mean((dataset[!, \"FVC\"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)\nend\n\nfunction compute_laplace_log_likelihood(results, dataset)\n FVC_predicted = FVC_predict(results)\n sigma_c = std.(FVC_predicted)\n sigma_c[sigma_c .< 70] .= 70\n delta = abs.(mean.(FVC_predicted) .- dataset[!, \"FVC\"])\n delta[delta .> 1000] .= 1000\n return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"compute_laplace_log_likelihood (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.0313266260767\nLaplace Log Likelihood: -6.15689374755478","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Add-layer-to-model-hierarchy:-Smoking-Status","page":"Bayesian Linear Regression Tutorial","title":"Add layer to model hierarchy: Smoking Status","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We can enhance the model by incorporating the column \"SmokingStatus\" as a pooling level, where model parameters will be partially pooled within the groups \"Never smoked,\" \"Ex-smoker,\" and \"Currently smokes.\" To achieve this, we need to:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Encode the \"SmokingStatus\" column. Map the patient encoding to the corresponding \"SmokingStatus\" encodings. Refine and retrain the model with the additional hierarchical structure.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"combine(groupby(dataset, \"SmokingStatus\"), nrow)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"3×2 DataFrame\n Row │ SmokingStatus nrow\n │ String31 Int64\n─────┼─────────────────────────\n 1 │ Ex-smoker 1038\n 2 │ Never smoked 429\n 3 │ Currently smokes 82","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, \"SmokingStatus\"]))))\nsmoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id\n smoking_status = first(unique(patientinfo(dataset, patient_id)[!, \"SmokingStatus\"]))\n return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]\nend)\n\nsmoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)\n μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)\n σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n σ_β_global ~ Gamma(shape = 1.75, scale = 1.36) # Corresponds to half-normal with scale 3.0\n\n n_codes = length(patient_codes) # Total number of data points\n n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern\n μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern\n \n for i in 1:n_smoking_statuses\n μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)\n μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)\n end\n \n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)\n β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n\n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes)\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\n \nend\n\n@constraints function partially_pooled_with_smooking_constraints()\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)\n q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)\n q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)\n q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smooking_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n \n return inference(\n model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_with_smooking_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n σ = Gamma(1.75, 45.54),\n σ_α_global = Gamma(1.75, 45.54),\n σ_β_global = Gamma(1.75, 1.36),\n ),\n returnvars = KeepLast(),\n iterations = 100,\n )\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspect-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspect the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)\n local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)\n local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])\n local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α_global)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β_global)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n local p5 = plot(title = \"q(μ_α_smoking_status)...\", legend = false)\n local p6 = plot(title = \"q(μ_β_smoking_status)...\", legend = false)\n \n foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) \n foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)\n \n plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Interpret-smoking-status-model-parameters","page":"Bayesian Linear Regression Tutorial","title":"Interpret smoking status model parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Dict{InlineStrings.String31, Int64} with 3 entries:\n \"Currently smokes\" => 3\n \"Ex-smoker\" => 1\n \"Never smoked\" => 2","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]\n\nprintln(\"Trend for\")\nforeach(pairs(smoking_id_mapping)) do (key, id)\n println(\" $key: $(mean(posteriors_μ_β_smoking_status[id]))\")\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Trend for\n Currently smokes: 1.815745767102511\n Ex-smoker: -4.565164617653452\n Never smoked: -4.446729680169412","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Let's look at these curves for individual patients to help interpret these model results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Never smoked\np1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\") \n# Ex-smoker\np2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\") \n# Currently smokes\np3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\") \n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Review-patients-that-currently-smoke","page":"Bayesian Linear Regression Tutorial","title":"Review patients that currently smoke","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"When plotting each patient with the smoking status \"Currently smokes,\" we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Depending on the purpose of the model, we can proceed in different ways:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.\nHowever, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the \"Currently smokes\" group's parameters closer to the global parameters, or even consider merging the group with \"Ex-smokers.\" Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"let \n local plots = []\n\n for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==(\"Currently smokes\"), dataset)[!, \"Patient\"]))\n push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))\n end\n\n plot(plots..., size = (1200, 1200))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modified-Laplace-Log-Likelihood-and-RMSE-for-model-with-Smoking-Status-Level","page":"Bayesian Linear Regression Tutorial","title":"Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We calculate the metrics for the updated model and compare to the original model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.7845980866074\nLaplace Log Likelihood: -6.165346437287479","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#References","page":"Bayesian Linear Regression Tutorial","title":"References","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#examples-probit-model-(ep)","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable x_t with the discrete variable y_t. The model is defined as:","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"beginaligned\n u = 01 \n x_0 sim mathcalN(0 100) \n x_t sim mathcalN(x_t-1+ u 001) \n y_t sim mathrmBer(Phi(x_t))\nendaligned","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Import-packages","page":"Probit Model (EP)","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"using RxInfer, StableRNGs, Random, Plots\nusing StatsFuns: normcdf","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Data-generation","page":"Probit Model (EP)","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n \n # hyper parameters\n u = 0.1\n\n # allocate space for data\n data_x = zeros(nr_samples + 1)\n data_y = zeros(nr_samples)\n \n # initialize data\n data_x[1] = -2\n \n # generate data\n for k = 2:nr_samples + 1\n \n # calculate new x\n data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)\n \n # calculate y\n data_y[k-1] = normcdf(data_x[k]) > rand(rng)\n \n end\n \n # return data\n return data_x, data_y\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"n = 40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"data_x, data_y = generate_data(n);","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"p = plot(xlabel = \"t\", ylabel = \"x, y\")\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\")","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Model-specification","page":"Probit Model (EP)","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"@model function probit_model(nr_samples::Int64)\n \n # allocate space for variables\n x = randomvar(nr_samples + 1)\n y = datavar(Float64, nr_samples)\n \n # specify uninformative prior\n x[1] ~ Normal(mean = 0.0, precision = 0.01)\n \n # create model \n for k = 2:nr_samples + 1\n x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)\n y[k - 1] ~ Probit(x[k]) where {\n # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge\n # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations\n pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) \n }\n end\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Inference","page":"Probit Model (EP)","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"result = inference(\n model = probit_model(length(data_y)), \n data = (y = data_y, ), \n iterations = 5, \n returnvars = (x = KeepLast(),),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"Inference results:\n Posteriors | available for (x)\n Free Energy: | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Results","page":"Probit Model (EP)","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"mx = result.posteriors[:x]\n\np = plot(xlabel = \"t\", ylabel = \"x, y\", legend = :bottomright)\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\", lw = 2)\np = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label=\"x (inferred mean)\")\n\nf = plot(xlabel = \"t\", ylabel = \"BFE\")\nf = plot!(result.free_energy, label = \"Bethe Free Energy\")\n\nplot(p, f, size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#examples-advanced-tutorial","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This tutorial is also available in the documentation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#General-model-specification-syntax","page":"Advanced Tutorial","title":"General model specification syntax","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We use the @model macro from the RxInfer.jl package to create a probabilistic model p(s y) and we also specify extra constraints on the variational family of distributions mathcalQ, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `@model` macro accepts a regular Julia function\n@model function test_model1(s_mean, s_precision)\n \n # We use the `randomvar` function to create \n # a random variable in our model\n s = randomvar()\n \n # the `tilde` operator creates a functional dependency\n # between variables in our model and can be read as \n # `sampled from` or `is modeled by`\n s ~ Normal(mean = s_mean, precision = s_precision)\n \n # We use the `datavar` function to create \n # observed data variables in our models\n # We also need to specify the type of our data \n # In this example it is `Float64`\n y = datavar(Float64)\n \n y ~ Normal(mean = s, precision = 1.0)\n \n # It is possible to return something from the model specification (including variables and nodes)\n return \"Hello world\"\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"modelgenerator = test_model1(0.0, 1.0)\n\nmodel, returnval = create_model(modelgenerator)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(FactorGraphModel(), \"Hello world\")","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(): returns an array of factor nodes in a corresponding factor graph\ngetrandom(): returns an array of random variables in the model\ngetdata(): returns an array of data inputs in the model\ngetconstant(): returns an array of constant values in the model","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(model)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"FactorNodesCollection(nodes: 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getrandom(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :s","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getdata(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :y","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getconstant(model) .|> getconst","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 1.0","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model2(n)\n \n if n <= 1\n error(\"`n` argument must be greater than one.\")\n end\n \n # `randomvar(n)` creates a dense sequence of \n # random variables\n s = randomvar(n)\n \n # `datavar(Float64, n)` creates a dense sequence of \n # observed data variables of type `Float64`\n y = datavar(Float64, n)\n \n s[1] ~ Normal(mean = 0.0, precision = 0.1)\n y[1] ~ Normal(mean = s[1], precision = 1.0)\n \n for i in 2:n\n s[i] ~ Normal(mean = s[i - 1], precision = 1.0)\n y[i] ~ Normal(mean = s[i], precision = 1.0)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, _ = create_model(test_model2(10));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of factor nodes in generated Factor Graph\ngetnodes(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"20","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of random variables\ngetrandom(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of data inputs\ngetdata(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of constant values\ngetconstant(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"21","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use complex expressions inside the functional dependency expressions","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# s = randomvar() here is optional\n# `~` creates random variables automatically\ns ~ NormalMeanPrecision(0.0, 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example model which will throw an error:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function error_model1()\n s = 1.0\n s ~ NormalMeanPrecision(0.0, 1.0)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Creates constant reference in a model with a prespecified value\nc = constvar(0.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)\n \n s = randomvar(n)\n \n y = datavar(Vector{Float64}, n)\n \n # Here we create constant references\n # for constant matrices in our model \n # to make inference more memory efficient\n cA = constvar(A)\n cP = constvar(P)\n cQ = constvar(Q)\n \n s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)\n y[1] ~ MvNormal(mean = s[1], covariance = cQ)\n \n for i in 2:n\n s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)\n y[i] ~ MvNormal(mean = s[i], covariance = cQ)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n\n # In this example `ynode` refers to the corresponding \n # `GaussianMeanVariance` node created in the factor graph\n ynode, y ~ GaussianMeanVariance(0.0, 1.0)\n \n return ynode, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Probabilistic-inference-in-RxInfer.jl","page":"Advanced Tutorial","title":"Probabilistic inference in RxInfer.jl","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Observables","page":"Advanced Tutorial","title":"Observables","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Observables are lazy push-based collections and they deliver their values over time.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Timer that emits a new value every second and has an initial one second delay \nobservable = timer(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerObservable(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"actor = (value) -> println(value)\nsubscription1 = subscribe!(observable, actor)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We always need to unsubscribe from some observables\nunsubscribe!(subscription1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We can modify our observables\nmodified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Int64, MapProxy(Int64))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscription2 = subscribe!(modified, (value) -> println(value))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(subscription2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n \n # We assume that the outcome of each coin flip \n # is modeled by a Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during the inference step\n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can call the inference function to run inference in such model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"p = 0.75 # Bias of a coin\n\ndataset = float.(rand(Bernoulli(p), 500));\n\nresult = inference(\n model = coin_toss_model(length(dataset)),\n data = (y = dataset, )\n)\n\nprintln(\"Inferred bias: \", mean_var(result.posteriors[:θ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inferred bias: (0.7387033398821218, 0.0003784719912335691)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can see that the inferred bias is quite close to the actual value we used in the dataset generation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getmarginal(x): for a single random variable x\ngetmarginals(xs): for a dense sequence of random variables sx","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = create_model(coin_toss_model(length(dataset)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# As soon as we have a new value for the marginal posterior over the `θ` variable\n# we simply print the first two statistics of it\nθ_subscription = subscribe!(getmarginal(θ), (marginal) -> println(\"New update: mean(θ) = \", mean(marginal), \", std(θ) = \", std(marginal)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To pass data to our model we use update! function","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"New update: mean(θ) = 0.7387033398821218, std(θ) = 0.01945435661320027","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It is necessary to always unsubscribe from running observables\nunsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them\n# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing\nupdate!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `keep` actor simply keeps all incoming updates in an internal storage, ordered\nθvalues = keep(Marginal)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"KeepActor{Marginal}(Marginal[])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `getmarginal` always emits last cached value as its first value\nsubscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=376.0, β=133.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"2-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=376.0, β=133.0))\n Marginal(Beta{Float64}(α=376.0, β=133.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `buffer` actor keeps very last incoming update in an internal storage and can also store \n# an array of updates for a sequence of random variables\nθbuffer = buffer(Marginal, 1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=376.0, β=133.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=376.0, β=133.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Reactive-Online-Inference","page":"Advanced Tutorial","title":"Reactive Online Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function online_coin_toss_model()\n \n # We create datavars for the prior \n # over `θ` variable\n θ_a = datavar(Float64)\n θ_b = datavar(Float64)\n \n θ ~ Beta(θ_a, θ_b)\n \n y = datavar(Float64)\n y ~ Bernoulli(θ)\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"autoupdates = @autoupdates begin \n θ_a, θ_b = params(q(θ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(θ_a,θ_b = params(q(θ)),)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"rxresult = rxinference(\n model = online_coin_toss_model(),\n data = (y = dataset, ),\n autoupdates = autoupdates,\n historyvars = (θ = KeepLast(), ),\n keephistory = length(dataset),\n initmarginals = (\n θ = vague(Beta),\n ),\n autostart = true\n);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"animation = @animate for i in 1:length(dataset)\n plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = \"Online coin bias inference\", label = \"Inferred bias\", legend = :bottomright)\n hline!([ p ], label = \"Real bias\", size = (600, 200))\nend\n\ngif(animation, \"../pics/online-coin-bias-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Variational-inference","page":"Advanced Tutorial","title":"Variational inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions q in mathcalQ. Often this involves assuming some factorization over q. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_a for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"There are several options to specify the mean-field factorisation constraint. ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use local structured factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-constraints-macro","page":"Advanced Tutorial","title":"RxInfer.jl constraints macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints6 = @constraints begin\n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: where blocks have higher priority over constraints specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Inference","page":"Advanced Tutorial","title":"Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To run inference in this model we again need to create a synthetic dataset:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#inference-function","page":"Advanced Tutorial","title":"inference function","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Use ?inference to quickly check the documentation for the inference function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"result = inference(\n model = test_model6(length(dataset)),\n data = (y = dataset, ),\n constraints = constraints6, \n initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),\n returnvars = (μ = KeepLast(), τ = KeepLast()),\n iterations = 10,\n free_energy = true,\n showprogress = true\n)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inference results:\n Posteriors | available for (μ, τ)\n Free Energy: | Real[14763.3, 3275.76, 651.834, 609.391, 609.391, 609.\n391, 609.391, 609.391, 609.391, 609.391]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(result.posteriors[:μ]), \", std = \", std(result.posteriors[:μ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -3.000724646986326, std = 0.013966417335757148","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(result.posteriors[:τ]), \", std = \", std(result.posteriors[:τ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 5.126596331700441, std = 0.22903943279021433","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Manual-inference","page":"Advanced Tutorial","title":"Manual inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.006731961208428e-9, w=\n0.010000001002000566))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.534269275882096, w=9.\n185855437107634))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9886.339565217606, w=329\n4.6542755992728))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15375.00197071403, w=512\n3.763022641175))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.525455265057, w=51\n26.603492503708))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533966426894, w=51\n26.606328866963))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974921042, w=51\n26.606331697606))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974929553, w=51\n26.606331700403))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974929553, w=51\n26.606331700403))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15383.533974929553, w=51\n26.606331700403))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(GammaShapeRate{Float64}(a=501.0, b=5.000000000046004e14))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=54599.81398289297))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=152.064975181232))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.77988864532342))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72571215810044))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565808994209))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803598197))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803592796))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803592796))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=97.72565803592796))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(last(μ_values)), \", std = \", std(last(μ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -3.000724646986326, std = 0.013966417335757148","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(last(τ_values)), \", std = \", std(last(τ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 5.126596331700441, std = 0.22903943279021433","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Form-constraints","page":"Advanced Tutorial","title":"Form constraints","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints7 = @constraints begin \n q(μ) :: PointMass\n \n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_i for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar()\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, PointMass(1.0))\n\nμ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(PointMass{Float64}(-3.000724652827777))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(GammaShapeRate{Float64}(a=501.0, b=97.62812762929559))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { \n prod_constraint = ProdGeneric(),\n form_constraint = SampleListFormConstraint() \n}","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: @constraints macro specifies required prod_constraint automatically.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Free-Energy","page":"Advanced Tutorial","title":"Free Energy","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_observable = score(model, Float64, BetheFreeEnergy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Float64, ErrorIfProxy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_subscription = subscribe!(bfe_observable, (fe) -> println(\"Current BFE value: \", fe));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Reset the model with vague marginals\nsetmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Current BFE value: 621.8890579210147\nCurrent BFE value: 609.3910191436262\nCurrent BFE value: 609.3910188947075\nCurrent BFE value: 609.3910188947066\nCurrent BFE value: 609.3910188947084\nCurrent BFE value: 609.391018894707\nCurrent BFE value: 609.3910188947075\nCurrent BFE value: 609.3910188947066\nCurrent BFE value: 609.3910188947066\nCurrent BFE value: 609.3910188947066","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It always necessary to unsubscribe and release computer resources\nunsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Meta-data-specification","page":"Advanced Tutorial","title":"Meta data specification","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of \n# the autoregressive process and its order. In addition it specifies that the message computation rules should\n# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations\n# by cost of possible numerical instabilities during an inference procedure\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }\n...\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` \n# method with `21` sigma points for approximation of non-lineariety between hierarchy layers\nxt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-@meta-macro","page":"Advanced Tutorial","title":"RxInfer.jl @meta macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@meta begin \n AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Meta specification:\n AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Creating-custom-nodes-and-message-computation-rules","page":"Advanced Tutorial","title":"Creating custom nodes and message computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-nodes","page":"Advanced Tutorial","title":"Custom nodes","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification\n@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]\n\n# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error\nstruct NormalMeanVariance end \n\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# It is also possible to use function objects as a node functional form\nfunction dot end\n\n# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them \n# out = dot(x, a)\n@node typeof(dot) Deterministic [ out, x, a ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"After that it is possible to use the newly created node during model specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n ...\n y ~ dot(x, a)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-messages-computation-rules","page":"Advanced Tutorial","title":"Custom messages computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu_z = mu_x + mu_y\nV_z = V_x + V_y\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To specify this in RxInfer.jl we use the @node and @rule macros:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@node typeof(+) Deterministic [ z, x, y ]\n\n@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin\n x_mean, x_var = mean_var(m_x)\n y_mean, y_var = mean_var(m_y)\n return NormalMeanVariance(x_mean + y_mean, x_var + y_var)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(z) = int q(z x y) mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu(z) = int f(x y z)mu(x)mu(y)mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nnu(z) = exp int log f(x y z)q(x)q(y)mathrmdxmathrmdy \nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @rule macro supports both cases with special prefixes during rule specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"m_ prefix corresponds to the incoming message on a specific edge\nq_ prefix corresponds to the posterior marginal of a specific edge","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Sum-Product rule with m_ messages used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin \n m_out_mean, m_out_cov = mean_cov(m_out)\n return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Variational rule with Mean-Field assumption with q_ posteriors used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin \n return NormalMeanPrecision(mean(q_out), mean(q_τ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin\n m, V = mean_cov(q_out_μ)\n θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))\n α = convert(typeof(θ), 1.5)\n return Gamma(α, θ)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference backend expects arguments in `@rule` macro to be in the same order\n@node NormalMeanPrecision Stochastic [ out, μ, τ ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Any rule always has access to the meta information with hidden the meta::Any variable:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin \n ...\n println(meta)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to dispatch on a specific type of a meta object:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"or","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Customizing-messages-computational-pipeline","page":"Advanced Tutorial","title":"Customizing messages computational pipeline","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Logs all outbound messages\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }\n# Initialise messages to be vague\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }\n# In principle, it is possible to approximate outbound messages with Laplace Approximation\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let us return to the coin toss model, but this time we want to print flowing messages:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model_log(n)\n\n y = datavar(Float64, n)\n\n θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage(\"θ\") }\n\n for i in 1:n\n y[i] ~ Bernoulli(θ) where { pipeline = LoggerPipelineStage(\"y[$i]\") }\n end\n \n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"θ_subscription = subscribe!(getmarginal(θ), (value) -> println(\"New posterior marginal for θ: \", value));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[θ][Beta][out]: VariationalMessage()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"coinflips = float.(rand(Bernoulli(0.5), 5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, coinflips)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[y[1]][Bernoulli][p]: VariationalMessage()\n[y[2]][Bernoulli][p]: VariationalMessage()\n[y[3]][Bernoulli][p]: VariationalMessage()\n[y[4]][Bernoulli][p]: VariationalMessage()\n[y[5]][Bernoulli][p]: VariationalMessage()\nNew posterior marginal for θ: Marginal(Beta{Float64}(α=4.0, β=10.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference is lazy and does not send messages if no one is listening for them\nupdate!(y, coinflips)","category":"page"},{"location":"manuals/custom-node/#create-node","page":"Defining a custom node and rules","title":"Creating your own custom nodes","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To create a custom node in RxInfer, 4 steps are required:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Create your custom node in RxInfer using the @node macro.\nDefine the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.\nSpecify computations for marginal distributions of the relevant variables with the @marginalrule macro.\nImplement the computation of the Free Energy in a node with the @average_energy macro.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!","category":"page"},{"location":"manuals/custom-node/#Problem-statement","page":"Defining a custom node and rules","title":"Problem statement","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin K=20 times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment x_kin01 using the Bernoulli distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_k mid pi) = mathrmBer(x_k mid pi) = pi^x_k (1-pi)^1-x_k","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"where pi in01 denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of pi which she models using the Beta distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(pi) = mathrmBeta(pi mid 4 8)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With this prior belief, the total probabilistic model that she has for this experiment is given by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_1K pi) = p(pi) prod_k=1^K p(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of pi, p(pi mid x_1K), denoting how pi is distributed after we have seen the data.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-1:-Creating-the-custom-node","page":"Defining a custom node and rules","title":"Step 1: Creating the custom node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nIn this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"First things first, let's import RxInfer:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using RxInfer","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The name of the node. (::Type)\nWhether the node is Deterministic or Stochastic.\nThe interfaces of the node and any potential aliases. (::Vector)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"# struct for Bernoulli distribution with success probability π\nstruct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution\n π :: T\n new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError(\"π must be between 0 and 1\"))\t\nend\n\n# for simplicity, let's also specify the mean of the distribution\nDistributions.mean(d::MyBernoulli) = d.π\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nYou can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of pi, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Concluding, we can create the MyBernoulli factor node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@node MyBernoulli Stochastic [out, (π, aliases = [p])]","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Cool! Step 1 is done, we have created a custom node.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-2:-Defining-rules-for-our-node","page":"Defining a custom node and rules","title":"Step 2: Defining rules for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as p(pimid x_1K), we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.","category":"page"},{"location":"manuals/custom-node/#Sum-product-message-passing-update-rules","page":"Defining a custom node and rules","title":"Sum-product message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In sum-product message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecmu(x) propto int mathrmBer(xmid pi) vecmu(pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(pi) propto sum_x in 01 mathrmBer(xmid pi) overleftarrowmu(x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain pi = fracalphaalpha + beta, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for \"the incoming message on interface π\". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(π) propto mathrmBeta(1 + x 2 - x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which gives us the following update rule:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin\n p = mean(m_out)\n Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/#Variational-message-passing-update-rules","page":"Defining a custom node and rules","title":"Variational message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecnu(x) propto exp int q(pi) ln mathrmBer(xmid pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrownu(pi) propto exp sum_x in 01 q(x) ln mathrmBer(xmid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"#rules towards out\n@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))\n\n@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin\n rho_1 = mean(log, q_π) # E[ln(x)]\n rho_2 = mean(mirrorlog, q_π) # E[log(1-x)]\n m = max(rho_1, rho_2)\n tmp = exp(rho_1 - m)\n p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))\n return Bernoulli(p)\nend\n\n#rules towards π\n@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin\n p = mean(q_out)\n return Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"node: Node\nTypically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-3:-Defining-joint-marginals-for-our-node","page":"Defining a custom node and rules","title":"Step 3: Defining joint marginals for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Fqf = - sum_ainmathcalV mathrmHq_a(s_a) - sum_ainmathcalVmathrmE_q_a(s_a)ln f_a(s_a) + sum_iinmathcalEmathrmHq_i(s_i)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here we call q_a(s_a) the joint marginals around a node and -mathrmE_q_a(s_a)ln f_a(s_a) we term the average energy.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to be able to compute the Bethe free energy, we need to first describe how to compute q_a(s_a), defined in our case as ","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"q(x_k pi) = vecmu(pi) overleftarrowmu(x_k) mathrmBer(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin\n r = mean(m_out)\n p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)\n return (out = m_out, p = p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as q(x_k pi) = q(x_k)q(pi). These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing q(pi) we need to compute the product vecmu(pi)overleftarrowmu(pi). We already know how overleftarrowmu(pi) looks like from the previous step, so we can just use the prod function.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-4:-Defining-the-average-energy-for-our-node","page":"Defining a custom node and rules","title":"Step 4: Defining the average energy for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as -mathrmE_q(x_k pi)ln p(x_k mid pi), however, because we know that we observe x_k and therefore q(x_k pi) factorizes, we can instead compute beginaligned -mathrmE_q(x_k)q(pi)ln p(x_k mid pi) = -mathrmE_q(x_k)q(pi) ln (pi^x_k (1-pi)^1 - x_k) \n= -mathrmE_q(x_k)q(pi) x_k ln(pi) + (1-x_k) ln(1-pi) \n= -mathrmE_q(x_k)x_k mathrmE_q(pi) ln(pi) - (1-mathrmE_q(x_k)x_k) mathrmE_q(pi)ln(1-pi) endaligned","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to mathrmE_q(x)1-logx.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....","category":"page"},{"location":"manuals/custom-node/#Using-our-node-in-a-model","page":"Defining a custom node and rules","title":"Using our node in a model","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Random\n\nrng = MersenneTwister(42)\nn = 500\nπ_real = 0.75\ndistribution = Bernoulli(π_real)\n\ndataset = float.(rand(rng, distribution, n))\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model_mybernoulli(n)\n\n # `datavar` creates data 'inputs' in our model\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n π ~ Beta(4.0, 8.0)\n\n # We assume that outcome of each coin flip is governed by the MyBernoulli distribution\n for i in 1:n\n y[i] ~ MyBernoulli(π)\n end\n\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Finally, we can run inference with this model and the generated dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"result_mybernoulli = inference(\n model = coin_model_mybernoulli(length(dataset)), \n data = (y = dataset, ),\n)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label=\"p(π|x)\", c=3)\nvline!([π_real], label=\"Real π\")","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model(n)\n \n y = datavar(Float64, n)\n p ~ Beta(4.0, 8.0)\n\n for i in 1:n\n y[i] ~ Bernoulli(p)\n end\n\nend\n\nresult_bernoulli = inference(\n model = coin_model(length(dataset)), \n data = (y = dataset, ),\n)\n\nif !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])\n error(\"Results are not identical\")\nelse \n println(\"Results are identical 🎉🎉🎉\")\nend\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#examples-simple-nonlinear-node","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using RxInfer, Random, StableRNGs","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here is an example of creating custom node with nonlinear function approximation with samplelist.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Custom-node-creation","page":"Simple Nonlinear Node","title":"Custom node creation","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"struct NonlinearNode end # Dummy structure just to make Julia happy\n\nstruct NonlinearMeta{R, F}\n rng :: R\n fn :: F # Nonlinear function, we assume 1 float input - 1 float output\n nsamples :: Int # Number of samples used in approximation\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@node NonlinearNode Deterministic [ out, in ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"We need to define two Sum-product message computation rules for our new custom node","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Rule for outbound message on out edge given inbound message on in edge\nRule for outbound message on in edge given inbound message on out edge\nBoth rules accept optional meta object","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `out` edge given inbound message on `in` edge\n@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin \n samples = rand(meta.rng, m_in, meta.nsamples)\n return SampleList(map(meta.fn, samples))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `in` edge given inbound message on `out` edge\n@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin \n return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Model-specification","page":"Simple Nonlinear Node","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"After we have defined our custom node with custom rules we may proceed with a model specification:","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"beginaligned\np(theta) = mathcalN(thetamu_theta sigma_theta)\np(m) = mathcalN(thetamu_m sigma_m)\np(w) = f(theta)\np(y_im w) = mathcalN(y_im w)\nendaligned","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable theta through a non-linear transformation f to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of theta. ","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@model function nonlinear_estimation(n)\n \n θ ~ Normal(mean = 0.0, variance = 100.0)\n m ~ Normal(mean = 0.0, variance = 1.0)\n \n w ~ NonlinearNode(θ)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = m, precision = w)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@constraints function nconstsraints(nsamples)\n q(θ) :: SampleList(nsamples, LeftProposal())\n q(w) :: SampleList(nsamples, RightProposal())\n \n q(θ, w, m) = q(θ)q(m)q(w)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nconstsraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@meta function nmeta(fn, nsamples)\n NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here we generate some data","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn(x) = abs(exp(x) * sin(x))","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"seed = 123\nrng = StableRNG(seed)\n\nniters = 15 # Number of VMP iterations\nnsamples = 5_000 # Number of samples in approximation\n\nn = 500 # Number of IID samples\nμ = -10.0\nθ = -1.0\nw = nonlinear_fn(θ)\n\ndata = rand(rng, NormalMeanPrecision(μ, w), n);","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"result = inference(\n model = nonlinear_estimation(n),\n meta = nmeta(nonlinear_fn, nsamples),\n constraints = nconstsraints(nsamples),\n data = (y = data, ), \n initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),\n returnvars = (θ = KeepLast(), ),\n iterations = niters, \n showprogress = true\n)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"θposterior = result.posteriors[:θ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"SampleList(Univariate, 5000)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using Plots, StatsPlots\n\nestimated = Normal(mean_std(θposterior)...)\n\nplot(estimated, title=\"Posterior for θ\", label = \"Estimated\", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))\nvline!([ θ ], label = \"Real value of θ\")","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"page"},{"location":"library/exported-methods/#lib-using-methods","page":"Exported methods","title":"Using methods from RxInfer","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"A nice explanation about how modules/packages work in Julia can be found in the official documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean as mean_from_rxinfer\nimport Distributions: mean as mean_from_distributions\n\nmean_from_rxinfer === mean_from_distributions","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"# It is easier to let Julia resolve names automatically\n# Julia will not overwrite `mean` that is coming from both packages\nusing RxInfer, Distributions ","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`","category":"page"},{"location":"library/exported-methods/#lib-list-methods","page":"Exported methods","title":"List of available methods","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"note: Note\nSome exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer #hide\nforeach(println, names(RxInfer))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/#examples-nonlinear-sensor-fusion","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"section"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers\nusing DataFrames, DelimitedFiles, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"To illustrate these noisy measurements, the engineers decided to plot them:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# fetch measurements\nbeacon_locations = readdlm(\"../data/sensor_fusion/beacons.txt\")\ndistances = readdlm(\"../data/sensor_fusion/distances.txt\")\nposition = readdlm(\"../data/sensor_fusion/position.txt\")\nnr_observations = size(distances, 1);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual location of WALL-E\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\")\n\n# plot noisy distance measurements\np2 = plot(distances, legend=:topleft, linewidth=3, label=[\"distance to beacon 1\" \"distance to beacon 2\" \"distance to beacon 3\"])\nxlabel!(\"time [sec]\"), ylabel!(\"distance [m]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time t, denoted by z_t, follows a 2-dimensional normal random walk:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(z_t mid z_t - 1) = mathcalN(z_t mid z_t-1mathrmI_2)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"where mathrmI_2 denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements y_t as a noisy set of the distances between WALL-E and the beacons, specified by s_i:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(y_t mid z_t) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixmathrmI_3 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# function to compute distance to beacons\nfunction compute_distances(z) \n distance1 = norm(z - beacon_locations[1,:])\n distance2 = norm(z - beacon_locations[2,:])\n distance3 = norm(z - beacon_locations[3,:])\n distances = [distance1, distance2, distance3]\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model(nr_observations)\n \n # specify precision matrices\n W = diageye(2)\n R = diageye(3)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], W)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":" compute_distances(z) -> CVI(..., Val(false), ...)","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)\n compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"NOTE: You can try out different meta for approximating the nonlinearity, e.g.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_linear_meta()\n compute_distances(z) -> Linearization()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_unscented_meta()\n compute_distances(z) -> Unscented()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_fast = inference(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_accuracy = inference(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1000, 100, StableRNG(42)),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"After running this fast inference procedure, the engineers plot the results and evaluate the performance:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_fast.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Fast (1 sample, 3 iterations)\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot beacon and actual and estimated location of WALL-E (accurate inference)\np2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_accuracy.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Accurate (1000 samples, 100 iterations)\"); p2.series_list[end][:label] = \"estimated location ±2σ\"\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, Q and R respectively. They did this by adding Wishart priors to those matrices:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(Q) = mathcalW(Q mid 3 mathrmI_2) \n p(R) = mathcalW(R mid 4 mathrmI_3) \n p(z_t mid z_t - 1 Q) = mathcalN(z_t mid z_t-1 Q^-1)\n p(y_t mid z_t R) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixR^-1 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model_wishart(nr_observations)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # set priors on precision matrices\n Q ~ Wishart(3, diageye(2))\n R ~ Wishart(4, diageye(3))\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], Q)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"meta = @meta begin \n compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"constraints = @constraints begin\n q(z, Q, R) = q(z)q(Q)q(R)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_wishart = inference(\n model = random_walk_model_wishart(nr_observations),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = constraints,\n meta = meta,\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),\n initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"They plot the new estimates and the performance over time, and luckily WALL-E is found!","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_wishart.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot bethe free energy performance\np2 = plot(results_wishart.free_energy, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"page"},{"location":"examples/problem_specific/overview/#examples-problem_specific-overview","page":"Overview","title":"Problem specific","text":"","category":"section"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Autoregressive Models: An example of Bayesian treatment of latent AR and ARMA models. Reference: Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.\nGamma Mixture Model: This example implements one of the Gamma mixture experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/ .\nGaussian Mixture: This example implements variational Bayesian inference in univariate and multivariate Gaussian mixture models with mean-field assumption.\nHierarchical Gaussian Filter: An example of online inference procedure for Hierarchical Gaussian Filter with univariate noisy observations using Variational Message Passing algorithm. Reference: Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter.\nInvertible neural networks: a tutorial: An example of variational Bayesian Inference with invertible neural networks. Reference: Bart van Erp, Hybrid Inference with Invertible Neural Networks in Factor Graphs.\nProbit Model (EP): In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model.\nRTS vs BIFM Smoothing: This example performs BIFM Kalman smoother on a factor graph using message passing and compares it with the RTS implementation.\nSimple Nonlinear Node: In this example we create a non-conjugate model and use a nonlinear link function between variables. We show how to extend the functionality of RxInfer and to create a custom factor node with arbitrary message passing update rules.\nUniversal Mixtures: Universal mixture modeling.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/#examples-coin-toss-model-(beta-bernoulli)","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"section"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"In this example, we are going to perform an exact inference for a coin toss model that can be represented as:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"beginaligned\np(theta) = mathrmBeta(thetaa b)\np(y_itheta) = mathrmBer(y_itheta)\nendaligned","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"where y_i in 0 1 is a binary observation induced by Bernoulli likelihood while theta is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of theta.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using RxInfer, Random","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"rng = MersenneTwister(42)\nn = 500\nθ_real = 0.75\ndistribution = Bernoulli(θ_real)\n\ndataset = float.(rand(rng, Bernoulli(θ_real), n));","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n θ ~ Beta(4.0, 8.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n\n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"result = inference(\n model = coin_model(length(dataset)), \n data = (y = dataset, )\n)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Beta{Float64}(α=365.0, β=147.0)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\nplot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\nvline!([θ_real], label=\"Real θ\")","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"page"},{"location":"manuals/inference/rxinference/#user-guide-rxinference","page":"Real-time dataset / reactive inference","title":"Automatic inference specification on real-time datasets","text":"","category":"section"},{"location":"manuals/inference/rxinference/","page":"Real-time dataset / reactive inference","title":"Real-time dataset / reactive inference","text":"RxInfer exports the rxinference function to quickly run and test you model with dynamic and potentially real-time datasets. Note, however, that this function does cover almost all capabilities of the reactive inference engine, but for advanced use cases you may want to resort to the manual inference specification.","category":"page"},{"location":"manuals/inference/rxinference/","page":"Real-time dataset / reactive inference","title":"Real-time dataset / reactive inference","text":"For running inference on static datasets see the Static Inference section. For manual inference specification see the Manual Inference section.","category":"page"},{"location":"manuals/inference/rxinference/","page":"Real-time dataset / reactive inference","title":"Real-time dataset / reactive inference","text":"rxinference\nRxInfer.start\nRxInfer.stop\n@autoupdates\nRxInferenceEngine\nRxInferenceEvent","category":"page"},{"location":"manuals/inference/rxinference/#RxInfer.rxinference","page":"Real-time dataset / reactive inference","title":"RxInfer.rxinference","text":"rxinference(\n model,\n data = nothing,\n datastream = nothing,\n initmarginals = nothing,\n initmessages = nothing,\n autoupdates = nothing,\n constraints = nothing,\n meta = nothing,\n options = nothing,\n returnvars = nothing,\n historyvars = nothing,\n keephistory = nothing,\n iterations = nothing,\n free_energy = false,\n free_energy_diagnostics = BetheFreeEnergyDefaultChecks,\n autostart = true,\n events = nothing,\n callbacks = nothing,\n addons = nothing,\n postprocess = DefaultPostprocess(),\n uselock = false,\n warn = true\n)\n\nThis function provides a generic way to perform probabilistic inference in RxInfer.jl. Returns RxInferenceEngine.\n\nArguments\n\nFor more information about some of the arguments, please check below.\n\nmodel: specifies a model generator, required\ndata: NamedTuple or Dict with data, required (or datastream)\ndatastream: A stream of NamedTuple with data, required (or data)\ninitmarginals = nothing: NamedTuple or Dict with initial marginals, optional\ninitmessages = nothing: NamedTuple or Dict with initial messages, optional\nautoupdates = nothing: auto-updates specification, required for many models, see @autoupdates\nconstraints = nothing: constraints specification object, optional, see @constraints\nmeta = nothing: meta specification object, optional, may be required for some models, see @meta\noptions = nothing: model creation options, optional, see ModelInferenceOptions\nreturnvars = nothing: return structure info, optional, by default creates observables for all random variables that return posteriors at last vmp iteration, see below for more information\nhistoryvars = nothing: history structure info, optional, defaults to no history, see below for more information\nkeephistory = nothing: history buffer size, defaults to empty buffer, see below for more information\niterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information\nfree_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl\nfree_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.\nautostart = true: specifies whether to call RxInfer.start on the created engine automatically or not\nshowprogress = false: show progress module, optional, defaults to false\nevents = nothing: inference cycle events, optional, see below for more info\ncallbacks = nothing: inference cycle callbacks, optional, see below for more info\naddons = nothing: inject and send extra computation information along messages, see below for more info\npostprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info\nuselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock.\nwarn = true: enables/disables warnings\n\nNote on NamedTuples\n\nWhen passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.\n\nExtended information about some of the arguments\n\ndata or datastream\n\nEither data or datastream keyword argument is required, but specifying both is not supported and will result in an error.\n\ndata\n\nThe data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds an iterable container with values of type Float64. The elements of such containers in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide an iterable container with elements of type Vector{Float64}. \n\nAll entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.\n\nNote: The behavior of the data keyword argument is different from that which is used in the inference function.\n\ndatastream\n\nThe datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.\n\nNote: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the inference function and its data argument. In fact, you can see the rxinference function as an efficient streamed version of the inference function, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.\n\nmodel\n\nThe model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:\n\n@model function coin_toss(some_argument, some_keyword_argument = 3)\n ...\nend\n\nresult = rxinference(\n model = coin_toss(some_argument; some_keyword_argument = 3)\n)\n\nNote: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.\n\ninitmarginals\n\nFor specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as\n\nrxinference(...\n initmarginals = (\n # initialize the marginal distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. initmarginals = (a = ..., ), or dictionary.\n\ninitmessages\n\nFor specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the initmessages argument, such as\n\nrxinference(...\n initmessages = (\n # initialize the messages distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. initmessages = (a = ..., ), or dictionary.\n\nautoupdates\n\nSee @autoupdates for more information.\n\noptions\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\nreturnvars\n\nreturnvars accepts a tuple of symbols and specifies the latent variables of interests. For each symbol in the returnvars specification the rxinference function will prepare an observable stream (see Rocket.jl) of posterior updates. An agent may subscribe on the new posteriors events and perform some actions. For example:\n\nengine = rxinference(\n ...,\n returnvars = (:x, :τ),\n autostart = false\n)\n\nx_subscription = subscribe!(engine.posteriors[:x], (update) -> println(\"x variable has been updated: \", update))\nτ_subscription = subscribe!(engine.posteriors[:τ], (update) -> println(\"τ variable has been updated: \", update))\n\nRxInfer.start(engine)\n\n...\n\nunsubscribe!(x_subscription)\nunsubscribe!(τ_subscription)\n\nRxInfer.stop(engine)\n\nhistoryvars\n\nhistoryvars specifies the variables of interests and the amount of information to keep in history about the posterior updates. The specification is similar to the returnvars in the inference procedure. The historyvars requires keephistory to be greater than zero.\n\nhistoryvars accepts a NamedTuple or Dict or return var specification. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = rxinference(\n ...,\n historyvars = (\n x = KeepLast(),\n τ = KeepEach()\n ),\n keephistory = 10\n)\n\nIt is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.\n\nExample:\n\nresult = rxinference(\n ...,\n historyvars = KeepLast(),\n keephistory = 10\n)\n\nkeep_history\n\nSpecifies the buffer size for the updates history both for the historyvars and the free_energy buffers.\n\niterations\n\nSpecifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration. \n\nfree_energy\n\nThis setting specifies whenever the inference function should create an observable of Bethe Free Energy (BFE) values. The BFE observable returns a new computed value for each VMP iteration. Note, however, that it may be not possible to compute BFE values for every model. If free_energy = true and keephistory > 0 the engine exposes extra fields to access the history of the Bethe free energy updates:\n\nengine.free_energy_history: Returns a free energy history averaged over the VMP iterations\nengine.free_energy_final_only_history: Returns a free energy history of values computed on last VMP iterations for every observation\nengine.free_energy_raw_history: Returns a raw free energy history\n\nAdditionally, the argument may accept a floating point type, instead of a Bool value. Using this option, e.g.Float64, improves performance of Bethe Free Energy computation, but restricts using automatic differentiation packages.\n\nfree_energy_diagnostics\n\nThis settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.\n\nevents\n\nThe engine from the rxinference function has its own lifecycle. The events can be listened by subscribing to the engine.events field. E.g.\n\nengine = rxinference(\n ...,\n autostart = false\n)\n\nsubscription = subscribe!(engine.events, (event) -> println(event))\n\nRxInfer.start(engine)\n\nBy default all events are disabled, in order to enable an event its identifier must be listed in the Val tuple of symbols passed to the events keyword arguments.\n\nengine = rxinference(\n events = Val((:on_new_data, :before_history_save, :after_history_save))\n)\n\nThe list of all possible events and their event data is present below (see RxInferenceEvent for more information about the type of event data):\n\non_new_data: args: (model::FactorGraphModel, data)\nbefore_iteration args: (model::FactorGraphModel, iteration)\nbefore_auto_update args: (model::FactorGraphModel, iteration, auto_updates)\nafter_auto_update args: (model::FactorGraphModel, iteration, auto_updates)\nbefore_data_update args: (model::FactorGraphModel, iteration, data)\nafter_data_update args: (model::FactorGraphModel, iteration, data)\nafter_iteration args: (model::FactorGraphModel, iteration)\nbefore_history_save args: (model::FactorGraphModel, )\nafter_history_save args: (model::FactorGraphModel, )\non_tick args: (model::FactorGraphModel, )\non_error args: (model::FactorGraphModel, err)\non_complete args: (model::FactorGraphModel, )\ncallbacks\n\nThe rxinference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the preparation of the inference engine. To inject extra procedures during the inference use the events. Here is the example of the callbacks\n\nresult = rxinference(\n ...,\n callbacks = (\n after_model_creation = (model, returnval) -> println(\"The model has been created. Number of nodes: $(length(getnodes(model)))\"),\n )\n)\n\nThe callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks and their input arguments is present below:\n\nbefore_model_creation: args: ()\nafter_model_creation: args: (model::FactorGraphModel, returnval)\nbefore_autostart: args: (engine::RxInferenceEngine)\nafter_autostart: args: (engine::RxInferenceEngine)\naddons\n\nThe addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.\n\npostprocess\n\nThe postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.\n\nSee also inference\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/rxinference/#RxInfer.start","page":"Real-time dataset / reactive inference","title":"RxInfer.start","text":"start(engine::RxInferenceEngine)\n\nStarts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.stop\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/rxinference/#RxInfer.stop","page":"Real-time dataset / reactive inference","title":"RxInfer.stop","text":"stop(engine::RxInferenceEngine)\n\nStops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.start\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/rxinference/#RxInfer.@autoupdates","page":"Real-time dataset / reactive inference","title":"RxInfer.@autoupdates","text":"@autoupdates\n\nCreates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification. \n\nEach line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.\n\nFor example:\n\n@autoupdates begin \n x = f(q(z))\nend\n\nThis structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically. \n\nAs an example consider the following model and auto-update specification:\n\n@model function kalman_filter()\n x_current_mean = datavar(Float64)\n x_current_var = datavar(Float64)\n\n x_current ~ Normal(mean = x_current_mean, var = x_current_var)\n\n x_next ~ Normal(mean = x_current, var = 1.0)\n\n y = datavar(Float64)\n y ~ Normal(mean = x_next, var = 1.0)\nend\n\nThis model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:\n\nautoupdates = @autoupdates begin\n x_current_mean, x_current_var = mean_cov(q(x_next))\nend\n\nThis structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.\n\nSee also: rxinference\n\n\n\n\n\n","category":"macro"},{"location":"manuals/inference/rxinference/#RxInfer.RxInferenceEngine","page":"Real-time dataset / reactive inference","title":"RxInfer.RxInferenceEngine","text":"RxInferenceEngine\n\nThe return value of the rxinference function. \n\nPublic fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the rxinference.\nfree_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the rxinference.\nhistory: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the rxinference.\nfree_energy_history: (optional) Free energy history, average over variational iterations \nfree_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)\nfree_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)\nevents: (optional) A stream of events send by the inference engine. See the events argument for the rxinference.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\n\nUse the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.\n\nSee also: rxinference, RxInferenceEvent, RxInfer.start, RxInfer.stop\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/rxinference/#RxInfer.RxInferenceEvent","page":"Real-time dataset / reactive inference","title":"RxInfer.RxInferenceEvent","text":"RxInferenceEvent{T, D}\n\nThe RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.\n\nThe events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:\n\nusing Rocket\n\nstruct MyEventListener <: Rocket.Actor{RxInferenceEvent}\n # ... extra fields\nend\n\nfunction Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })\n model, iteration = event\n println(\"Iteration $(iteration) has been finished.\")\nend\n\nfunction Rocket.on_error!(listener::MyEventListener, err)\n # ...\nend\n\nfunction Rocket.on_complete!(listener::MyEventListener)\n # ...\nend\n\n\nand later on:\n\nengine = rxinference(events = Val((:after_iteration, )), ...)\n\nsubscription = subscribe!(engine.events, MyEventListener(...))\n\nSee also: rxinference, RxInferenceEngine\n\n\n\n\n\n","category":"type"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#examples-invertible-neural-networks:-a-tutorial","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Table of contents","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Introduction\nModel specification\nModel compilation\nProbabilistic inference\nParameter estimation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Introduction","page":"Invertible neural networks: a tutorial","title":"Introduction","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Load-required-packages","page":"Invertible neural networks: a tutorial","title":"Load required packages","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Before we can start, we need to import some packages:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using RxInfer\nusing Random\nusing StableRNGs\n\nusing ReactiveMP # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality\nusing LinearAlgebra # only used for some matrix specifics\nusing Plots # only used for visualisation\nusing Distributions # only used for sampling from multivariate distributions\nusing Optim # only used for parameter optimisation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-specification","page":"Invertible neural networks: a tutorial","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Alternatively, the input_dim can also be passed as an InputLayer layer as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the above AdditiveCouplingLayer layers the input bfx = x_1 x_2 ldots x_N is partitioned into chunks of unit length. These partitions are additively coupled to an output bfy = y_1 y_2 ldots y_N as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n y_1 = x_1 \n y_2 = x_2 + f_1(x_1) \n vdots \n y_N = x_N + f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Importantly, this structure can easily be converted as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n x_1 = y_1 \n x_2 = y_2 - f_1(x_1) \n vdots \n x_N = y_N - f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"f_n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow(); permute=false),\n PermutationLayer(PermutationMatrix(2)),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-compilation","page":"Invertible neural networks: a tutorial","title":"Model compilation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the current models, the layers are setup to work with the passed input dimension. This means that the function f_n is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P\nlanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa\nyerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou\nplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar\nFlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad\nditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive\nMP.PlanarFlowEmpty{1}(),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel - specifies that we are dealing with a flow model.\n3 - Number of layers.\nTuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.\nTuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions f_n.\nPermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(-0.51319441885293, -0.562855685\n8301944, -0.6039741162529291),), 1), PermutationLayer{Int64}(2, [0 1; 1 0])\n, AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlow\n{Float64, Float64}(-0.41324059953248177, -0.6524105536272277, 0.01360673107\n9877291),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361\n28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323\n52386),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Probabilistic-inference","page":"Invertible neural networks: a tutorial","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)\n\n rng = StableRNG(seed)\n \n # specify latent sampling distribution\n dist = MvNormal([1.5, 0.5], I)\n\n # sample from the latent distribution\n x = rand(rng, dist, nr_samples)\n\n # transform data\n y = zeros(Float64, size(x))\n for k = 1:nr_samples\n y[:,k] .= ReactiveMP.forward(model, x[:,k])\n end\n\n # return data\n return y, x\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# generate data\ny, x = generate_data(1000, compiled_model)\n\n# plot generated data\np1 = scatter(x[1,:], x[2,:], alpha=0.3, title=\"Original data\", size=(800,400))\np2 = scatter(y[1,:], y[2,:], alpha=0.3, title=\"Transformed data\", size=(800,400))\nplot(p1, p2, legend = false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The probabilistic model for doing inference can be described as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network(nr_samples::Int64)\n \n # initialize variables\n z_μ = randomvar()\n z_Λ = randomvar()\n x = randomvar(nr_samples)\n y_lat = randomvar(nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n\n # specify prior\n z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))\n z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)\n\n # specify transformed latent value\n y_lat[k] ~ Flow(x[k])\n\n # specify observations\n y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))\n\n end\n\n # return variables\n return z_μ, z_Λ, x, y_lat, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here the model is passed inside a meta data object of the flow node. Inference then resorts to","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"observations = [y[:,k] for k=1:size(y,2)]\n\nfmodel = invertible_neural_network(length(observations))\ndata = (y = observations, )\ninitmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))\nreturnvars = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())\n\nconstraints = @constraints begin\n q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)\nend\n\n@meta function fmeta(model)\n compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))\n Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). \n # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))\nend\n\n# First execution is slow due to Julia's initial compilation \nresult = inference(\n model = fmodel, \n data = data,\n constraints = constraints,\n meta = fmeta(model),\n initmarginals = initmarginals,\n returnvars = returnvars,\n free_energy = true,\n iterations = 10, \n showprogress = false\n)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Inference results:\n Posteriors | available for (z_μ, z_Λ, y_lat, x)\n Free Energy: | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357\n0.6, 23570.6, 23570.6, 23570.6, 23570.6]","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fe_flow = result.free_energy\nzμ_flow = result.posteriors[:z_μ]\nzΛ_flow = result.posteriors[:z_Λ]\nx_flow = result.posteriors[:x]\ny_flow = result.posteriors[:y_lat];","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"As we can see, the variational free energy decreases inside of our model.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"plot(1:10, fe_flow/size(y,2), xlabel=\"iteration\", ylabel=\"normalized variational free energy [nats/sample]\", legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"If we plot a random noisy observation and its approximated transformed uncertainty we obtain:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# pick a random observation\nid = rand(StableRNG(321), 1:size(y,2))\nrand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))\nwarped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');\n\np1 = scatter(x[1,:], x[2,:], alpha=0.1, title=\"Latent distribution\", size=(1200,500), label=\"generated data\")\ncontour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)\nscatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color=\"red\", markershape=:x, markersize=5, label=\"inferred mean\")\ncontour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, colorbar=false)\nscatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color=\"red\", label=\"transformed noisy observation\")\np2 = scatter(y[1,:], y[2,:], alpha=0.1, label=\"generated data\")\nscatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color=\"red\", marker=:x, label=\"inferred mean\")\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, label=\"random noisy observation\", colorba=false)\nscatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color=\"red\", label=\"random noisy observation\")\nplot(p1, p2, legend = true)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Parameter-estimation","page":"Invertible neural networks: a tutorial","title":"Parameter estimation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n\n # sample weights\n w = rand(rng, nr_samples, 2)\n\n # sample appraisal\n y = zeros(Float64, nr_samples)\n for k = 1:nr_samples\n y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)\n end\n\n # return data\n return y, w\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"data_y, data_x = generate_data(50);\nscatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel=\"w1\", ylabel=\"w2\", colorbar=false, legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We will then specify a possible model as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# specify flow model\nmodel = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The corresponding probabilistic model for the binary classification task can be created as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network_classifier(nr_samples::Int64)\n \n # initialize variables\n x_lat = randomvar(nr_samples)\n y_lat1 = randomvar(nr_samples)\n y_lat2 = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n x = datavar(Vector{Float64}, nr_samples)\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))\n\n # specify transformed latent value\n y_lat1[k] ~ Flow(x_lat[k])\n y_lat2[k] ~ dot(y_lat1[k], [1, 1])\n\n # specify observations\n y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }\n\n end\n\n # return variables\n return x_lat, x, y_lat1, y_lat2, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fcmodel = invertible_neural_network_classifier(length(data_y))\ndata = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )\n\n@meta function fmeta(model, params)\n compiled_model = compile(model, params)\n Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)\nend","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fmeta (generic function with 2 methods)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function f(params)\n Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure\n result = inference(\n model = fcmodel, \n data = data,\n meta = fmeta(model, params),\n free_energy = true,\n free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure\n iterations = 10, \n showprogress = false\n );\n \n result.free_energy[end]\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"uses finitediff and is slower/less accurate.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"or","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# create gradient function\ng = (x) -> ForwardDiff.gradient(f, x);\n\n# specify initial params\nparams = randn(nr_params(model))\n\n# create custom optimizer (here Adam)\noptimizer = Adam(params; λ=1e-1)\n\n# allocate space for gradient\n∇ = zeros(nr_params(model))\n\n# perform optimization\nfor it = 1:10000\n\n # backward pass\n ∇ .= ForwardDiff.gradient(f, optimizer.x)\n\n # gradient update\n ReactiveMP.update!(optimizer, ∇)\n\nend\n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Iter Function value Gradient norm \n 0 5.888958e+02 8.943663e+02\n * time: 0.022298812866210938\n 100 1.059826e+01 4.120090e+00\n * time: 14.472792863845825\n * Status: success\n\n * Candidate solution\n Final objective value: 1.010332e+01\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.21e-03 ≰ 0.0e+00\n |x - x'|/|x'| = 5.80e-04 ≰ 0.0e+00\n |f(x) - f(x')| = 6.28e-03 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03\n |g(x)| = 2.07e+00 ≰ 1.0e-08\n\n * Work counters\n Seconds run: 16 (vs limit Inf)\n Iterations: 113\n f(x) calls: 301\n ∇f(x) calls: 301","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"optimization results are then given as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"params = Optim.minimizer(res)\ninferred_model = compile(model, params)\ntrans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'\ntrans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])\ntrans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title=\"original data\")\np2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title=\"|> warp\")\np3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title=\"|> dot\")\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using StatsFuns: normcdf\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title=\"original labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title=\"predicted labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title=\"Classification map\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"contributing/new-example/#contributing-new-example","page":"Contributing to the examples","title":"Contributing to the examples","text":"","category":"section"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/\"subcategory\" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"After preparing the new example it is necessary to modify the examples/.meta.jl file.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"Make sure that the very first cell of the notebook contains ONLY # in it and has the markdown cell type. This is important for generating links in our documentation.\nThe path option must be set to a local path in a category sub-folder.\nThe text in the description option will be used on the Examples page in the documentation.\nSet category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).\nPlease do no use Overview as a name for the new example, the title Overview is reserved.\nUse the following template for equations, note that $$ and both \\begin and \\end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"$$\\begin{aligned}\n <latex equations here>\n\\end{aligned}$$","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.\nNotebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"variable = 0\nfor i in 1:10\n global variable = variable + i\nend","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.\nAll plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nPlease avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nUse make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.","category":"page"},{"location":"library/model-specification/#lib-model-specification","page":"Model specification","title":"Model specification in RxInfer","text":"","category":"section"},{"location":"library/model-specification/","page":"Model specification","title":"Model specification","text":"RxInfer.@model\nRxInfer.ModelGenerator\nRxInfer.create_model\nRxInfer.ModelInferenceOptions","category":"page"},{"location":"library/model-specification/#RxInfer.@model","page":"Model specification","title":"RxInfer.@model","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model description\nend\n\n@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.\n\nSupported alias in the model specification\n\na || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).\na && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\na -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\n¬a and !a: alias for NOT(a) node (Unicode \\neg, operator precedence ||, &&, -> and ! is the same as in Julia).\na + b + c: alias for (a + b) + c\na * b * c: alias for (a * b) * c\nNormal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.\nNormal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.\nMvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nGamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.\nGamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.\n\n\n\n\n\n","category":"macro"},{"location":"library/model-specification/#RxInfer.ModelGenerator","page":"Model specification","title":"RxInfer.ModelGenerator","text":"ModelGenerator\n\nModelGenerator is a special object that is used in the inference function to lazily create model later on given constraints, meta and options.\n\nSee also: inference\n\n\n\n\n\n","category":"type"},{"location":"library/model-specification/#RxInfer.create_model","page":"Model specification","title":"RxInfer.create_model","text":"create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)\n\nCreates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.\n\nReturns a tuple of 2 values:\n\nan instance of FactorGraphModel\nreturn value from the @model macro function definition\n\n\n\n\n\n","category":"function"},{"location":"library/model-specification/#RxInfer.ModelInferenceOptions","page":"Model specification","title":"RxInfer.ModelInferenceOptions","text":"ModelInferenceOptions(; kwargs...)\n\nCreates model inference options object. The list of available options is present below.\n\nOptions\n\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\nwarn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.\n\nAdvanced options\n\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\n\nSee also: inference, rxinference\n\n\n\n\n\n","category":"type"},{"location":"manuals/getting-started/#user-guide-getting-started","page":"Getting started","title":"Getting started","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.","category":"page"},{"location":"manuals/getting-started/#Installation","page":"Getting started","title":"Installation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Install RxInfer through the Julia package manager:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"] add RxInfer","category":"page"},{"location":"manuals/getting-started/#Importing-RxInfer","page":"Getting started","title":"Importing RxInfer","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"To add RxInfer package (and all associated packages) into a running Julia session simply run:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more about about using in the Using methods from RxInfer section of the documentation.","category":"page"},{"location":"manuals/getting-started/#Example:-Inferring-the-bias-of-a-coin","page":"Getting started","title":"Example: Inferring the bias of a coin","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The RxInfer approach to solving inference problems consists of three phases:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.\nInference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.\nInference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.","category":"page"},{"location":"manuals/getting-started/#Coin-flip-simulation","page":"Getting started","title":"Coin flip simulation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"First let's setup our environment by importing all needed packages:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Next, let's define our dataset:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"rng = MersenneTwister(42)\nn = 10\np = 0.75\ndistribution = Bernoulli(p)\n\ndataset = float.(rand(rng, Bernoulli(p), n))","category":"page"},{"location":"manuals/getting-started/#getting-started-model-specification","page":"Getting started","title":"Model specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In 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.","category":"page"},{"location":"manuals/getting-started/#Likelihood","page":"Getting started","title":"Likelihood","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"y_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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 01.","category":"page"},{"location":"manuals/getting-started/#Prior","page":"Getting started","title":"Prior","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"theta sim Beta(a b)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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. ","category":"page"},{"location":"manuals/getting-started/#Joint-probability","page":"Getting started","title":"Joint probability","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The joint probability is given by the multiplication of the likelihood and the prior, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"P(y_1N θ) = P(θ) prod_i=1^N P(y_i θ)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Now let's see how to specify this model using GraphPPL's package syntax.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"\n# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n \n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during inference step\n return y, θ\nend\n","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create \"clamped\" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG. ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-specification","page":"Getting started","title":"Inference specification","text":"","category":"section"},{"location":"manuals/getting-started/#Automatic-inference-specification","page":"Getting started","title":"Automatic inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Once 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 inference function that supports static datasets.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"result = inference(\n model = coin_model(length(dataset)),\n data = (y = dataset, )\n)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more information about the inference function in the Static Inference documentation section.","category":"page"},{"location":"manuals/getting-started/#Manual-inference-specification","page":"Getting started","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Return variables of interests from model specification\nSubscribe on variables of interests posterior marginal updates\nPass data to the model\nUnsubscribe ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here is an example of inference procedure:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"function custom_inference(data)\n n = length(data)\n\n # `coin_model` function from `@model` macro returns a reference to the model generator object\n # we need to use the `create_model` function to get actual model object\n model, (y, θ) = create_model(coin_model(n))\n \n # Reference for future posterior marginal \n mθ = nothing\n\n # `getmarginal` function returns an observable of future posterior marginal updates\n # We use `Rocket.jl` API to subscribe on this observable\n # As soon as posterior marginal update is available we just save it in `mθ`\n subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)\n \n # `update!` function passes data to our data inputs\n update!(y, data)\n \n # It is always a good practice to unsubscribe and to \n # free computer resources held by the subscription\n unsubscribe!(subscription)\n \n # Here we return our resulting posterior marginal\n return mθ\nend","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-execution","page":"Getting started","title":"Inference execution","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = custom_inference(dataset)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title=\"Prior\", fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\np2 = plot(rθ, (x) -> pdf(θestimated, x), title=\"Posterior\", fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"dataset_100 = float.(rand(rng, Bernoulli(p), 100))\ndataset_1000 = float.(rand(rng, Bernoulli(p), 1000))\ndataset_10000 = float.(rand(rng, Bernoulli(p), 10000))\nnothing # hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated_100 = custom_inference(dataset_100)\nθestimated_1000 = custom_inference(dataset_1000)\nθestimated_10000 = custom_inference(dataset_10000)\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"p3 = plot(title = \"Posterior\", legend = :topleft)\n\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_100)\", c = 4)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_1000)\", c = 5)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_10000)\", c = 6)\n\nplot(p1, p3, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated_10000))\nprintln(\"std: \", std(θestimated_10000))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/#Where-to-go-next?","page":"Getting started","title":"Where to go next?","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.","category":"page"},{"location":"manuals/debugging/#user-guide-debugging","page":"Debugging","title":"Debugging","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want. ","category":"page"},{"location":"manuals/debugging/#Requesting-a-trace-of-messages","page":"Debugging","title":"Requesting a trace of messages","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a \"Memory Addon\". Below is an example explaining how you can extract this history and use it to fix a bug.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Consider the coin toss example from earlier in the documentation. We model the binary outcome x (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the theta parameter, with a known shape 𝑎 and rate 𝑏 parameter.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"x_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"theta sim mathrmBeta(a b)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"where x_i in 0 1 are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"using RxInfer, Random, Plots\n\nn = 4\nθ_real = 0.3\ndataset = convert.(Int64, rand(Bernoulli(θ_real), n))\n\n@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, huge)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = inference(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);\n","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The model will run without errors. But when we plot the posterior distribution for theta, something's wrong. The posterior seems to be a flat distribution:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"\nrθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"result = inference(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n addons = (AddonMemory(),)\n)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now we have access to the messages that led to the marginal posterior:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"underbraceoverrightarrowmu_θ(θ)_substack textoutgoing textmessage = sum_x_1ldotsx_n underbraceoverrightarrowmu_X_1(x_1)cdots overrightarrowmu_X_n(x_n)_substacktextincoming textmessages cdot underbracef(θx_1ldotsx_n)_substacktextnode textfunction","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Graph)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of theta we used in the code block above. So why does the posterior have this rate parameter?","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, 100)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = inference(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"rθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now the posterior is visible in the plot.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#examples-active-inference-mountain-car","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#The-environmental-process-of-the-mountain","page":"Active Inference Mountain car","title":"The environmental process of the mountain","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Firstly, we specify the environmental process according to Ueltzhoeffer (2017) \"Deep active inference\". This process shows how the environment evolves after interacting with the agent.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Particularly, let's denote z_t = (phi_t dotphi_t) as the environmental state depending on the position phi_t and velocity dotphi_t of the car; a_t as the action of the environment on the car. Then the evolution of the state is described as follows ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndotphi_t = dotphi_t-1 + F_g(phi_t-1) + F_f(dotphi_t-1) + F_a(a_t)\nphi_t = phi_t-1 + dotphi_t \nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where F_g(phi_t-1) is the gravitational force of the hill landscape that depends on the car's position","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_g(phi) = begincases\n -005(2phi + 1) mathrmif phi 0 \n -005 left(1 + 5phi^2)^-frac12 + phi^2 (1 + 5phi^2)^-frac32 + frac116phi^4 right mathrmotherwise\nendcases","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_f(dotphi)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"is the friction on the car defined through the car's velocity F_f(dotphi) = -01 dotphi and F_a(a) is the engine force F_a(a) = 004 tanh(a) Since the car is on low battery, we use the tanh(cdot) function to limit the engine force to the interval [-0.04, 0.04].","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the create_physics function defines forces F_g F_f F_a; and the create_world function defines the environmental process of the mountain.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import HypergeometricFunctions: _₂F₁\n\nfunction create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)\n # Engine force as function of action\n Fa = (a::Real) -> engine_force_limit * tanh(a) \n\n # Friction force as function of velocity\n Ff = (y_dot::Real) -> -friction_coefficient * y_dot \n \n # Gravitational force (horizontal component) as function of position\n Fg = (y::Real) -> begin\n if y < 0\n 0.05*(-2*y - 1)\n else\n 0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)\n end\n end\n \n # The height of the landscape as a function of the horizontal coordinate\n height = (x::Float64) -> begin\n if x < 0\n h = x^2 + x\n else\n h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80\n end\n return 0.05*h\n end\n\n return (Fa, Ff, Fg,height)\nend;\n\nfunction create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)\n\n y_t_min = initial_position\n y_dot_t_min = initial_velocity\n \n y_t = y_t_min\n y_dot_t = y_dot_t_min\n \n execute = (a_t::Float64) -> begin\n # Compute next state\n y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)\n y_t = y_t_min + y_dot_t\n \n # Reset state for next step\n y_t_min = y_t\n y_dot_t_min = y_dot_t\n end\n \n observe = () -> begin \n return [y_t, y_dot_t]\n end\n \n return (execute, observe)\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_world (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Let's visualize the mountain landscape and the situation of the car. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"engine_force_limit = 0.04\nfriction_coefficient = 0.1\n\nFa, Ff, Fg, height = create_physics(\n engine_force_limit = engine_force_limit,\n friction_coefficient = friction_coefficient\n);\ninitial_position = -0.5\ninitial_velocity = 0.0\n\nx_target = [0.5, 0.0] \n\nvalley_x = range(-2, 2, length=400)\nvalley_y = [ height(xs) for xs in valley_x ]\nplot(valley_x, valley_y, title = \"Mountain valley\", label = \"Landscape\", color = \"black\")\nscatter!([ initial_position ], [ height(initial_position) ], label=\"initial car position\") \nscatter!([x_target[1]], [height(x_target[1])], label=\"camping site\")","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Naive-approach","page":"Active Inference Mountain car","title":"Naive approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"N_naive = 100 # Total simulation time\npi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only\n\n# Let there be a world\n(execute_naive, observe_naive) = create_world(; \n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n);\n\ny_naive = Vector{Vector{Float64}}(undef, N_naive)\nfor t = 1:N_naive\n execute_naive(pi_naive[t]) # Execute environmental process\n y_naive[t] = observe_naive() # Observe external states\nend\n\nanimation_naive = @animate for i in 1:N_naive\n plot(valley_x, valley_y, title = \"Naive policy\", label = \"Landscape\", color = \"black\", size = (800, 400))\n scatter!([y_naive[i][1]], [height(y_naive[i][1])], label=\"car\")\n scatter!([x_target[1]], [height(x_target[1])], label=\"goal\") \nend\n\n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_naive, \"../pics/ai-mountain-car-naive.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Active-inference-approach","page":"Active Inference Mountain car","title":"Active inference approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned\np_t(xsu) propto p(s_t-1) prod_k=t^t+T p(x_k mid s_k) p(s_k mid s_k-1u_k) p(u_k) p(x_k) nonumber\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where the factors are defined as","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k) = mathcalN(x_k mid x_goalV_goal) quad (mathrmtarget)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_k mid s_k-1u_k) = mathcalN(s_k mid tildeg(s_k-1)+h(u_k)gamma^-1) quad (mathrmstate transition)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k mid s_k) = mathcalN(x_k mid s_ktheta) quad (mathrmobservation)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(u_k) = mathcalN(u_k mid m_uV_u) quad (mathrmcontrol)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_t-1) = mathcalN(s_t-1 mid m_t-1V_t-1) quad (mathrmprevious state)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"x\ndenotes observations of the agent after interacting with the environment; \ns_t = (s_tdots_t)\nis the state of the car embodying its position and velocity; \nu_t\ndenotes the control state of the agent; \nh(cdot)\nis the tanh(cdot) function modeling engine control; \ntildeg(cdot)\nexecutes a linear approximation of equations (1) and (2): ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndots_t = dots_t-1 + F_g(s_t-1) + F_f(dots_t-1)\ns_t = s_t-1 + dots_t\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)\n \n # Transition function modeling transition due to gravity and friction\n g = (s_t_min::AbstractVector) -> begin \n s_t = similar(s_t_min) # Next state\n s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity\n s_t[1] = s_t_min[1] + s_t[2] # Update position\n return s_t\n end\n \n # Function for modeling engine control\n h = (u::AbstractVector) -> [0.0, Fa(u[1])] \n \n # Inverse engine force, from change in state to corresponding engine force\n h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] \n \n # Internal model perameters\n Gamma = 1e4*diageye(2) # Transition precision\n Theta = 1e-4*diageye(2) # Observation variance\n \n m_s_t_min = datavar(Vector{Float64})\n V_s_t_min = datavar(Matrix{Float64})\n\n s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)\n s_k_min = s_t_min\n \n m_u = datavar(Vector{Float64}, T)\n V_u = datavar(Matrix{Float64}, T)\n \n m_x = datavar(Vector{Float64}, T)\n V_x = datavar(Matrix{Float64}, T)\n \n u = randomvar(T)\n s = randomvar(T)\n x = randomvar(T)\n \n u_h_k = randomvar(T)\n s_g_k = randomvar(T)\n u_s_sum = randomvar(T)\n \n for k in 1:T\n u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])\n u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }\n s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }\n u_s_sum[k] ~ s_g_k[k] + u_h_k[k]\n s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)\n x[k] ~ MvNormal(mean = s[k], cov = Theta)\n x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal\n s_k_min = s[k]\n end\n \n return (s, )\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time t and gets T observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next T time step. \nInfer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state s_t and control u_t, i.e. p(s_tmid x_t) and p(u_tmid x_t).\nSlide: After updating its internal belief, the agent moves to the next time step and uses the inferred action u_t in the previous time step to interact with the environment. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, we create the agent through the create_agent function, which includes infer, act, slide and future functions:","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next T positions based on the current action. These two function implement the Act-Execute-Observe phase.\nThe infer function infers the policy (which is a set of actions for the next T time steps) and the agent's state using the agent internal model. This function implements the Infer phase.\nThe slide function implements the Slide phase, which moves the agent internal model to the next time step.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"# We are going to use some private functionality from ReactiveMP, \n# in the future we should expose a proper API for this\nimport RxInfer.ReactiveMP: getrecent, messageout\n\nfunction create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)\n Epsilon = fill(huge, 1, 1) # Control prior variance\n m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors\n V_u = Matrix{Float64}[ Epsilon for k=1:T ]\n\n Sigma = 1e-4*diageye(2) # Goal prior variance\n m_x = [zeros(2) for k=1:T]\n V_x = [huge*diageye(2) for k=1:T]\n V_x[end] = Sigma # Set prior to reach goal at t=T\n\n # Set initial brain state prior\n m_s_t_min = [initial_position, initial_velocity] \n V_s_t_min = tiny * diageye(2)\n \n # Set current inference results\n result = nothing\n\n # The `infer` function is the heart of the agent\n # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing\n infer = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin\n m_u[1] = [ upsilon_t ] # Register action with the generative model\n V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action\n\n m_x[1] = y_hat_t # Register observation with the generative model\n V_x[1] = tiny*diageye(2) # Clamp goal prior to observation\n\n data = Dict(:m_u => m_u, \n :V_u => V_u, \n :m_x => m_x, \n :V_x => V_x,\n :m_s_t_min => m_s_t_min,\n :V_s_t_min => V_s_t_min)\n \n model = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) \n result = inference(model = model, data = data)\n end\n \n # The `act` function returns the inferred best possible action\n act = () -> begin\n if result !== nothing\n return mode(result.posteriors[:u][2])[1]\n else\n return 0.0 # Without inference result we return some 'random' action\n end\n end\n \n # The `future` function returns the inferred future states\n future = () -> begin \n if result !== nothing \n return getindex.(mode.(result.posteriors[:s]), 1)\n else\n return zeros(T)\n end\n end\n\n # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step\n # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`\n slide = () -> begin\n (s, ) = result.returnval\n \n slide_msg_idx = 3 # This index is model dependend\n (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))\n\n m_u = circshift(m_u, -1)\n m_u[end] = [0.0]\n V_u = circshift(V_u, -1)\n V_u[end] = Epsilon\n\n m_x = circshift(m_x, -1)\n m_x[end] = x_target\n V_x = circshift(V_x, -1)\n V_x[end] = Sigma\n end\n\n return (infer, act, slide, future) \nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_agent (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now it's time to see if we can help our friends arrive at the camping site by midnight?","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(execute_ai, observe_ai) = create_world(\n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n) # Let there be a world\n\nT_ai = 50\n\n(infer_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent\n T = T_ai, \n Fa = Fa,\n Fg = Fg, \n Ff = Ff, \n engine_force_limit = engine_force_limit,\n x_target = x_target,\n initial_position = initial_position,\n initial_velocity = initial_velocity\n) \n\nN_ai = 100\n\n# Step through experimental protocol\nagent_a = Vector{Float64}(undef, N_ai) # Actions\nagent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future\nagent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations\n\nfor t=1:N_ai\n agent_a[t] = act_ai() # Invoke an action from the agent\n agent_f[t] = future_ai() # Fetch the predicted future states\n execute_ai(agent_a[t]) # The action influences hidden external states\n agent_x[t] = observe_ai() # Observe the current environmental outcome (update p)\n infer_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)\n slide_ai() # Prepare for next iteration\nend\n\nanimation_ai = @animate for i in 1:N_ai\n # pls - plot landscape\n pls = plot(valley_x, valley_y, title = \"Active inference results\", label = \"Landscape\", color = \"black\")\n pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label=\"car\")\n pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label=\"goal\") \n pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = \"Predicted future\", alpha = map(i -> 0.5 / i, 1:T_ai))\n \n # pef - plot engine force\n pef = plot(Fa.(agent_a[1:i]), title = \"Engine force (agents actions)\", xlim = (0, N_ai), ylim = (-0.05, 0.05))\n \n plot(pls, pef, size = (800, 400))\nend\n \n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_ai, \"../pics/ai-mountain-car-ai.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Voila! The car now is able to reach the camping site with a smart strategy.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now our friends can enjoy their trip at the camping site!. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Reference","page":"Active Inference Mountain car","title":"Reference","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We refer reader to the Thijs van de Laar (2019) \"Simulating active inference processes by message passing\" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) \"Deep active inference\".","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-free-energy","page":"Bethe Free Energy","title":"Bethe Free Energy implementation in RxInfer","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-factorized-model","page":"Bethe Free Energy","title":"Factorized model","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, y = (y_1 dots y_j dots y_m) and variables that can not be observed directly, also known as latent variables, x = (x_1 dots x_i dots x_n) We then define a model that factorizes over consituent smaller factors (functions), as f(yx) = prod_a f_a(y_ax_a)","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-vfe","page":"Bethe Free Energy","title":"Variational Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, Fq(haty) = mathbbE_q(x)leftlog fracq(x)f(y=haty x) right A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-variational-inference","page":"Bethe Free Energy","title":"Variational inference","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The goal of variational inference is to find a variational distibution that minimizes the VFE, q^*(x) = argmin_qinmathcalQ Fq(haty) This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-approximation","page":"Bethe Free Energy","title":"Bethe approximation","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, q(x) triangleq fracprod_a q_a(x_a)prod_i q_i(x_i)^d_i - 1 The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-bfe","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as F_Bq(haty) = sum_a U_aq_a(haty_a) - sum_a Hq_a + sum_i (d_i - 1) Hq_i The first term of the BFE specifies an average energy, U_aq_a(haty_a) = -mathbbE_q_a(x_a)leftlog f_a(y_a=haty_a x_a)right which internalizes the factors of the model. The last two terms specify entropies.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the inference and rxinference functions initializes the variational distributions of the BFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-further-reading","page":"Bethe Free Energy","title":"Further reading","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Pearl (1986) on the original foundations of Bayesian networks and belief propagation;\nYedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;\nDauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);\nSenoz et al. (2021) on constraint manipulation and message passing on FFGs.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"RxInfer.AbstractScoreObjective\nRxInfer.BetheFreeEnergy\nRxInfer.apply_diagnostic_check\nRxInfer.BetheFreeEnergyCheckNaNs\nRxInfer.BetheFreeEnergyCheckInfs","category":"page"},{"location":"library/bethe-free-energy/#RxInfer.AbstractScoreObjective","page":"Bethe Free Energy","title":"RxInfer.AbstractScoreObjective","text":"AbstractScoreObjective\n\nAbstract type for functional objectives that can be used in the score function. \n\nnote: Note\n\n\nscore is defined in the ReactiveMP package.\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergy","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergy","text":"BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)\n\nCreates Bethe Free Energy values stream when passed to the score function. \n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.apply_diagnostic_check","page":"Bethe Free Energy","title":"RxInfer.apply_diagnostic_check","text":"apply_diagnostic_check(check, context, stream)\n\nThis function applies a check to the stream. Accepts optional context object for custom error messages.\n\n\n\n\n\n","category":"function"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckNaNs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckNaNs","text":"BetheFreeEnergyCheckNaNs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return NaNs. Throws an error if finds NaN. \n\nSee also: BetheFreeEnergyCheckInfs\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckInfs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckInfs","text":"BetheFreeEnergyCheckInfs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return Infs. Throws an error if finds Inf. \n\nSee also: BetheFreeEnergyCheckNaNs\n\n\n\n\n\n","category":"type"},{"location":"manuals/background/#intro-background-variational-inference","page":"Background: variational inference","title":"Background: variational inference","text":"","category":"section"}] +} diff --git a/v2.15.0/siteinfo.js b/v2.15.0/siteinfo.js new file mode 100644 index 000000000..4969aa8ad --- /dev/null +++ b/v2.15.0/siteinfo.js @@ -0,0 +1 @@ +var DOCUMENTER_CURRENT_VERSION = "v2.15.0"; diff --git a/v2.16 b/v2.16 new file mode 120000 index 000000000..b71174af3 --- /dev/null +++ b/v2.16 @@ -0,0 +1 @@ +v2.16.2 \ No newline at end of file diff --git a/v2.16.0/.documenter-siteinfo.json b/v2.16.0/.documenter-siteinfo.json new file mode 100644 index 000000000..67f137289 --- /dev/null +++ b/v2.16.0/.documenter-siteinfo.json @@ -0,0 +1 @@ +{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-11T14:50:56","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/v2.16.0/assets/biglogo-blacktheme.svg b/v2.16.0/assets/biglogo-blacktheme.svg new file mode 100644 index 000000000..101ebb89d --- /dev/null +++ b/v2.16.0/assets/biglogo-blacktheme.svg @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 27.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) --> +<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" + viewBox="0 0 642.5 213.6" style="enable-background:new 0 0 642.5 213.6;" xml:space="preserve"> +<style type="text/css"> + .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFFFFF;stroke-miterlimit:10;} + .st1{fill:#389826;} + .st2{fill:#9558B2;} + .st3{fill:#FFFFFF;stroke:#FFFFFF;stroke-miterlimit:10;} + .st4{fill:#CB3C33;} + .st5{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFE9E9;stroke-miterlimit:10;} + .st6{fill-rule:evenodd;clip-rule:evenodd;fill:#4063D8;stroke:#FFFFFF;stroke-miterlimit:10;} +</style> +<g id="Слой_2"> + <g id="Layer_1_00000116955105323099935610000000039006590443086520_"> + <path class="st0" d="M66.6,114.5h63c6.7-0.3,12-5.8,12-12.5c0-14.1,0.3-27.6,0.3-41.5c0-6.3,5.1-11.4,11.3-11.4h40.1 + c6.3,0,11.4,5.1,11.4,11.4v40.1c0,6.3-5.1,11.4-11.4,11.4h-35.1c-6.2,0.9-10.8,6.2-10.8,12.4v70.9c0,9.8-8,17.8-17.9,17.8H66.6 + c-9.8,0-17.8-8-17.8-17.8V130c0-6.8-5.5-12.2-12.3-12.2H9.2c-4.8,0-8.7-3.9-8.7-8.7V78.2c0-4.8,3.9-8.7,8.7-8.7h28.7 + c6,0,10.8-4.8,10.8-10.8V13c0-6.9,5.6-12.5,12.5-12.5h44c6.9,0,12.5,5.6,12.5,12.5v44c0,6.9-5.6,12.5-12.5,12.5H59.6 + c-6,0-10.8,4.8-10.8,10.8v22c0,6.7,5.5,12.2,12.2,12.2H66.6z"/> + <rect x="62" y="13.8" class="st1" width="42.3" height="42.3"/> + <rect x="155.2" y="62.4" class="st2" width="36.2" height="36.2"/> + <rect x="13.7" y="82.8" class="st3" width="21.7" height="21.7"/> + <rect x="62" y="127.7" class="st4" width="72" height="72"/> + <path class="st5" d="M213.7,130.1c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.1-9.6,10.4-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.1,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C223.6,131.6,219,130.1,213.7,130.1z"/> + <polygon class="st0" points="281.9,165.8 306.4,130.8 294,130.8 276.2,156.7 260.4,130.8 232.2,130.8 259.8,175.5 234.7,211.6 + 247.2,211.6 265.4,184.8 281.9,211.6 310,211.6 "/> + <polygon class="st0" points="342.1,211.6 342.1,130 315.8,134.3 315.8,211.6 "/> + <path class="st6" d="M329.3,124.6c3.7,0.1,7.2-1.3,9.8-3.9c2.6-2.7,4-6.3,3.9-10.1c0.1-3.7-1.3-7.3-3.9-9.9s-6.1-4.1-9.8-4 + c-3.9-0.1-7.6,1.3-10.4,4c-2.7,2.6-4.2,6.2-4.1,9.9c-0.1,3.8,1.4,7.5,4.1,10.1C321.7,123.3,325.6,124.8,329.3,124.6z"/> + <path class="st0" d="M405.2,129.3c-5.7-0.1-11.3,1.4-16.3,4.1c-4.8,2.5-8.8,6.3-11.7,10.9V130l-26.3,4.3v77.3h26.3v-55.4 + c3.6-8.1,10.4-13.3,17.6-13.3c6.6,0,11.5,5.2,11.5,12.5v56.2h26.3v-55.7c0.2-7.2-2.6-14.1-7.8-19 + C419.6,131.9,413.1,129.4,405.2,129.3z"/> + <path class="st0" d="M479.3,93.6c-9.7,0-17.8,2.8-24.3,8.3s-9.8,12.5-9.8,20.7v8.2h-9.4v8.7h9.4v72.1h26.3v-72.1h16.4v-8.7h-16.4 + v-10.3c-0.2-4.3,1.3-8.5,4.1-11.8c2.7-3.1,6.6-4.9,10.6-5c-1.4,1.9-2.1,4.2-2.1,6.6c0,2.9,1.2,5.7,3.4,7.7 + c2.2,2.1,5.1,3.3,8.1,3.2c2.8,0.1,5.6-1.1,7.6-3.1s3.2-4.8,3.1-7.7c0-4.7-2.6-8.7-7.7-11.9S487,93.6,479.3,93.6z"/> + <path class="st0" d="M527.9,129.4v8.6l0,0V129.4L527.9,129.4z"/> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M527.3,129.3c-11.7,0.2-21.6,4.2-29.7,12c-8.3,7.9-12.6,17.9-12.6,29.8c-0.2,11.4,4.6,22.4,13.2,29.9 + c7.9,7.3,17.9,11.3,29.8,12v-0.1c1.2,0.1,2.5,0.1,3.7,0.1c9.9,0,18.4-2.1,25.4-6.4s10.5-9.5,10.5-15.7c0.1-3-1.1-6-3.2-8.2 + c-2-2.2-4.9-3.3-7.9-3.3c-3.2-0.1-6.2,1.1-8.5,3.3c-2.3,2.1-3.6,5.1-3.6,8.2c-0.1,3.9,1.9,7.6,5.4,9.5c-3.3,1.5-6.9,2.3-10.5,2.2 + c-3.9,0.1-7.8-0.6-11.4-2l0,0c-9.9-3.9-15.2-13.8-16-29.5h55.9c0-12-3.8-22-11.4-29.9c-7.6-8-17.2-11.9-28.8-11.9L527.3,129.3 + M527.9,138c8.5,0.1,14.2,9.1,15.1,24.4h-15.7l0,0h-15.1c0.6-7.3,2.4-13.2,5.3-17.7C520.3,140.5,523.8,138.2,527.9,138L527.9,138" + /> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M623.6,129.4c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.2-9.6,10.3-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.2,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C633.4,130.9,629,129.4,623.6,129.4z"/> + </g> +</g> +<g id="Layer_2_00000036966862148631286250000015780344526604021166_"> +</g> +</svg> diff --git a/v2.16.0/assets/biglogo.svg b/v2.16.0/assets/biglogo.svg new file mode 100644 index 000000000..b9f3d9f8e --- /dev/null +++ b/v2.16.0/assets/biglogo.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 641.51 212.57"><defs><style>.cls-1{fill:#333;}.cls-1,.cls-6{fill-rule:evenodd;}.cls-2{fill:#389826;}.cls-3{fill:#9558b2;}.cls-4{fill:#fff;}.cls-5{fill:#cb3c33;}.cls-6{fill:#4063d8;}</style></defs><title>1 \ No newline at end of file diff --git a/v2.16.0/assets/documenter.js b/v2.16.0/assets/documenter.js new file mode 100644 index 000000000..f5311607b --- /dev/null +++ b/v2.16.0/assets/documenter.js @@ -0,0 +1,889 @@ +// Generated by Documenter.jl +requirejs.config({ + paths: { + 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', + 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', + 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', + 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', + 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', + 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', + 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', + 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min', + 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min', + 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia-repl.min', + }, + shim: { + "highlight-julia": { + "deps": [ + "highlight" + ] + }, + "katex-auto-render": { + "deps": [ + "katex" + ] + }, + "headroom-jquery": { + "deps": [ + "jquery", + "headroom" + ] + }, + "highlight-julia-repl": { + "deps": [ + "highlight" + ] + } +} +}); +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'katex', 'katex-auto-render'], function($, katex, renderMathInElement) { +$(document).ready(function() { + renderMathInElement( + document.body, + { + "delimiters": [ + { + "left": "$", + "right": "$", + "display": false + }, + { + "left": "$$", + "right": "$$", + "display": true + }, + { + "left": "\\[", + "right": "\\]", + "display": true + } + ] +} + + ); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'highlight', 'highlight-julia', 'highlight-julia-repl'], function($) { +$(document).ready(function() { + hljs.highlightAll(); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let timer = 0; +var isExpanded = true; + +$(document).on("click", ".docstring header", function () { + let articleToggleTitle = "Expand docstring"; + + debounce(() => { + if ($(this).siblings("section").is(":visible")) { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + } else { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + articleToggleTitle = "Collapse docstring"; + } + + $(this) + .find(".docstring-article-toggle-button") + .prop("title", articleToggleTitle); + $(this).siblings("section").slideToggle(); + }); +}); + +$(document).on("click", ".docs-article-toggle-button", function () { + let articleToggleTitle = "Expand docstring"; + let navArticleToggleTitle = "Expand all docstrings"; + + debounce(() => { + if (isExpanded) { + $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + + isExpanded = false; + + $(".docstring section").slideUp(); + } else { + $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + isExpanded = true; + articleToggleTitle = "Collapse docstring"; + navArticleToggleTitle = "Collapse all docstrings"; + + $(".docstring section").slideDown(); + } + + $(this).prop("title", navArticleToggleTitle); + $(".docstring-article-toggle-button").prop("title", articleToggleTitle); + }); +}); + +function debounce(callback, timeout = 300) { + if (Date.now() - timer > timeout) { + callback(); + } + + clearTimeout(timer); + + timer = Date.now(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require([], function() { +function addCopyButtonCallbacks() { + for (const el of document.getElementsByTagName("pre")) { + const button = document.createElement("button"); + button.classList.add("copy-button", "fa-solid", "fa-copy"); + button.setAttribute("aria-label", "Copy this code block"); + button.setAttribute("title", "Copy"); + + el.appendChild(button); + + const success = function () { + button.classList.add("success", "fa-check"); + button.classList.remove("fa-copy"); + }; + + const failure = function () { + button.classList.add("error", "fa-xmark"); + button.classList.remove("fa-copy"); + }; + + button.addEventListener("click", function () { + copyToClipboard(el.innerText).then(success, failure); + + setTimeout(function () { + button.classList.add("fa-copy"); + button.classList.remove("success", "fa-check", "fa-xmark"); + }, 5000); + }); + } +} + +function copyToClipboard(text) { + // clipboard API is only available in secure contexts + if (window.navigator && window.navigator.clipboard) { + return window.navigator.clipboard.writeText(text); + } else { + return new Promise(function (resolve, reject) { + try { + const el = document.createElement("textarea"); + el.textContent = text; + el.style.position = "fixed"; + el.style.opacity = 0; + document.body.appendChild(el); + el.select(); + document.execCommand("copy"); + + resolve(); + } catch (err) { + reject(err); + } finally { + document.body.removeChild(el); + } + }); + } +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addCopyButtonCallbacks); +} else { + addCopyButtonCallbacks(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'headroom', 'headroom-jquery'], function($, Headroom) { + +// Manages the top navigation bar (hides it when the user starts scrolling down on the +// mobile). +window.Headroom = Headroom; // work around buggy module loading? +$(document).ready(function () { + $("#documenter .docs-navbar").headroom({ + tolerance: { up: 10, down: 10 }, + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'minisearch'], function($, minisearch) { + +// In general, most search related things will have "search" as a prefix. +// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +let results = []; +let timer = undefined; + +let data = documenterSearchIndex["docs"].map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; +}); + +// list below is the lunr 2.1.3 list minus the intersect with names(Base) +// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) +// ideally we'd just filter the original list but it's not available as a variable +const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", +]); + +let index = new minisearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification + tokenize: (string) => string.split(/[\s\-\.]+/), + // options which will be applied during the search + searchOptions: { + boost: { title: 100 }, + fuzzy: 2, + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + tokenize: (string) => string.split(/[\s\-\.]+/), + }, +}); + +index.addAll(data); + +let filters = [...new Set(data.map((x) => x.category))]; +var modal_filters = make_modal_body_filters(filters); +var filter_results = []; + +$(document).on("keyup", ".documenter-search-input", function (event) { + // Adding a debounce to prevent disruptions from super-speed typing! + debounce(() => update_search(filter_results), 300); +}); + +$(document).on("click", ".search-filter", function () { + if ($(this).hasClass("search-filter-selected")) { + $(this).removeClass("search-filter-selected"); + } else { + $(this).addClass("search-filter-selected"); + } + + // Adding a debounce to prevent disruptions from crazy clicking! + debounce(() => get_filters(), 300); +}); + +/** + * A debounce function, takes a function and an optional timeout in milliseconds + * + * @function callback + * @param {number} timeout + */ +function debounce(callback, timeout = 300) { + clearTimeout(timer); + timer = setTimeout(callback, timeout); +} + +/** + * Make/Update the search component + * + * @param {string[]} selected_filters + */ +function update_search(selected_filters = []) { + let initial_search_body = ` +
Type something to get started!
+ `; + + let querystring = $(".documenter-search-input").val(); + + if (querystring.trim()) { + results = index.search(querystring, { + filter: (result) => { + // Filtering results + if (selected_filters.length === 0) { + return result.score >= 1; + } else { + return ( + result.score >= 1 && selected_filters.includes(result.category) + ); + } + }, + }); + + let search_result_container = ``; + let search_divider = `
`; + + if (results.length) { + let links = []; + let count = 0; + let search_results = ""; + + results.forEach(function (result) { + if (result.location) { + // Checking for duplication of results for the same page + if (!links.includes(result.location)) { + search_results += make_search_result(result, querystring); + count++; + } + + links.push(result.location); + } + }); + + let result_count = `
${count} result(s)
`; + + search_result_container = ` +
+ ${modal_filters} + ${search_divider} + ${result_count} +
+ ${search_results} +
+
+ `; + } else { + search_result_container = ` +
+ ${modal_filters} + ${search_divider} +
0 result(s)
+
+
No result found!
+ `; + } + + if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").removeClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(search_result_container); + } else { + filter_results = []; + modal_filters = make_modal_body_filters(filters, filter_results); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(initial_search_body); + } +} + +/** + * Make the modal filter html + * + * @param {string[]} filters + * @param {string[]} selected_filters + * @returns string + */ +function make_modal_body_filters(filters, selected_filters = []) { + let str = ``; + + filters.forEach((val) => { + if (selected_filters.includes(val)) { + str += `${val}`; + } else { + str += `${val}`; + } + }); + + let filter_html = ` +
+ Filters: + ${str} +
+ `; + + return filter_html; +} + +/** + * Make the result component given a minisearch result data object and the value of the search input as queryString. + * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ +function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } + + let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${result.title}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; +} + +/** + * Get selected filters, remake the filter html and lastly update the search modal + */ +function get_filters() { + let ele = $(".search-filters .search-filter-selected").get(); + filter_results = ele.map((x) => $(x).text().toLowerCase()); + modal_filters = make_modal_body_filters(filters, filter_results); + update_search(filter_results); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Modal settings dialog +$(document).ready(function () { + var settings = $("#documenter-settings"); + $("#documenter-settings-button").click(function () { + settings.toggleClass("is-active"); + }); + // Close the dialog if X is clicked + $("#documenter-settings button.delete").click(function () { + settings.removeClass("is-active"); + }); + // Close dialog if ESC is pressed + $(document).keyup(function (e) { + if (e.keyCode == 27) settings.removeClass("is-active"); + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let search_modal_header = ` +
+
+

+ + + + +

+
+
+ +
+
+`; + +let initial_search_body = ` +
Type something to get started!
+`; + +let search_modal_footer = ` +
+ + Ctrl + + / to search + + esc to close +
+`; + +$(document.body).append( + ` + + ` +); + +document.querySelector(".docs-search-query").addEventListener("click", () => { + openModal(); +}); + +document.querySelector(".close-search-modal").addEventListener("click", () => { + closeModal(); +}); + +$(document).on("click", ".search-result-link", function () { + closeModal(); +}); + +document.addEventListener("keydown", (event) => { + if ((event.ctrlKey || event.metaKey) && event.key === "/") { + openModal(); + } else if (event.key === "Escape") { + closeModal(); + } + + return false; +}); + +// Functions to open and close a modal +function openModal() { + let searchModal = document.querySelector("#search-modal"); + + searchModal.classList.add("is-active"); + document.querySelector(".documenter-search-input").focus(); +} + +function closeModal() { + let searchModal = document.querySelector("#search-modal"); + let initial_search_body = ` +
Type something to get started!
+ `; + + searchModal.classList.remove("is-active"); + document.querySelector(".documenter-search-input").blur(); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".documenter-search-input").val(""); + $(".search-modal-card-body").html(initial_search_body); +} + +document + .querySelector("#search-modal .modal-background") + .addEventListener("click", () => { + closeModal(); + }); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Manages the showing and hiding of the sidebar. +$(document).ready(function () { + var sidebar = $("#documenter > .docs-sidebar"); + var sidebar_button = $("#documenter-sidebar-button"); + sidebar_button.click(function (ev) { + ev.preventDefault(); + sidebar.toggleClass("visible"); + if (sidebar.hasClass("visible")) { + // Makes sure that the current menu item is visible in the sidebar. + $("#documenter .docs-menu a.is-active").focus(); + } + }); + $("#documenter > .docs-main").bind("click", function (ev) { + if ($(ev.target).is(sidebar_button)) { + return; + } + if (sidebar.hasClass("visible")) { + sidebar.removeClass("visible"); + } + }); +}); + +// Resizes the package name / sitename in the sidebar if it is too wide. +// Inspired by: https://github.com/davatron5000/FitText.js +$(document).ready(function () { + e = $("#documenter .docs-autofit"); + function resize() { + var L = parseInt(e.css("max-width"), 10); + var L0 = e.width(); + if (L0 > L) { + var h0 = parseInt(e.css("font-size"), 10); + e.css("font-size", (L * h0) / L0); + // TODO: make sure it survives resizes? + } + } + // call once and then register events + resize(); + $(window).resize(resize); + $(window).on("orientationchange", resize); +}); + +// Scroll the navigation bar to the currently selected menu item +$(document).ready(function () { + var sidebar = $("#documenter .docs-menu").get(0); + var active = $("#documenter .docs-menu .is-active").get(0); + if (typeof active !== "undefined") { + sidebar.scrollTop = active.offsetTop - sidebar.offsetTop - 15; + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Theme picker setup +$(document).ready(function () { + // onchange callback + $("#documenter-themepicker").change(function themepick_callback(ev) { + var themename = $("#documenter-themepicker option:selected").attr("value"); + if (themename === "auto") { + // set_theme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'); + window.localStorage.removeItem("documenter-theme"); + } else { + // set_theme(themename); + window.localStorage.setItem("documenter-theme", themename); + } + // We re-use the global function from themeswap.js to actually do the swapping. + set_theme_from_local_storage(); + }); + + // Make sure that the themepicker displays the correct theme when the theme is retrieved + // from localStorage + if (typeof window.localStorage !== "undefined") { + var theme = window.localStorage.getItem("documenter-theme"); + if (theme !== null) { + $("#documenter-themepicker option").each(function (i, e) { + e.selected = e.value === theme; + }); + } + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// update the version selector with info from the siteinfo.js and ../versions.js files +$(document).ready(function () { + // If the version selector is disabled with DOCUMENTER_VERSION_SELECTOR_DISABLED in the + // siteinfo.js file, we just return immediately and not display the version selector. + if ( + typeof DOCUMENTER_VERSION_SELECTOR_DISABLED === "boolean" && + DOCUMENTER_VERSION_SELECTOR_DISABLED + ) { + return; + } + + var version_selector = $("#documenter .docs-version-selector"); + var version_selector_select = $("#documenter .docs-version-selector select"); + + version_selector_select.change(function (x) { + target_href = version_selector_select + .children("option:selected") + .get(0).value; + window.location.href = target_href; + }); + + // add the current version to the selector based on siteinfo.js, but only if the selector is empty + if ( + typeof DOCUMENTER_CURRENT_VERSION !== "undefined" && + $("#version-selector > option").length == 0 + ) { + var option = $( + "" + ); + version_selector_select.append(option); + } + + if (typeof DOC_VERSIONS !== "undefined") { + var existing_versions = version_selector_select.children("option"); + var existing_versions_texts = existing_versions.map(function (i, x) { + return x.text; + }); + DOC_VERSIONS.forEach(function (each) { + var version_url = documenterBaseURL + "/../" + each + "/"; + var existing_id = $.inArray(each, existing_versions_texts); + // if not already in the version selector, add it as a new option, + // otherwise update the old option with the URL and enable it + if (existing_id == -1) { + var option = $( + "" + ); + version_selector_select.append(option); + } else { + var option = existing_versions[existing_id]; + option.value = version_url; + option.disabled = false; + } + }); + } + + // only show the version selector if the selector has been populated + if (version_selector_select.children("option").length > 0) { + version_selector.toggleClass("visible"); + } +}); + +}) diff --git a/v2.16.0/assets/examples/Active Inference Mountain car_4_1.png b/v2.16.0/assets/examples/Active Inference Mountain car_4_1.png new file mode 100644 index 000000000..9394d1730 Binary files /dev/null and b/v2.16.0/assets/examples/Active Inference Mountain car_4_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_12_1.png b/v2.16.0/assets/examples/Autoregressive Models_12_1.png new file mode 100644 index 000000000..5f7b543d9 Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_12_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_13_1.png b/v2.16.0/assets/examples/Autoregressive Models_13_1.png new file mode 100644 index 000000000..99416e777 Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_13_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_14_1.png b/v2.16.0/assets/examples/Autoregressive Models_14_1.png new file mode 100644 index 000000000..e4b52db2e Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_14_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_24_1.png b/v2.16.0/assets/examples/Autoregressive Models_24_1.png new file mode 100644 index 000000000..92d942e95 Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_24_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_32_1.png b/v2.16.0/assets/examples/Autoregressive Models_32_1.png new file mode 100644 index 000000000..9b30d0046 Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_32_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_36_1.png b/v2.16.0/assets/examples/Autoregressive Models_36_1.png new file mode 100644 index 000000000..047100331 Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_36_1.png differ diff --git a/v2.16.0/assets/examples/Autoregressive Models_6_1.png b/v2.16.0/assets/examples/Autoregressive Models_6_1.png new file mode 100644 index 000000000..309eadff5 Binary files /dev/null and b/v2.16.0/assets/examples/Autoregressive Models_6_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_10_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_10_1.png new file mode 100644 index 000000000..4ecb12eef Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_10_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_12_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_12_1.png new file mode 100644 index 000000000..21f2cf9b8 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_12_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_14_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_14_1.png new file mode 100644 index 000000000..d35fb5850 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_14_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_15_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_15_1.png new file mode 100644 index 000000000..8068d76e2 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_15_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_16_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_16_1.png new file mode 100644 index 000000000..2dd3fcb12 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_16_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_17_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_17_1.png new file mode 100644 index 000000000..ddcc56f62 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_17_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_18_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_18_1.png new file mode 100644 index 000000000..e986a2b1a Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_18_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_21_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_21_1.png new file mode 100644 index 000000000..157bce417 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_21_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_24_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_24_1.png new file mode 100644 index 000000000..35e9d9591 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_24_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_25_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_25_1.png new file mode 100644 index 000000000..da8387995 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_25_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_26_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_26_1.png new file mode 100644 index 000000000..0b3299f1c Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_26_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_27_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_27_1.png new file mode 100644 index 000000000..dc2785db5 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_27_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_34_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_34_1.png new file mode 100644 index 000000000..e935ce86c Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_34_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_40_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_40_1.png new file mode 100644 index 000000000..a7f23a09f Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_40_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_42_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_42_1.png new file mode 100644 index 000000000..3249d9b3c Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_42_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_4_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_4_1.png new file mode 100644 index 000000000..3851d2ea5 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_4_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_51_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_51_1.png new file mode 100644 index 000000000..df1ae996a Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_51_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_54_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_54_1.png new file mode 100644 index 000000000..8da279955 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_54_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_55_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_55_1.png new file mode 100644 index 000000000..ca615bf2c Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_55_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_7_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_7_1.png new file mode 100644 index 000000000..564b04161 Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_7_1.png differ diff --git a/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_8_1.png b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_8_1.png new file mode 100644 index 000000000..b86dc84cd Binary files /dev/null and b/v2.16.0/assets/examples/Bayesian Linear Regression Tutorial_8_1.png differ diff --git a/v2.16.0/assets/examples/Chance Constraints_11_1.png b/v2.16.0/assets/examples/Chance Constraints_11_1.png new file mode 100644 index 000000000..b7b9be536 Binary files /dev/null and b/v2.16.0/assets/examples/Chance Constraints_11_1.png differ diff --git a/v2.16.0/assets/examples/Coin Toss Model_7_1.png b/v2.16.0/assets/examples/Coin Toss Model_7_1.png new file mode 100644 index 000000000..180821d61 Binary files /dev/null and b/v2.16.0/assets/examples/Coin Toss Model_7_1.png differ diff --git a/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png b/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png new file mode 100644 index 000000000..d90df26c0 Binary files /dev/null and b/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png differ diff --git a/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png b/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png new file mode 100644 index 000000000..14f524963 Binary files /dev/null and b/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png differ diff --git a/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png b/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png new file mode 100644 index 000000000..2e19804fb Binary files /dev/null and b/v2.16.0/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png differ diff --git a/v2.16.0/assets/examples/GP Regression by SSM_10_1.png b/v2.16.0/assets/examples/GP Regression by SSM_10_1.png new file mode 100644 index 000000000..be25d53d3 Binary files /dev/null and b/v2.16.0/assets/examples/GP Regression by SSM_10_1.png differ diff --git a/v2.16.0/assets/examples/GP Regression by SSM_5_1.png b/v2.16.0/assets/examples/GP Regression by SSM_5_1.png new file mode 100644 index 000000000..3246e6256 Binary files /dev/null and b/v2.16.0/assets/examples/GP Regression by SSM_5_1.png differ diff --git a/v2.16.0/assets/examples/Gamma Mixture_10_1.png b/v2.16.0/assets/examples/Gamma Mixture_10_1.png new file mode 100644 index 000000000..bd8ce343b Binary files /dev/null and b/v2.16.0/assets/examples/Gamma Mixture_10_1.png differ diff --git a/v2.16.0/assets/examples/Gaussian Mixture_12_1.png b/v2.16.0/assets/examples/Gaussian Mixture_12_1.png new file mode 100644 index 000000000..fc21b9942 Binary files /dev/null and b/v2.16.0/assets/examples/Gaussian Mixture_12_1.png differ diff --git a/v2.16.0/assets/examples/Gaussian Mixture_4_1.png b/v2.16.0/assets/examples/Gaussian Mixture_4_1.png new file mode 100644 index 000000000..aedf37236 Binary files /dev/null and b/v2.16.0/assets/examples/Gaussian Mixture_4_1.png differ diff --git a/v2.16.0/assets/examples/Gaussian Mixture_7_1.png b/v2.16.0/assets/examples/Gaussian Mixture_7_1.png new file mode 100644 index 000000000..338fe2092 Binary files /dev/null and b/v2.16.0/assets/examples/Gaussian Mixture_7_1.png differ diff --git a/v2.16.0/assets/examples/Gaussian Mixture_9_1.png b/v2.16.0/assets/examples/Gaussian Mixture_9_1.png new file mode 100644 index 000000000..64adeef14 Binary files /dev/null and b/v2.16.0/assets/examples/Gaussian Mixture_9_1.png differ diff --git a/v2.16.0/assets/examples/Global Parameter Optimisation_14_1.png b/v2.16.0/assets/examples/Global Parameter Optimisation_14_1.png new file mode 100644 index 000000000..70f61d1cf Binary files /dev/null and b/v2.16.0/assets/examples/Global Parameter Optimisation_14_1.png differ diff --git a/v2.16.0/assets/examples/Global Parameter Optimisation_18_1.png b/v2.16.0/assets/examples/Global Parameter Optimisation_18_1.png new file mode 100644 index 000000000..eac50a682 Binary files /dev/null and b/v2.16.0/assets/examples/Global Parameter Optimisation_18_1.png differ diff --git a/v2.16.0/assets/examples/Global Parameter Optimisation_22_1.png b/v2.16.0/assets/examples/Global Parameter Optimisation_22_1.png new file mode 100644 index 000000000..c24630442 Binary files /dev/null and b/v2.16.0/assets/examples/Global Parameter Optimisation_22_1.png differ diff --git a/v2.16.0/assets/examples/Global Parameter Optimisation_28_1.png b/v2.16.0/assets/examples/Global Parameter Optimisation_28_1.png new file mode 100644 index 000000000..0eb0740f8 Binary files /dev/null and b/v2.16.0/assets/examples/Global Parameter Optimisation_28_1.png differ diff --git a/v2.16.0/assets/examples/Global Parameter Optimisation_32_1.png b/v2.16.0/assets/examples/Global Parameter Optimisation_32_1.png new file mode 100644 index 000000000..cf55c8da0 Binary files /dev/null and b/v2.16.0/assets/examples/Global Parameter Optimisation_32_1.png differ diff --git a/v2.16.0/assets/examples/Global Parameter Optimisation_35_1.png b/v2.16.0/assets/examples/Global Parameter Optimisation_35_1.png new file mode 100644 index 000000000..fddb20942 Binary files /dev/null and b/v2.16.0/assets/examples/Global Parameter Optimisation_35_1.png differ diff --git a/v2.16.0/assets/examples/Hidden Markov Model_4_1.png b/v2.16.0/assets/examples/Hidden Markov Model_4_1.png new file mode 100644 index 000000000..a15a96215 Binary files /dev/null and b/v2.16.0/assets/examples/Hidden Markov Model_4_1.png differ diff --git a/v2.16.0/assets/examples/Hidden Markov Model_9_1.png b/v2.16.0/assets/examples/Hidden Markov Model_9_1.png new file mode 100644 index 000000000..32d9bbc46 Binary files /dev/null and b/v2.16.0/assets/examples/Hidden Markov Model_9_1.png differ diff --git a/v2.16.0/assets/examples/Hierarchical Gaussian Filter_10_1.png b/v2.16.0/assets/examples/Hierarchical Gaussian Filter_10_1.png new file mode 100644 index 000000000..6a3b9c9dc Binary files /dev/null and b/v2.16.0/assets/examples/Hierarchical Gaussian Filter_10_1.png differ diff --git a/v2.16.0/assets/examples/Hierarchical Gaussian Filter_5_1.png b/v2.16.0/assets/examples/Hierarchical Gaussian Filter_5_1.png new file mode 100644 index 000000000..2d74bff5a Binary files /dev/null and b/v2.16.0/assets/examples/Hierarchical Gaussian Filter_5_1.png differ diff --git a/v2.16.0/assets/examples/Hierarchical Gaussian Filter_9_1.png b/v2.16.0/assets/examples/Hierarchical Gaussian Filter_9_1.png new file mode 100644 index 000000000..9821f6bc9 Binary files /dev/null and b/v2.16.0/assets/examples/Hierarchical Gaussian Filter_9_1.png differ diff --git a/v2.16.0/assets/examples/Infinite Data Stream_11_1.png b/v2.16.0/assets/examples/Infinite Data Stream_11_1.png new file mode 100644 index 000000000..8a409e320 Binary files /dev/null and b/v2.16.0/assets/examples/Infinite Data Stream_11_1.png differ diff --git a/v2.16.0/assets/examples/Invertible Neural Network Tutorial_10_1.png b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_10_1.png new file mode 100644 index 000000000..009e76bec Binary files /dev/null and b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_10_1.png differ diff --git a/v2.16.0/assets/examples/Invertible Neural Network Tutorial_14_1.png b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_14_1.png new file mode 100644 index 000000000..95edfacc0 Binary files /dev/null and b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_14_1.png differ diff --git a/v2.16.0/assets/examples/Invertible Neural Network Tutorial_15_1.png b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_15_1.png new file mode 100644 index 000000000..ab077a912 Binary files /dev/null and b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_15_1.png differ diff --git a/v2.16.0/assets/examples/Invertible Neural Network Tutorial_17_1.png b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_17_1.png new file mode 100644 index 000000000..201b882c0 Binary files /dev/null and b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_17_1.png differ diff --git a/v2.16.0/assets/examples/Invertible Neural Network Tutorial_23_1.png b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_23_1.png new file mode 100644 index 000000000..a639d283d Binary files /dev/null and b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_23_1.png differ diff --git a/v2.16.0/assets/examples/Invertible Neural Network Tutorial_24_1.png b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_24_1.png new file mode 100644 index 000000000..b38e5ab4e Binary files /dev/null and b/v2.16.0/assets/examples/Invertible Neural Network Tutorial_24_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_10_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_10_1.png new file mode 100644 index 000000000..404cd2073 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_10_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_15_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_15_1.png new file mode 100644 index 000000000..387f83e00 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_15_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_20_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_20_1.png new file mode 100644 index 000000000..0332168c8 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_20_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_23_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_23_1.png new file mode 100644 index 000000000..3997d6305 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_23_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_25_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_25_1.png new file mode 100644 index 000000000..baae896e0 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_25_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_30_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_30_1.png new file mode 100644 index 000000000..0ca63d89e Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_30_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_33_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_33_1.png new file mode 100644 index 000000000..230f9e497 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_33_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_39_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_39_1.png new file mode 100644 index 000000000..f69576333 Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_39_1.png differ diff --git a/v2.16.0/assets/examples/Kalman filtering and smoothing_6_1.png b/v2.16.0/assets/examples/Kalman filtering and smoothing_6_1.png new file mode 100644 index 000000000..868c31a7a Binary files /dev/null and b/v2.16.0/assets/examples/Kalman filtering and smoothing_6_1.png differ diff --git a/v2.16.0/assets/examples/Nonlinear Sensor Fusion_12_1.png b/v2.16.0/assets/examples/Nonlinear Sensor Fusion_12_1.png new file mode 100644 index 000000000..b2722f776 Binary files /dev/null and b/v2.16.0/assets/examples/Nonlinear Sensor Fusion_12_1.png differ diff --git a/v2.16.0/assets/examples/Nonlinear Sensor Fusion_17_1.png b/v2.16.0/assets/examples/Nonlinear Sensor Fusion_17_1.png new file mode 100644 index 000000000..4d1e2bd3c Binary files /dev/null and b/v2.16.0/assets/examples/Nonlinear Sensor Fusion_17_1.png differ diff --git a/v2.16.0/assets/examples/Nonlinear Sensor Fusion_4_1.png b/v2.16.0/assets/examples/Nonlinear Sensor Fusion_4_1.png new file mode 100644 index 000000000..6be9531bf Binary files /dev/null and b/v2.16.0/assets/examples/Nonlinear Sensor Fusion_4_1.png differ diff --git a/v2.16.0/assets/examples/Predicting Bike Rental Demand_17_1.png b/v2.16.0/assets/examples/Predicting Bike Rental Demand_17_1.png new file mode 100644 index 000000000..49ebabbfb Binary files /dev/null and b/v2.16.0/assets/examples/Predicting Bike Rental Demand_17_1.png differ diff --git a/v2.16.0/assets/examples/Predicting Bike Rental Demand_18_1.png b/v2.16.0/assets/examples/Predicting Bike Rental Demand_18_1.png new file mode 100644 index 000000000..ed7f08607 Binary files /dev/null and b/v2.16.0/assets/examples/Predicting Bike Rental Demand_18_1.png differ diff --git a/v2.16.0/assets/examples/Probit Model (EP)_6_1.png b/v2.16.0/assets/examples/Probit Model (EP)_6_1.png new file mode 100644 index 000000000..b9b15d04b Binary files /dev/null and b/v2.16.0/assets/examples/Probit Model (EP)_6_1.png differ diff --git a/v2.16.0/assets/examples/Probit Model (EP)_9_1.png b/v2.16.0/assets/examples/Probit Model (EP)_9_1.png new file mode 100644 index 000000000..baf1f1c80 Binary files /dev/null and b/v2.16.0/assets/examples/Probit Model (EP)_9_1.png differ diff --git a/v2.16.0/assets/examples/RTS vs BIFM Smoothing_11_1.png b/v2.16.0/assets/examples/RTS vs BIFM Smoothing_11_1.png new file mode 100644 index 000000000..6b4fff75a Binary files /dev/null and b/v2.16.0/assets/examples/RTS vs BIFM Smoothing_11_1.png differ diff --git a/v2.16.0/assets/examples/RTS vs BIFM Smoothing_12_1.png b/v2.16.0/assets/examples/RTS vs BIFM Smoothing_12_1.png new file mode 100644 index 000000000..73181f1e1 Binary files /dev/null and b/v2.16.0/assets/examples/RTS vs BIFM Smoothing_12_1.png differ diff --git a/v2.16.0/assets/examples/RTS vs BIFM Smoothing_5_1.png b/v2.16.0/assets/examples/RTS vs BIFM Smoothing_5_1.png new file mode 100644 index 000000000..5378389dd Binary files /dev/null and b/v2.16.0/assets/examples/RTS vs BIFM Smoothing_5_1.png differ diff --git a/v2.16.0/assets/examples/Simple Nonlinear Node_14_1.png b/v2.16.0/assets/examples/Simple Nonlinear Node_14_1.png new file mode 100644 index 000000000..c1344831f Binary files /dev/null and b/v2.16.0/assets/examples/Simple Nonlinear Node_14_1.png differ diff --git a/v2.16.0/assets/examples/Tiny Benchmark_11_1.png b/v2.16.0/assets/examples/Tiny Benchmark_11_1.png new file mode 100644 index 000000000..97ee402ca Binary files /dev/null and b/v2.16.0/assets/examples/Tiny Benchmark_11_1.png differ diff --git a/v2.16.0/assets/examples/Tiny Benchmark_7_1.png b/v2.16.0/assets/examples/Tiny Benchmark_7_1.png new file mode 100644 index 000000000..36c08b460 Binary files /dev/null and b/v2.16.0/assets/examples/Tiny Benchmark_7_1.png differ diff --git a/v2.16.0/assets/examples/Universal Mixtures_10_1.png b/v2.16.0/assets/examples/Universal Mixtures_10_1.png new file mode 100644 index 000000000..fd23f884a Binary files /dev/null and b/v2.16.0/assets/examples/Universal Mixtures_10_1.png differ diff --git a/v2.16.0/assets/examples/Universal Mixtures_13_1.png b/v2.16.0/assets/examples/Universal Mixtures_13_1.png new file mode 100644 index 000000000..cf2c5244c Binary files /dev/null and b/v2.16.0/assets/examples/Universal Mixtures_13_1.png differ diff --git a/v2.16.0/assets/examples/Universal Mixtures_3_1.png b/v2.16.0/assets/examples/Universal Mixtures_3_1.png new file mode 100644 index 000000000..cec0904cc Binary files /dev/null and b/v2.16.0/assets/examples/Universal Mixtures_3_1.png differ diff --git a/v2.16.0/assets/examples/Universal Mixtures_9_1.png b/v2.16.0/assets/examples/Universal Mixtures_9_1.png new file mode 100644 index 000000000..a6c946c8b Binary files /dev/null and b/v2.16.0/assets/examples/Universal Mixtures_9_1.png differ diff --git a/v2.16.0/assets/examples/pics/ai-mountain-car-ai.gif b/v2.16.0/assets/examples/pics/ai-mountain-car-ai.gif new file mode 100644 index 000000000..87f6cc774 Binary files /dev/null and b/v2.16.0/assets/examples/pics/ai-mountain-car-ai.gif differ diff --git a/v2.16.0/assets/examples/pics/ai-mountain-car-naive.gif b/v2.16.0/assets/examples/pics/ai-mountain-car-naive.gif new file mode 100644 index 000000000..80fdf4e1c Binary files /dev/null and b/v2.16.0/assets/examples/pics/ai-mountain-car-naive.gif differ diff --git a/v2.16.0/assets/examples/pics/hblr-matrix-completion.jpeg b/v2.16.0/assets/examples/pics/hblr-matrix-completion.jpeg new file mode 100644 index 000000000..be0f78e1c Binary files /dev/null and b/v2.16.0/assets/examples/pics/hblr-matrix-completion.jpeg differ diff --git a/v2.16.0/assets/examples/pics/infinite-data-stream-inference.gif b/v2.16.0/assets/examples/pics/infinite-data-stream-inference.gif new file mode 100644 index 000000000..2f3ee1e3f Binary files /dev/null and b/v2.16.0/assets/examples/pics/infinite-data-stream-inference.gif differ diff --git a/v2.16.0/assets/examples/pics/infinite-data-stream.gif b/v2.16.0/assets/examples/pics/infinite-data-stream.gif new file mode 100644 index 000000000..a7697b1b4 Binary files /dev/null and b/v2.16.0/assets/examples/pics/infinite-data-stream.gif differ diff --git a/v2.16.0/assets/examples/pics/online-coin-bias-inference.gif b/v2.16.0/assets/examples/pics/online-coin-bias-inference.gif new file mode 100644 index 000000000..c78b9388b Binary files /dev/null and b/v2.16.0/assets/examples/pics/online-coin-bias-inference.gif differ diff --git a/v2.16.0/assets/examples/pics/pipeline.png b/v2.16.0/assets/examples/pics/pipeline.png new file mode 100644 index 000000000..d8302e166 Binary files /dev/null and b/v2.16.0/assets/examples/pics/pipeline.png differ diff --git a/v2.16.0/assets/examples/pics/posterior.png b/v2.16.0/assets/examples/pics/posterior.png new file mode 100644 index 000000000..4fa49edff Binary files /dev/null and b/v2.16.0/assets/examples/pics/posterior.png differ diff --git a/v2.16.0/assets/examples/pics/rts_bifm_benchmark.png b/v2.16.0/assets/examples/pics/rts_bifm_benchmark.png new file mode 100644 index 000000000..51a066062 Binary files /dev/null and b/v2.16.0/assets/examples/pics/rts_bifm_benchmark.png differ diff --git a/v2.16.0/assets/examples/pics/sp.png b/v2.16.0/assets/examples/pics/sp.png new file mode 100644 index 000000000..dedc65431 Binary files /dev/null and b/v2.16.0/assets/examples/pics/sp.png differ diff --git a/v2.16.0/assets/examples/pics/vmp.png b/v2.16.0/assets/examples/pics/vmp.png new file mode 100644 index 000000000..0561f27e3 Binary files /dev/null and b/v2.16.0/assets/examples/pics/vmp.png differ diff --git a/v2.16.0/assets/header.css b/v2.16.0/assets/header.css new file mode 100644 index 000000000..155b10a3b --- /dev/null +++ b/v2.16.0/assets/header.css @@ -0,0 +1,138 @@ + +@media all and (max-width: 560px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar { + min-height: 1rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + min-height: 1rem !important; + margin-left: 0.5rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: visible !important; + display: block !important; + margin: 0.5rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + visibility: hidden; + display: none; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a { + visibility: hidden; + display: none; + } + + html:not(.theme--documenter-dark) body #documenter .docs-main { + margin-top: 2rem !important; + } +} + +@media all and (max-width: 1055px) and (min-width: 561px){ + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + width: 80% !important; + } +} + +@media all and (min-width: 1056px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 18rem; + } + +} + +html.theme--documenter-dark header.navigation { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container { + border-bottom: 1px solid #5e6d6f; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: white; + transition: color 100ms; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +html header.navigation { + background-color: white !important; +} + +html header.navigation div.container { + border-bottom: 1px solid #dbdbdb; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: #222; + transition: color 100ms; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +header.navigation { + z-index: 3; +} + +header.navigation div.container nav.navbar ul.navbar-nav { + margin-left: 4rem; + min-height: 3.25rem; + width: 70%; + display: flex; + align-self: auto; + flex-direction: row; + justify-content: space-around; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + align-self: stretch; + align-content: space-around; + justify-content: center; + display: flex; + flex-direction: column; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: hidden; + display: none; +} \ No newline at end of file diff --git a/v2.16.0/assets/header.js b/v2.16.0/assets/header.js new file mode 100644 index 000000000..7f15cae83 --- /dev/null +++ b/v2.16.0/assets/header.js @@ -0,0 +1,97 @@ + +// We add a simple `onload` hook to inject the custom header for our `HTML`-generated pages +window.onload = function() { + //
+ const header = document.createElement('header') + header.classList.add("navigation") + header.appendChild((() => { + const container = document.createElement('div') + container.classList.add('container') + container.appendChild((() => { + const nav = document.createElement('nav') + nav.classList.add("navbar") + + nav.appendChild((() => { + const ul = document.createElement("ul") + ul.classList.add("navbar-nav") + + ul.appendChild((() => { + const smalllink = document.createElement('li') + smalllink.classList.add('small-item') + smalllink.appendChild((() => { + const a = document.createElement('a') + a.classList.add("nav-link") + a.href = 'http://www.rxinfer.ml' + a.innerHTML = 'RxInfer.jl' + a.title = 'RxInfer.jl' + return a + })()) + return smalllink + })()) + + const items = [ + { title: "Home", link: "http://www.rxinfer.ml", icon: [ "fas", "fa-diagram-project" ] }, + { title: "Get Started", link: "https://reactivebayes.github.io/RxInfer.jl/stable/manuals/getting-started/" }, + { title: "Documentation", link: "https://reactivebayes.github.io/RxInfer.jl/stable/" }, + { title: "Examples", link: "https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/" }, + { title: "Papers", link: "https://reactivebayes.github.io/publication/" }, + { title: "Team", link: "https://reactivebayes.github.io/team/" }, + // { title: "Contact", link: "http://www.rxinfer.ml/contact/" }, the redirect is broken for now + { title: "GitHub", link: "https://github.com/reactivebayes/RxInfer.jl", icon: [ "fab", "fa-github" ] }, + ] + + items.forEach((item) => { + ul.appendChild(((item) => { + const li = document.createElement("li") + li.classList.add("nav-item") + li.appendChild((() => { + const a = document.createElement("a") + + if (item.icon !== undefined) { + a.appendChild((() => { + const i = document.createElement("i") + i.classList.add(...(item.icon)) + return i + })()) + } + + a.classList.add("nav-link") + a.href = item.link + a.title = item.title + + a.appendChild((() => { + const span = document.createElement("span") + span.innerHTML = ` ${item.title}` + return span + })()) + + return a + })()) + return li + })(item)) + }) + return ul + })()) + return nav + })()) + return container + })()) + + const documenterTarget = document.querySelector('#documenter'); + + documenterTarget.parentNode.insertBefore(header, documenterTarget); + + // Edit broken links in the examples, see issue #70 + const editOnGithubLinkTarget = document.querySelector('.docs-edit-link'); + + if (editOnGithubLinkTarget) { + const link = editOnGithubLinkTarget.href; + if (link.includes('docs/src/examples')) { + const fixedLink = link.replace('docs/src/', '').replace('.md', '.ipynb'); + editOnGithubLinkTarget.href = fixedLink; + console.log('Fixed link for the example: ', fixedLink) + } + } + +} + diff --git a/v2.16.0/assets/img/bp-message.svg b/v2.16.0/assets/img/bp-message.svg new file mode 100644 index 000000000..259b70803 --- /dev/null +++ b/v2.16.0/assets/img/bp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.16.0/assets/img/coin-flip.png b/v2.16.0/assets/img/coin-flip.png new file mode 100644 index 000000000..2ed0f04c0 Binary files /dev/null and b/v2.16.0/assets/img/coin-flip.png differ diff --git a/v2.16.0/assets/img/coin-flip.svg b/v2.16.0/assets/img/coin-flip.svg new file mode 100644 index 000000000..a85960c12 --- /dev/null +++ b/v2.16.0/assets/img/coin-flip.svg @@ -0,0 +1,794 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/assets/img/debugging_graph.png b/v2.16.0/assets/img/debugging_graph.png new file mode 100644 index 000000000..b97ef1a06 Binary files /dev/null and b/v2.16.0/assets/img/debugging_graph.png differ diff --git a/v2.16.0/assets/img/debugging_messages.png b/v2.16.0/assets/img/debugging_messages.png new file mode 100644 index 000000000..8ec84e778 Binary files /dev/null and b/v2.16.0/assets/img/debugging_messages.png differ diff --git a/v2.16.0/assets/img/release_comment.png b/v2.16.0/assets/img/release_comment.png new file mode 100644 index 000000000..743fe9614 Binary files /dev/null and b/v2.16.0/assets/img/release_comment.png differ diff --git a/v2.16.0/assets/img/vmp-message.svg b/v2.16.0/assets/img/vmp-message.svg new file mode 100644 index 000000000..475cd7f49 --- /dev/null +++ b/v2.16.0/assets/img/vmp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.16.0/assets/logo-dark.svg b/v2.16.0/assets/logo-dark.svg new file mode 100644 index 000000000..63b4f65fa --- /dev/null +++ b/v2.16.0/assets/logo-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + diff --git a/v2.16.0/assets/logo.svg b/v2.16.0/assets/logo.svg new file mode 100644 index 000000000..b799e5beb --- /dev/null +++ b/v2.16.0/assets/logo.svg @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/v2.16.0/assets/theme.css b/v2.16.0/assets/theme.css new file mode 100644 index 000000000..1b060cdef --- /dev/null +++ b/v2.16.0/assets/theme.css @@ -0,0 +1,27 @@ +html body #documenter .docs-main { + margin-top: 4rem; +} + +html body #documenter .docs-sidebar.visible { + margin-top: 0px !important; +} + +html div.light-biglogo { + display: block; +} + +html.theme--documenter-dark div.light-biglogo { + display: none; +} + +html div.dark-biglogo { + display: none; +} + +html.theme--documenter-dark div.dark-biglogo { + display: block; +} + +#documenter .docs-main article.content img { + width: 100%; +} diff --git a/v2.16.0/assets/themes/documenter-dark.css b/v2.16.0/assets/themes/documenter-dark.css new file mode 100644 index 000000000..9f5449f4b --- /dev/null +++ b/v2.16.0/assets/themes/documenter-dark.css @@ -0,0 +1,7 @@ +html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:.4em;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus,html.theme--documenter-dark .pagination-ellipsis:focus,html.theme--documenter-dark .file-cta:focus,html.theme--documenter-dark .file-name:focus,html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .button:focus,html.theme--documenter-dark .is-focused.pagination-previous,html.theme--documenter-dark .is-focused.pagination-next,html.theme--documenter-dark .is-focused.pagination-link,html.theme--documenter-dark .is-focused.pagination-ellipsis,html.theme--documenter-dark .is-focused.file-cta,html.theme--documenter-dark .is-focused.file-name,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-focused.button,html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active,html.theme--documenter-dark .pagination-ellipsis:active,html.theme--documenter-dark .file-cta:active,html.theme--documenter-dark .file-name:active,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .button:active,html.theme--documenter-dark .is-active.pagination-previous,html.theme--documenter-dark .is-active.pagination-next,html.theme--documenter-dark .is-active.pagination-link,html.theme--documenter-dark .is-active.pagination-ellipsis,html.theme--documenter-dark .is-active.file-cta,html.theme--documenter-dark .is-active.file-name,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .is-active.button{outline:none}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-ellipsis[disabled],html.theme--documenter-dark .file-cta[disabled],html.theme--documenter-dark .file-name[disabled],html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark fieldset[disabled] .pagination-previous,fieldset[disabled] html.theme--documenter-dark .pagination-next,html.theme--documenter-dark fieldset[disabled] .pagination-next,fieldset[disabled] html.theme--documenter-dark .pagination-link,html.theme--documenter-dark fieldset[disabled] .pagination-link,fieldset[disabled] html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark fieldset[disabled] .pagination-ellipsis,fieldset[disabled] html.theme--documenter-dark .file-cta,html.theme--documenter-dark fieldset[disabled] .file-cta,fieldset[disabled] html.theme--documenter-dark .file-name,html.theme--documenter-dark fieldset[disabled] .file-name,fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark fieldset[disabled] .select select,html.theme--documenter-dark .select fieldset[disabled] select,html.theme--documenter-dark fieldset[disabled] .textarea,html.theme--documenter-dark fieldset[disabled] .input,html.theme--documenter-dark fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] html.theme--documenter-dark .button,html.theme--documenter-dark fieldset[disabled] .button{cursor:not-allowed}html.theme--documenter-dark .tabs,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .breadcrumb,html.theme--documenter-dark .file,html.theme--documenter-dark .button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after,html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}html.theme--documenter-dark .admonition:not(:last-child),html.theme--documenter-dark .tabs:not(:last-child),html.theme--documenter-dark .pagination:not(:last-child),html.theme--documenter-dark .message:not(:last-child),html.theme--documenter-dark .level:not(:last-child),html.theme--documenter-dark .breadcrumb:not(:last-child),html.theme--documenter-dark .block:not(:last-child),html.theme--documenter-dark .title:not(:last-child),html.theme--documenter-dark .subtitle:not(:last-child),html.theme--documenter-dark .table-container:not(:last-child),html.theme--documenter-dark .table:not(:last-child),html.theme--documenter-dark .progress:not(:last-child),html.theme--documenter-dark .notification:not(:last-child),html.theme--documenter-dark .content:not(:last-child),html.theme--documenter-dark .box:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .modal-close,html.theme--documenter-dark .delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before,html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before{height:2px;width:50%}html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{height:50%;width:2px}html.theme--documenter-dark .modal-close:hover,html.theme--documenter-dark .delete:hover,html.theme--documenter-dark .modal-close:focus,html.theme--documenter-dark .delete:focus{background-color:rgba(10,10,10,0.3)}html.theme--documenter-dark .modal-close:active,html.theme--documenter-dark .delete:active{background-color:rgba(10,10,10,0.4)}html.theme--documenter-dark .is-small.modal-close,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.modal-close,html.theme--documenter-dark .is-small.delete,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}html.theme--documenter-dark .is-medium.modal-close,html.theme--documenter-dark .is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}html.theme--documenter-dark .is-large.modal-close,html.theme--documenter-dark .is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}html.theme--documenter-dark .control.is-loading::after,html.theme--documenter-dark .select.is-loading::after,html.theme--documenter-dark .loader,html.theme--documenter-dark .button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdee0;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}html.theme--documenter-dark .hero-video,html.theme--documenter-dark .modal-background,html.theme--documenter-dark .modal,html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}html.theme--documenter-dark .navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#ecf0f1 !important}a.has-text-light:hover,a.has-text-light:focus{color:#cfd9db !important}.has-background-light{background-color:#ecf0f1 !important}.has-text-dark{color:#282f2f !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#111414 !important}.has-background-dark{background-color:#282f2f !important}.has-text-primary{color:#375a7f !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#28415b !important}.has-background-primary{background-color:#375a7f !important}.has-text-primary-light{color:#f1f5f9 !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#cddbe9 !important}.has-background-primary-light{background-color:#f1f5f9 !important}.has-text-primary-dark{color:#4d7eb2 !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#7198c1 !important}.has-background-primary-dark{background-color:#4d7eb2 !important}.has-text-link{color:#1abc9c !important}a.has-text-link:hover,a.has-text-link:focus{color:#148f77 !important}.has-background-link{background-color:#1abc9c !important}.has-text-link-light{color:#edfdf9 !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c0f6ec !important}.has-background-link-light{background-color:#edfdf9 !important}.has-text-link-dark{color:#15987e !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#1bc5a4 !important}.has-background-link-dark{background-color:#15987e !important}.has-text-info{color:#024c7d !important}a.has-text-info:hover,a.has-text-info:focus{color:#012d4b !important}.has-background-info{background-color:#024c7d !important}.has-text-info-light{color:#ebf7ff !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#b9e2fe !important}.has-background-info-light{background-color:#ebf7ff !important}.has-text-info-dark{color:#0e9dfb !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#40b1fc !important}.has-background-info-dark{background-color:#0e9dfb !important}.has-text-success{color:#008438 !important}a.has-text-success:hover,a.has-text-success:focus{color:#005122 !important}.has-background-success{background-color:#008438 !important}.has-text-success-light{color:#ebfff3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#b8ffd6 !important}.has-background-success-light{background-color:#ebfff3 !important}.has-text-success-dark{color:#00eb64 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#1fff7e !important}.has-background-success-dark{background-color:#00eb64 !important}.has-text-warning{color:#ad8100 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#7a5b00 !important}.has-background-warning{background-color:#ad8100 !important}.has-text-warning-light{color:#fffaeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#ffedb8 !important}.has-background-warning-light{background-color:#fffaeb !important}.has-text-warning-dark{color:#d19c00 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#ffbf05 !important}.has-background-warning-dark{background-color:#d19c00 !important}.has-text-danger{color:#9e1b0d !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#6f1309 !important}.has-background-danger{background-color:#9e1b0d !important}.has-text-danger-light{color:#fdeeec !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#fac3bd !important}.has-background-danger-light{background-color:#fdeeec !important}.has-text-danger-dark{color:#ec311d !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#f05c4c !important}.has-background-danger-dark{background-color:#ec311d !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#282f2f !important}.has-background-grey-darker{background-color:#282f2f !important}.has-text-grey-dark{color:#343c3d !important}.has-background-grey-dark{background-color:#343c3d !important}.has-text-grey{color:#5e6d6f !important}.has-background-grey{background-color:#5e6d6f !important}.has-text-grey-light{color:#8c9b9d !important}.has-background-grey-light{background-color:#8c9b9d !important}.has-text-grey-lighter{color:#dbdee0 !important}.has-background-grey-lighter{background-color:#dbdee0 !important}.has-text-white-ter{color:#ecf0f1 !important}.has-background-white-ter{background-color:#ecf0f1 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}html.theme--documenter-dark{/*! + Theme: a11y-dark + Author: @ericwbailey + Maintainer: @ericwbailey + + Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css +*/}html.theme--documenter-dark html{background-color:#1f2424;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark article,html.theme--documenter-dark aside,html.theme--documenter-dark figure,html.theme--documenter-dark footer,html.theme--documenter-dark header,html.theme--documenter-dark hgroup,html.theme--documenter-dark section{display:block}html.theme--documenter-dark body,html.theme--documenter-dark button,html.theme--documenter-dark input,html.theme--documenter-dark optgroup,html.theme--documenter-dark select,html.theme--documenter-dark textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}html.theme--documenter-dark code,html.theme--documenter-dark pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark body{color:#fff;font-size:1em;font-weight:400;line-height:1.5}html.theme--documenter-dark a{color:#1abc9c;cursor:pointer;text-decoration:none}html.theme--documenter-dark a strong{color:currentColor}html.theme--documenter-dark a:hover{color:#1dd2af}html.theme--documenter-dark code{background-color:rgba(255,255,255,0.05);color:#ececec;font-size:.875em;font-weight:normal;padding:.1em}html.theme--documenter-dark hr{background-color:#282f2f;border:none;display:block;height:2px;margin:1.5rem 0}html.theme--documenter-dark img{height:auto;max-width:100%}html.theme--documenter-dark input[type="checkbox"],html.theme--documenter-dark input[type="radio"]{vertical-align:baseline}html.theme--documenter-dark small{font-size:.875em}html.theme--documenter-dark span{font-style:inherit;font-weight:inherit}html.theme--documenter-dark strong{color:#f2f2f2;font-weight:700}html.theme--documenter-dark fieldset{border:none}html.theme--documenter-dark pre{-webkit-overflow-scrolling:touch;background-color:#282f2f;color:#fff;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}html.theme--documenter-dark pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}html.theme--documenter-dark table td,html.theme--documenter-dark table th{vertical-align:top}html.theme--documenter-dark table td:not([align]),html.theme--documenter-dark table th:not([align]){text-align:inherit}html.theme--documenter-dark table th{color:#f2f2f2}html.theme--documenter-dark .box{background-color:#343c3d;border-radius:8px;box-shadow:none;color:#fff;display:block;padding:1.25rem}html.theme--documenter-dark a.box:hover,html.theme--documenter-dark a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #1abc9c}html.theme--documenter-dark a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #1abc9c}html.theme--documenter-dark .button{background-color:#282f2f;border-color:#4c5759;border-width:1px;color:#375a7f;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}html.theme--documenter-dark .button strong{color:inherit}html.theme--documenter-dark .button .icon,html.theme--documenter-dark .button .icon.is-small,html.theme--documenter-dark .button #documenter .docs-sidebar form.docs-search>input.icon,html.theme--documenter-dark #documenter .docs-sidebar .button form.docs-search>input.icon,html.theme--documenter-dark .button .icon.is-medium,html.theme--documenter-dark .button .icon.is-large{height:1.5em;width:1.5em}html.theme--documenter-dark .button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}html.theme--documenter-dark .button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button:hover,html.theme--documenter-dark .button.is-hovered{border-color:#8c9b9d;color:#f2f2f2}html.theme--documenter-dark .button:focus,html.theme--documenter-dark .button.is-focused{border-color:#8c9b9d;color:#17a689}html.theme--documenter-dark .button:focus:not(:active),html.theme--documenter-dark .button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button:active,html.theme--documenter-dark .button.is-active{border-color:#343c3d;color:#f2f2f2}html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;color:#fff;text-decoration:underline}html.theme--documenter-dark .button.is-text:hover,html.theme--documenter-dark .button.is-text.is-hovered,html.theme--documenter-dark .button.is-text:focus,html.theme--documenter-dark .button.is-text.is-focused{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .button.is-text:active,html.theme--documenter-dark .button.is-text.is-active{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .button.is-text[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}html.theme--documenter-dark .button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#1abc9c;text-decoration:none}html.theme--documenter-dark .button.is-ghost:hover,html.theme--documenter-dark .button.is-ghost.is-hovered{color:#1abc9c;text-decoration:underline}html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:hover,html.theme--documenter-dark .button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus,html.theme--documenter-dark .button.is-white.is-focused{border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus:not(:active),html.theme--documenter-dark .button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-hovered{background-color:#000}html.theme--documenter-dark .button.is-white.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-white.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:hover,html.theme--documenter-dark .button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus,html.theme--documenter-dark .button.is-black.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus:not(:active),html.theme--documenter-dark .button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-black.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:hover,html.theme--documenter-dark .button.is-light.is-hovered{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus,html.theme--documenter-dark .button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus:not(:active),html.theme--documenter-dark .button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light.is-active{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:#ecf0f1;box-shadow:none}html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-outlined.is-focused{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-dark,html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover,html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus:not(:active),html.theme--documenter-dark .content kbd.button:focus:not(:active),html.theme--documenter-dark .button.is-dark.is-focused:not(:active),html.theme--documenter-dark .content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark[disabled],html.theme--documenter-dark .content kbd.button[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark,fieldset[disabled] html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:#282f2f;box-shadow:none}html.theme--documenter-dark .button.is-dark.is-inverted,html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted:hover,html.theme--documenter-dark .content kbd.button.is-inverted:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-dark.is-inverted[disabled],html.theme--documenter-dark .content kbd.button.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-loading::after,html.theme--documenter-dark .content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined,html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-outlined.is-focused{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus:not(:active),html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus:not(:active),html.theme--documenter-dark .button.is-primary.is-focused:not(:active),html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary[disabled],html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;box-shadow:none}html.theme--documenter-dark .button.is-primary.is-inverted,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}html.theme--documenter-dark .button.is-primary.is-inverted[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:hover,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-light.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e8eef5;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:active,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-light.is-active,html.theme--documenter-dark .docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#dfe8f1;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:hover,html.theme--documenter-dark .button.is-link.is-hovered{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus,html.theme--documenter-dark .button.is-link.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus:not(:active),html.theme--documenter-dark .button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link.is-active{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:#1abc9c;box-shadow:none}html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-link.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-outlined.is-focused{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:hover,html.theme--documenter-dark .button.is-link.is-light.is-hovered{background-color:#e2fbf6;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:active,html.theme--documenter-dark .button.is-link.is-light.is-active{background-color:#d7f9f3;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:hover,html.theme--documenter-dark .button.is-info.is-hovered{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus,html.theme--documenter-dark .button.is-info.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus:not(:active),html.theme--documenter-dark .button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info.is-active{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:#024c7d;box-shadow:none}html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-info.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;color:#024c7d}html.theme--documenter-dark .button.is-info.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-outlined.is-focused{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:hover,html.theme--documenter-dark .button.is-info.is-light.is-hovered{background-color:#def2fe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:active,html.theme--documenter-dark .button.is-info.is-light.is-active{background-color:#d2edfe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:hover,html.theme--documenter-dark .button.is-success.is-hovered{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus,html.theme--documenter-dark .button.is-success.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus:not(:active),html.theme--documenter-dark .button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success.is-active{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:#008438;box-shadow:none}html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-success.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;color:#008438}html.theme--documenter-dark .button.is-success.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-outlined.is-focused{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:hover,html.theme--documenter-dark .button.is-success.is-light.is-hovered{background-color:#deffec;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:active,html.theme--documenter-dark .button.is-success.is-light.is-active{background-color:#d1ffe5;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:hover,html.theme--documenter-dark .button.is-warning.is-hovered{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus,html.theme--documenter-dark .button.is-warning.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus:not(:active),html.theme--documenter-dark .button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning.is-active{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:#ad8100;box-shadow:none}html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-warning.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-outlined.is-focused{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-focused{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:hover,html.theme--documenter-dark .button.is-warning.is-light.is-hovered{background-color:#fff7de;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:active,html.theme--documenter-dark .button.is-warning.is-light.is-active{background-color:#fff3d1;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:hover,html.theme--documenter-dark .button.is-danger.is-hovered{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus,html.theme--documenter-dark .button.is-danger.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus:not(:active),html.theme--documenter-dark .button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger.is-active{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;box-shadow:none}html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-danger.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-outlined.is-focused{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:hover,html.theme--documenter-dark .button.is-danger.is-light.is-hovered{background-color:#fce3e0;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:active,html.theme--documenter-dark .button.is-danger.is-light.is-active{background-color:#fcd8d5;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}html.theme--documenter-dark .button.is-small:not(.is-rounded),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:3px}html.theme--documenter-dark .button.is-normal{font-size:1rem}html.theme--documenter-dark .button.is-medium{font-size:1.25rem}html.theme--documenter-dark .button.is-large{font-size:1.5rem}html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .button{background-color:#8c9b9d;border-color:#5e6d6f;box-shadow:none;opacity:.5}html.theme--documenter-dark .button.is-fullwidth{display:flex;width:100%}html.theme--documenter-dark .button.is-loading{color:transparent !important;pointer-events:none}html.theme--documenter-dark .button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}html.theme--documenter-dark .button.is-static{background-color:#282f2f;border-color:#5e6d6f;color:#dbdee0;box-shadow:none;pointer-events:none}html.theme--documenter-dark .button.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}html.theme--documenter-dark .buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .buttons .button{margin-bottom:0.5rem}html.theme--documenter-dark .buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}html.theme--documenter-dark .buttons:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .buttons:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:3px}html.theme--documenter-dark .buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}html.theme--documenter-dark .buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}html.theme--documenter-dark .buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}html.theme--documenter-dark .buttons.has-addons .button:last-child{margin-right:0}html.theme--documenter-dark .buttons.has-addons .button:hover,html.theme--documenter-dark .buttons.has-addons .button.is-hovered{z-index:2}html.theme--documenter-dark .buttons.has-addons .button:focus,html.theme--documenter-dark .buttons.has-addons .button.is-focused,html.theme--documenter-dark .buttons.has-addons .button:active,html.theme--documenter-dark .buttons.has-addons .button.is-active,html.theme--documenter-dark .buttons.has-addons .button.is-selected{z-index:3}html.theme--documenter-dark .buttons.has-addons .button:focus:hover,html.theme--documenter-dark .buttons.has-addons .button.is-focused:hover,html.theme--documenter-dark .buttons.has-addons .button:active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-selected:hover{z-index:4}html.theme--documenter-dark .buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .buttons.is-centered{justify-content:center}html.theme--documenter-dark .buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}html.theme--documenter-dark .buttons.is-right{justify-content:flex-end}html.theme--documenter-dark .buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:1rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1.25rem}}html.theme--documenter-dark .container{flex-grow:1;margin:0 auto;position:relative;width:auto}html.theme--documenter-dark .container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){html.theme--documenter-dark .container{max-width:992px}}@media screen and (max-width: 1215px){html.theme--documenter-dark .container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){html.theme--documenter-dark .container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){html.theme--documenter-dark .container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){html.theme--documenter-dark .container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}html.theme--documenter-dark .content li+li{margin-top:0.25em}html.theme--documenter-dark .content p:not(:last-child),html.theme--documenter-dark .content dl:not(:last-child),html.theme--documenter-dark .content ol:not(:last-child),html.theme--documenter-dark .content ul:not(:last-child),html.theme--documenter-dark .content blockquote:not(:last-child),html.theme--documenter-dark .content pre:not(:last-child),html.theme--documenter-dark .content table:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .content h1,html.theme--documenter-dark .content h2,html.theme--documenter-dark .content h3,html.theme--documenter-dark .content h4,html.theme--documenter-dark .content h5,html.theme--documenter-dark .content h6{color:#f2f2f2;font-weight:600;line-height:1.125}html.theme--documenter-dark .content h1{font-size:2em;margin-bottom:0.5em}html.theme--documenter-dark .content h1:not(:first-child){margin-top:1em}html.theme--documenter-dark .content h2{font-size:1.75em;margin-bottom:0.5714em}html.theme--documenter-dark .content h2:not(:first-child){margin-top:1.1428em}html.theme--documenter-dark .content h3{font-size:1.5em;margin-bottom:0.6666em}html.theme--documenter-dark .content h3:not(:first-child){margin-top:1.3333em}html.theme--documenter-dark .content h4{font-size:1.25em;margin-bottom:0.8em}html.theme--documenter-dark .content h5{font-size:1.125em;margin-bottom:0.8888em}html.theme--documenter-dark .content h6{font-size:1em;margin-bottom:1em}html.theme--documenter-dark .content blockquote{background-color:#282f2f;border-left:5px solid #5e6d6f;padding:1.25em 1.5em}html.theme--documenter-dark .content ol{list-style-position:outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ol:not([type]){list-style-type:decimal}html.theme--documenter-dark .content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}html.theme--documenter-dark .content ol.is-lower-roman:not([type]){list-style-type:lower-roman}html.theme--documenter-dark .content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}html.theme--documenter-dark .content ol.is-upper-roman:not([type]){list-style-type:upper-roman}html.theme--documenter-dark .content ul{list-style:disc outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ul ul{list-style-type:circle;margin-top:0.5em}html.theme--documenter-dark .content ul ul ul{list-style-type:square}html.theme--documenter-dark .content dd{margin-left:2em}html.theme--documenter-dark .content figure{margin-left:2em;margin-right:2em;text-align:center}html.theme--documenter-dark .content figure:not(:first-child){margin-top:2em}html.theme--documenter-dark .content figure:not(:last-child){margin-bottom:2em}html.theme--documenter-dark .content figure img{display:inline-block}html.theme--documenter-dark .content figure figcaption{font-style:italic}html.theme--documenter-dark .content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}html.theme--documenter-dark .content sup,html.theme--documenter-dark .content sub{font-size:75%}html.theme--documenter-dark .content table{width:100%}html.theme--documenter-dark .content table td,html.theme--documenter-dark .content table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .content table th{color:#f2f2f2}html.theme--documenter-dark .content table th:not([align]){text-align:inherit}html.theme--documenter-dark .content table thead td,html.theme--documenter-dark .content table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .content table tfoot td,html.theme--documenter-dark .content table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .content table tbody tr:last-child td,html.theme--documenter-dark .content table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .content .tabs li+li{margin-top:0}html.theme--documenter-dark .content.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}html.theme--documenter-dark .content.is-normal{font-size:1rem}html.theme--documenter-dark .content.is-medium{font-size:1.25rem}html.theme--documenter-dark .content.is-large{font-size:1.5rem}html.theme--documenter-dark .icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}html.theme--documenter-dark .icon.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}html.theme--documenter-dark .icon.is-medium{height:2rem;width:2rem}html.theme--documenter-dark .icon.is-large{height:3rem;width:3rem}html.theme--documenter-dark .icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}html.theme--documenter-dark .icon-text .icon{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .icon-text .icon:not(:last-child){margin-right:.25em}html.theme--documenter-dark .icon-text .icon:not(:first-child){margin-left:.25em}html.theme--documenter-dark div.icon-text{display:flex}html.theme--documenter-dark .image,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{display:block;position:relative}html.theme--documenter-dark .image img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}html.theme--documenter-dark .image img.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}html.theme--documenter-dark .image.is-fullwidth,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}html.theme--documenter-dark .image.is-square,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square,html.theme--documenter-dark .image.is-1by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}html.theme--documenter-dark .image.is-5by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}html.theme--documenter-dark .image.is-4by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}html.theme--documenter-dark .image.is-3by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}html.theme--documenter-dark .image.is-5by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}html.theme--documenter-dark .image.is-16by9,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}html.theme--documenter-dark .image.is-2by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}html.theme--documenter-dark .image.is-3by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}html.theme--documenter-dark .image.is-4by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}html.theme--documenter-dark .image.is-3by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}html.theme--documenter-dark .image.is-2by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}html.theme--documenter-dark .image.is-3by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}html.theme--documenter-dark .image.is-9by16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}html.theme--documenter-dark .image.is-1by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}html.theme--documenter-dark .image.is-1by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}html.theme--documenter-dark .image.is-16x16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}html.theme--documenter-dark .image.is-24x24,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}html.theme--documenter-dark .image.is-32x32,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}html.theme--documenter-dark .image.is-48x48,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}html.theme--documenter-dark .image.is-64x64,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}html.theme--documenter-dark .image.is-96x96,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}html.theme--documenter-dark .image.is-128x128,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}html.theme--documenter-dark .notification{background-color:#282f2f;border-radius:.4em;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}html.theme--documenter-dark .notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .notification strong{color:currentColor}html.theme--documenter-dark .notification code,html.theme--documenter-dark .notification pre{background:#fff}html.theme--documenter-dark .notification pre code{background:transparent}html.theme--documenter-dark .notification>.delete{right:.5rem;position:absolute;top:0.5rem}html.theme--documenter-dark .notification .title,html.theme--documenter-dark .notification .subtitle,html.theme--documenter-dark .notification .content{color:currentColor}html.theme--documenter-dark .notification.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .notification.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .notification.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .notification.is-dark,html.theme--documenter-dark .content kbd.notification{background-color:#282f2f;color:#fff}html.theme--documenter-dark .notification.is-primary,html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .notification.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.notification.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .notification.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .notification.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .notification.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .notification.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .notification.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .notification.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .notification.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .notification.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .notification.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .notification.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}html.theme--documenter-dark .progress::-webkit-progress-bar{background-color:#343c3d}html.theme--documenter-dark .progress::-webkit-progress-value{background-color:#dbdee0}html.theme--documenter-dark .progress::-moz-progress-bar{background-color:#dbdee0}html.theme--documenter-dark .progress::-ms-fill{background-color:#dbdee0;border:none}html.theme--documenter-dark .progress.is-white::-webkit-progress-value{background-color:#fff}html.theme--documenter-dark .progress.is-white::-moz-progress-bar{background-color:#fff}html.theme--documenter-dark .progress.is-white::-ms-fill{background-color:#fff}html.theme--documenter-dark .progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-black::-webkit-progress-value{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-moz-progress-bar{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-ms-fill{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-light::-webkit-progress-value{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-moz-progress-bar{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-ms-fill{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light:indeterminate{background-image:linear-gradient(to right, #ecf0f1 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-dark::-webkit-progress-value,html.theme--documenter-dark .content kbd.progress::-webkit-progress-value{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-moz-progress-bar,html.theme--documenter-dark .content kbd.progress::-moz-progress-bar{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-ms-fill,html.theme--documenter-dark .content kbd.progress::-ms-fill{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark:indeterminate,html.theme--documenter-dark .content kbd.progress:indeterminate{background-image:linear-gradient(to right, #282f2f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-primary::-webkit-progress-value,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-moz-progress-bar,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-ms-fill,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary:indeterminate,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #375a7f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-link::-webkit-progress-value{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-moz-progress-bar{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-ms-fill{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link:indeterminate{background-image:linear-gradient(to right, #1abc9c 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-info::-webkit-progress-value{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-moz-progress-bar{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-ms-fill{background-color:#024c7d}html.theme--documenter-dark .progress.is-info:indeterminate{background-image:linear-gradient(to right, #024c7d 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-success::-webkit-progress-value{background-color:#008438}html.theme--documenter-dark .progress.is-success::-moz-progress-bar{background-color:#008438}html.theme--documenter-dark .progress.is-success::-ms-fill{background-color:#008438}html.theme--documenter-dark .progress.is-success:indeterminate{background-image:linear-gradient(to right, #008438 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-warning::-webkit-progress-value{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-moz-progress-bar{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-ms-fill{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ad8100 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-danger::-webkit-progress-value{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-moz-progress-bar{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-ms-fill{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger:indeterminate{background-image:linear-gradient(to right, #9e1b0d 30%, #343c3d 30%)}html.theme--documenter-dark .progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#343c3d;background-image:linear-gradient(to right, #fff 30%, #343c3d 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}html.theme--documenter-dark .progress:indeterminate::-webkit-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-moz-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-ms-fill{animation-name:none}html.theme--documenter-dark .progress.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}html.theme--documenter-dark .progress.is-medium{height:1.25rem}html.theme--documenter-dark .progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}html.theme--documenter-dark .table{background-color:#343c3d;color:#fff}html.theme--documenter-dark .table td,html.theme--documenter-dark .table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .table td.is-white,html.theme--documenter-dark .table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .table td.is-black,html.theme--documenter-dark .table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .table td.is-light,html.theme--documenter-dark .table th.is-light{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .table td.is-dark,html.theme--documenter-dark .table th.is-dark{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .table td.is-primary,html.theme--documenter-dark .table th.is-primary{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-link,html.theme--documenter-dark .table th.is-link{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .table td.is-info,html.theme--documenter-dark .table th.is-info{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .table td.is-success,html.theme--documenter-dark .table th.is-success{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .table td.is-warning,html.theme--documenter-dark .table th.is-warning{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .table td.is-danger,html.theme--documenter-dark .table th.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .table td.is-narrow,html.theme--documenter-dark .table th.is-narrow{white-space:nowrap;width:1%}html.theme--documenter-dark .table td.is-selected,html.theme--documenter-dark .table th.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-selected a,html.theme--documenter-dark .table td.is-selected strong,html.theme--documenter-dark .table th.is-selected a,html.theme--documenter-dark .table th.is-selected strong{color:currentColor}html.theme--documenter-dark .table td.is-vcentered,html.theme--documenter-dark .table th.is-vcentered{vertical-align:middle}html.theme--documenter-dark .table th{color:#f2f2f2}html.theme--documenter-dark .table th:not([align]){text-align:left}html.theme--documenter-dark .table tr.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table tr.is-selected a,html.theme--documenter-dark .table tr.is-selected strong{color:currentColor}html.theme--documenter-dark .table tr.is-selected td,html.theme--documenter-dark .table tr.is-selected th{border-color:#fff;color:currentColor}html.theme--documenter-dark .table thead{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table thead td,html.theme--documenter-dark .table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .table tfoot{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tfoot td,html.theme--documenter-dark .table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .table tbody{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tbody tr:last-child td,html.theme--documenter-dark .table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .table.is-bordered td,html.theme--documenter-dark .table.is-bordered th{border-width:1px}html.theme--documenter-dark .table.is-bordered tr:last-child td,html.theme--documenter-dark .table.is-bordered tr:last-child th{border-bottom-width:1px}html.theme--documenter-dark .table.is-fullwidth{width:100%}html.theme--documenter-dark .table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#2d3435}html.theme--documenter-dark .table.is-narrow td,html.theme--documenter-dark .table.is-narrow th{padding:0.25em 0.5em}html.theme--documenter-dark .table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#282f2f}html.theme--documenter-dark .table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}html.theme--documenter-dark .tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .tags .tag,html.theme--documenter-dark .tags .content kbd,html.theme--documenter-dark .content .tags kbd,html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}html.theme--documenter-dark .tags .tag:not(:last-child),html.theme--documenter-dark .tags .content kbd:not(:last-child),html.theme--documenter-dark .content .tags kbd:not(:last-child),html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}html.theme--documenter-dark .tags:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .tags:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .tags.are-medium .tag:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .content kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .content .tags.are-medium kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}html.theme--documenter-dark .tags.are-large .tag:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .content kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .content .tags.are-large kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}html.theme--documenter-dark .tags.is-centered{justify-content:center}html.theme--documenter-dark .tags.is-centered .tag,html.theme--documenter-dark .tags.is-centered .content kbd,html.theme--documenter-dark .content .tags.is-centered kbd,html.theme--documenter-dark .tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}html.theme--documenter-dark .tags.is-right{justify-content:flex-end}html.theme--documenter-dark .tags.is-right .tag:not(:first-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:first-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}html.theme--documenter-dark .tags.is-right .tag:not(:last-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:last-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}html.theme--documenter-dark .tags.has-addons .tag,html.theme--documenter-dark .tags.has-addons .content kbd,html.theme--documenter-dark .content .tags.has-addons kbd,html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}html.theme--documenter-dark .tags.has-addons .tag:not(:first-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:first-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}html.theme--documenter-dark .tags.has-addons .tag:not(:last-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:last-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}html.theme--documenter-dark .tag:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#282f2f;border-radius:.4em;color:#fff;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}html.theme--documenter-dark .tag:not(body) .delete,html.theme--documenter-dark .content kbd:not(body) .delete,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}html.theme--documenter-dark .tag.is-white:not(body),html.theme--documenter-dark .content kbd.is-white:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .tag.is-black:not(body),html.theme--documenter-dark .content kbd.is-black:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .tag.is-light:not(body),html.theme--documenter-dark .content kbd.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .tag.is-dark:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-dark:not(body),html.theme--documenter-dark .content .docstring>section>kbd:not(body){background-color:#282f2f;color:#fff}html.theme--documenter-dark .tag.is-primary:not(body),html.theme--documenter-dark .content kbd.is-primary:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){background-color:#375a7f;color:#fff}html.theme--documenter-dark .tag.is-primary.is-light:not(body),html.theme--documenter-dark .content kbd.is-primary.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .tag.is-link:not(body),html.theme--documenter-dark .content kbd.is-link:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#1abc9c;color:#fff}html.theme--documenter-dark .tag.is-link.is-light:not(body),html.theme--documenter-dark .content kbd.is-link.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .tag.is-info:not(body),html.theme--documenter-dark .content kbd.is-info:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#024c7d;color:#fff}html.theme--documenter-dark .tag.is-info.is-light:not(body),html.theme--documenter-dark .content kbd.is-info.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .tag.is-success:not(body),html.theme--documenter-dark .content kbd.is-success:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#008438;color:#fff}html.theme--documenter-dark .tag.is-success.is-light:not(body),html.theme--documenter-dark .content kbd.is-success.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .tag.is-warning:not(body),html.theme--documenter-dark .content kbd.is-warning:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ad8100;color:#fff}html.theme--documenter-dark .tag.is-warning.is-light:not(body),html.theme--documenter-dark .content kbd.is-warning.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .tag.is-danger:not(body),html.theme--documenter-dark .content kbd.is-danger:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .tag.is-danger.is-light:not(body),html.theme--documenter-dark .content kbd.is-danger.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .tag.is-normal:not(body),html.theme--documenter-dark .content kbd.is-normal:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}html.theme--documenter-dark .tag.is-medium:not(body),html.theme--documenter-dark .content kbd.is-medium:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}html.theme--documenter-dark .tag.is-large:not(body),html.theme--documenter-dark .content kbd.is-large:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}html.theme--documenter-dark .tag:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .content kbd:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}html.theme--documenter-dark .tag:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .content kbd:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}html.theme--documenter-dark .tag:not(body) .icon:first-child:last-child,html.theme--documenter-dark .content kbd:not(body) .icon:first-child:last-child,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}html.theme--documenter-dark .tag.is-delete:not(body),html.theme--documenter-dark .content kbd.is-delete:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before,html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}html.theme--documenter-dark .tag.is-delete:not(body):hover,html.theme--documenter-dark .content kbd.is-delete:not(body):hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):hover,html.theme--documenter-dark .tag.is-delete:not(body):focus,html.theme--documenter-dark .content kbd.is-delete:not(body):focus,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#1d2122}html.theme--documenter-dark .tag.is-delete:not(body):active,html.theme--documenter-dark .content kbd.is-delete:not(body):active,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#111414}html.theme--documenter-dark .tag.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:not(body),html.theme--documenter-dark .content kbd.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}html.theme--documenter-dark a.tag:hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:hover{text-decoration:underline}html.theme--documenter-dark .title,html.theme--documenter-dark .subtitle{word-break:break-word}html.theme--documenter-dark .title em,html.theme--documenter-dark .title span,html.theme--documenter-dark .subtitle em,html.theme--documenter-dark .subtitle span{font-weight:inherit}html.theme--documenter-dark .title sub,html.theme--documenter-dark .subtitle sub{font-size:.75em}html.theme--documenter-dark .title sup,html.theme--documenter-dark .subtitle sup{font-size:.75em}html.theme--documenter-dark .title .tag,html.theme--documenter-dark .title .content kbd,html.theme--documenter-dark .content .title kbd,html.theme--documenter-dark .title .docstring>section>a.docs-sourcelink,html.theme--documenter-dark .subtitle .tag,html.theme--documenter-dark .subtitle .content kbd,html.theme--documenter-dark .content .subtitle kbd,html.theme--documenter-dark .subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}html.theme--documenter-dark .title{color:#fff;font-size:2rem;font-weight:500;line-height:1.125}html.theme--documenter-dark .title strong{color:inherit;font-weight:inherit}html.theme--documenter-dark .title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}html.theme--documenter-dark .title.is-1{font-size:3rem}html.theme--documenter-dark .title.is-2{font-size:2.5rem}html.theme--documenter-dark .title.is-3{font-size:2rem}html.theme--documenter-dark .title.is-4{font-size:1.5rem}html.theme--documenter-dark .title.is-5{font-size:1.25rem}html.theme--documenter-dark .title.is-6{font-size:1rem}html.theme--documenter-dark .title.is-7{font-size:.75rem}html.theme--documenter-dark .subtitle{color:#8c9b9d;font-size:1.25rem;font-weight:400;line-height:1.25}html.theme--documenter-dark .subtitle strong{color:#8c9b9d;font-weight:600}html.theme--documenter-dark .subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}html.theme--documenter-dark .subtitle.is-1{font-size:3rem}html.theme--documenter-dark .subtitle.is-2{font-size:2.5rem}html.theme--documenter-dark .subtitle.is-3{font-size:2rem}html.theme--documenter-dark .subtitle.is-4{font-size:1.5rem}html.theme--documenter-dark .subtitle.is-5{font-size:1.25rem}html.theme--documenter-dark .subtitle.is-6{font-size:1rem}html.theme--documenter-dark .subtitle.is-7{font-size:.75rem}html.theme--documenter-dark .heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}html.theme--documenter-dark .number{align-items:center;background-color:#282f2f;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#1f2424;border-color:#5e6d6f;border-radius:.4em;color:#dbdee0}html.theme--documenter-dark .select select::-moz-placeholder,html.theme--documenter-dark .textarea::-moz-placeholder,html.theme--documenter-dark .input::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select::-webkit-input-placeholder,html.theme--documenter-dark .textarea::-webkit-input-placeholder,html.theme--documenter-dark .input::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:-moz-placeholder,html.theme--documenter-dark .textarea:-moz-placeholder,html.theme--documenter-dark .input:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select:-ms-input-placeholder,html.theme--documenter-dark .textarea:-ms-input-placeholder,html.theme--documenter-dark .input:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:hover,html.theme--documenter-dark .textarea:hover,html.theme--documenter-dark .input:hover,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:hover,html.theme--documenter-dark .select select.is-hovered,html.theme--documenter-dark .is-hovered.textarea,html.theme--documenter-dark .is-hovered.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#8c9b9d}html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{border-color:#1abc9c;box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#8c9b9d;border-color:#282f2f;box-shadow:none;color:#fff}html.theme--documenter-dark .select select[disabled]::-moz-placeholder,html.theme--documenter-dark .textarea[disabled]::-moz-placeholder,html.theme--documenter-dark .input[disabled]::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .textarea[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .input[disabled]::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-moz-placeholder,html.theme--documenter-dark .textarea[disabled]:-moz-placeholder,html.theme--documenter-dark .input[disabled]:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-ms-input-placeholder,html.theme--documenter-dark .textarea[disabled]:-ms-input-placeholder,html.theme--documenter-dark .input[disabled]:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}html.theme--documenter-dark .textarea[readonly],html.theme--documenter-dark .input[readonly],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}html.theme--documenter-dark .is-white.textarea,html.theme--documenter-dark .is-white.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}html.theme--documenter-dark .is-white.textarea:focus,html.theme--documenter-dark .is-white.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:focus,html.theme--documenter-dark .is-white.is-focused.textarea,html.theme--documenter-dark .is-white.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-white.textarea:active,html.theme--documenter-dark .is-white.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:active,html.theme--documenter-dark .is-white.is-active.textarea,html.theme--documenter-dark .is-white.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .is-black.textarea,html.theme--documenter-dark .is-black.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}html.theme--documenter-dark .is-black.textarea:focus,html.theme--documenter-dark .is-black.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:focus,html.theme--documenter-dark .is-black.is-focused.textarea,html.theme--documenter-dark .is-black.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-black.textarea:active,html.theme--documenter-dark .is-black.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:active,html.theme--documenter-dark .is-black.is-active.textarea,html.theme--documenter-dark .is-black.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .is-light.textarea,html.theme--documenter-dark .is-light.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light{border-color:#ecf0f1}html.theme--documenter-dark .is-light.textarea:focus,html.theme--documenter-dark .is-light.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:focus,html.theme--documenter-dark .is-light.is-focused.textarea,html.theme--documenter-dark .is-light.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-light.textarea:active,html.theme--documenter-dark .is-light.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:active,html.theme--documenter-dark .is-light.is-active.textarea,html.theme--documenter-dark .is-light.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .is-dark.textarea,html.theme--documenter-dark .content kbd.textarea,html.theme--documenter-dark .is-dark.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark,html.theme--documenter-dark .content kbd.input{border-color:#282f2f}html.theme--documenter-dark .is-dark.textarea:focus,html.theme--documenter-dark .content kbd.textarea:focus,html.theme--documenter-dark .is-dark.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:focus,html.theme--documenter-dark .content kbd.input:focus,html.theme--documenter-dark .is-dark.is-focused.textarea,html.theme--documenter-dark .content kbd.is-focused.textarea,html.theme--documenter-dark .is-dark.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .content kbd.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-focused,html.theme--documenter-dark .is-dark.textarea:active,html.theme--documenter-dark .content kbd.textarea:active,html.theme--documenter-dark .is-dark.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:active,html.theme--documenter-dark .content kbd.input:active,html.theme--documenter-dark .is-dark.is-active.textarea,html.theme--documenter-dark .content kbd.is-active.textarea,html.theme--documenter-dark .is-dark.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .content kbd.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .is-primary.textarea,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink{border-color:#375a7f}html.theme--documenter-dark .is-primary.textarea:focus,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:focus,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.is-focused.textarea,html.theme--documenter-dark .docstring>section>a.is-focused.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .docstring>section>a.is-focused.input.docs-sourcelink,html.theme--documenter-dark .is-primary.textarea:active,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:active,html.theme--documenter-dark .is-primary.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:active,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:active,html.theme--documenter-dark .is-primary.is-active.textarea,html.theme--documenter-dark .docstring>section>a.is-active.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .is-link.textarea,html.theme--documenter-dark .is-link.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link{border-color:#1abc9c}html.theme--documenter-dark .is-link.textarea:focus,html.theme--documenter-dark .is-link.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:focus,html.theme--documenter-dark .is-link.is-focused.textarea,html.theme--documenter-dark .is-link.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-link.textarea:active,html.theme--documenter-dark .is-link.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:active,html.theme--documenter-dark .is-link.is-active.textarea,html.theme--documenter-dark .is-link.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .is-info.textarea,html.theme--documenter-dark .is-info.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info{border-color:#024c7d}html.theme--documenter-dark .is-info.textarea:focus,html.theme--documenter-dark .is-info.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:focus,html.theme--documenter-dark .is-info.is-focused.textarea,html.theme--documenter-dark .is-info.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-info.textarea:active,html.theme--documenter-dark .is-info.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:active,html.theme--documenter-dark .is-info.is-active.textarea,html.theme--documenter-dark .is-info.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .is-success.textarea,html.theme--documenter-dark .is-success.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success{border-color:#008438}html.theme--documenter-dark .is-success.textarea:focus,html.theme--documenter-dark .is-success.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:focus,html.theme--documenter-dark .is-success.is-focused.textarea,html.theme--documenter-dark .is-success.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-success.textarea:active,html.theme--documenter-dark .is-success.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:active,html.theme--documenter-dark .is-success.is-active.textarea,html.theme--documenter-dark .is-success.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .is-warning.textarea,html.theme--documenter-dark .is-warning.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ad8100}html.theme--documenter-dark .is-warning.textarea:focus,html.theme--documenter-dark .is-warning.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:focus,html.theme--documenter-dark .is-warning.is-focused.textarea,html.theme--documenter-dark .is-warning.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-warning.textarea:active,html.theme--documenter-dark .is-warning.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:active,html.theme--documenter-dark .is-warning.is-active.textarea,html.theme--documenter-dark .is-warning.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .is-danger.textarea,html.theme--documenter-dark .is-danger.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#9e1b0d}html.theme--documenter-dark .is-danger.textarea:focus,html.theme--documenter-dark .is-danger.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:focus,html.theme--documenter-dark .is-danger.is-focused.textarea,html.theme--documenter-dark .is-danger.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-danger.textarea:active,html.theme--documenter-dark .is-danger.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:active,html.theme--documenter-dark .is-danger.is-active.textarea,html.theme--documenter-dark .is-danger.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .is-small.textarea,html.theme--documenter-dark .is-small.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .is-medium.textarea,html.theme--documenter-dark .is-medium.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}html.theme--documenter-dark .is-large.textarea,html.theme--documenter-dark .is-large.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}html.theme--documenter-dark .is-fullwidth.textarea,html.theme--documenter-dark .is-fullwidth.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}html.theme--documenter-dark .is-inline.textarea,html.theme--documenter-dark .is-inline.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}html.theme--documenter-dark .input.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}html.theme--documenter-dark .input.is-static,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}html.theme--documenter-dark .textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}html.theme--documenter-dark .textarea:not([rows]){max-height:40em;min-height:8em}html.theme--documenter-dark .textarea[rows]{height:initial}html.theme--documenter-dark .textarea.has-fixed-size{resize:none}html.theme--documenter-dark .radio,html.theme--documenter-dark .checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}html.theme--documenter-dark .radio input,html.theme--documenter-dark .checkbox input{cursor:pointer}html.theme--documenter-dark .radio:hover,html.theme--documenter-dark .checkbox:hover{color:#8c9b9d}html.theme--documenter-dark .radio[disabled],html.theme--documenter-dark .checkbox[disabled],fieldset[disabled] html.theme--documenter-dark .radio,fieldset[disabled] html.theme--documenter-dark .checkbox,html.theme--documenter-dark .radio input[disabled],html.theme--documenter-dark .checkbox input[disabled]{color:#fff;cursor:not-allowed}html.theme--documenter-dark .radio+.radio{margin-left:.5em}html.theme--documenter-dark .select{display:inline-block;max-width:100%;position:relative;vertical-align:top}html.theme--documenter-dark .select:not(.is-multiple){height:2.5em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border-color:#1abc9c;right:1.125em;z-index:4}html.theme--documenter-dark .select.is-rounded select,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}html.theme--documenter-dark .select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}html.theme--documenter-dark .select select::-ms-expand{display:none}html.theme--documenter-dark .select select[disabled]:hover,fieldset[disabled] html.theme--documenter-dark .select select:hover{border-color:#282f2f}html.theme--documenter-dark .select select:not([multiple]){padding-right:2.5em}html.theme--documenter-dark .select select[multiple]{height:auto;padding:0}html.theme--documenter-dark .select select[multiple] option{padding:0.5em 1em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading):hover::after{border-color:#8c9b9d}html.theme--documenter-dark .select.is-white:not(:hover)::after{border-color:#fff}html.theme--documenter-dark .select.is-white select{border-color:#fff}html.theme--documenter-dark .select.is-white select:hover,html.theme--documenter-dark .select.is-white select.is-hovered{border-color:#f2f2f2}html.theme--documenter-dark .select.is-white select:focus,html.theme--documenter-dark .select.is-white select.is-focused,html.theme--documenter-dark .select.is-white select:active,html.theme--documenter-dark .select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .select.is-black:not(:hover)::after{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select:hover,html.theme--documenter-dark .select.is-black select.is-hovered{border-color:#000}html.theme--documenter-dark .select.is-black select:focus,html.theme--documenter-dark .select.is-black select.is-focused,html.theme--documenter-dark .select.is-black select:active,html.theme--documenter-dark .select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .select.is-light:not(:hover)::after{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select:hover,html.theme--documenter-dark .select.is-light select.is-hovered{border-color:#dde4e6}html.theme--documenter-dark .select.is-light select:focus,html.theme--documenter-dark .select.is-light select.is-focused,html.theme--documenter-dark .select.is-light select:active,html.theme--documenter-dark .select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .select.is-dark:not(:hover)::after,html.theme--documenter-dark .content kbd.select:not(:hover)::after{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select,html.theme--documenter-dark .content kbd.select select{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select:hover,html.theme--documenter-dark .content kbd.select select:hover,html.theme--documenter-dark .select.is-dark select.is-hovered,html.theme--documenter-dark .content kbd.select select.is-hovered{border-color:#1d2122}html.theme--documenter-dark .select.is-dark select:focus,html.theme--documenter-dark .content kbd.select select:focus,html.theme--documenter-dark .select.is-dark select.is-focused,html.theme--documenter-dark .content kbd.select select.is-focused,html.theme--documenter-dark .select.is-dark select:active,html.theme--documenter-dark .content kbd.select select:active,html.theme--documenter-dark .select.is-dark select.is-active,html.theme--documenter-dark .content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .select.is-primary:not(:hover)::after,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select:hover,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:hover,html.theme--documenter-dark .select.is-primary select.is-hovered,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#2f4d6d}html.theme--documenter-dark .select.is-primary select:focus,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:focus,html.theme--documenter-dark .select.is-primary select.is-focused,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-focused,html.theme--documenter-dark .select.is-primary select:active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:active,html.theme--documenter-dark .select.is-primary select.is-active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .select.is-link:not(:hover)::after{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select:hover,html.theme--documenter-dark .select.is-link select.is-hovered{border-color:#17a689}html.theme--documenter-dark .select.is-link select:focus,html.theme--documenter-dark .select.is-link select.is-focused,html.theme--documenter-dark .select.is-link select:active,html.theme--documenter-dark .select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select.is-info:not(:hover)::after{border-color:#024c7d}html.theme--documenter-dark .select.is-info select{border-color:#024c7d}html.theme--documenter-dark .select.is-info select:hover,html.theme--documenter-dark .select.is-info select.is-hovered{border-color:#023d64}html.theme--documenter-dark .select.is-info select:focus,html.theme--documenter-dark .select.is-info select.is-focused,html.theme--documenter-dark .select.is-info select:active,html.theme--documenter-dark .select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .select.is-success:not(:hover)::after{border-color:#008438}html.theme--documenter-dark .select.is-success select{border-color:#008438}html.theme--documenter-dark .select.is-success select:hover,html.theme--documenter-dark .select.is-success select.is-hovered{border-color:#006b2d}html.theme--documenter-dark .select.is-success select:focus,html.theme--documenter-dark .select.is-success select.is-focused,html.theme--documenter-dark .select.is-success select:active,html.theme--documenter-dark .select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .select.is-warning:not(:hover)::after{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select:hover,html.theme--documenter-dark .select.is-warning select.is-hovered{border-color:#946e00}html.theme--documenter-dark .select.is-warning select:focus,html.theme--documenter-dark .select.is-warning select.is-focused,html.theme--documenter-dark .select.is-warning select:active,html.theme--documenter-dark .select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .select.is-danger:not(:hover)::after{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select:hover,html.theme--documenter-dark .select.is-danger select.is-hovered{border-color:#86170b}html.theme--documenter-dark .select.is-danger select:focus,html.theme--documenter-dark .select.is-danger select.is-focused,html.theme--documenter-dark .select.is-danger select:active,html.theme--documenter-dark .select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .select.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .select.is-medium{font-size:1.25rem}html.theme--documenter-dark .select.is-large{font-size:1.5rem}html.theme--documenter-dark .select.is-disabled::after{border-color:#fff !important;opacity:0.5}html.theme--documenter-dark .select.is-fullwidth{width:100%}html.theme--documenter-dark .select.is-fullwidth select{width:100%}html.theme--documenter-dark .select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}html.theme--documenter-dark .select.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .select.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .select.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}html.theme--documenter-dark .file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:hover .file-cta,html.theme--documenter-dark .file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:focus .file-cta,html.theme--documenter-dark .file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}html.theme--documenter-dark .file.is-white:active .file-cta,html.theme--documenter-dark .file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:hover .file-cta,html.theme--documenter-dark .file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:focus .file-cta,html.theme--documenter-dark .file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}html.theme--documenter-dark .file.is-black:active .file-cta,html.theme--documenter-dark .file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-light .file-cta{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:hover .file-cta,html.theme--documenter-dark .file.is-light.is-hovered .file-cta{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:focus .file-cta,html.theme--documenter-dark .file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(236,240,241,0.25);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:active .file-cta,html.theme--documenter-dark .file.is-light.is-active .file-cta{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-dark .file-cta,html.theme--documenter-dark .content kbd.file .file-cta{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:hover .file-cta,html.theme--documenter-dark .content kbd.file:hover .file-cta,html.theme--documenter-dark .file.is-dark.is-hovered .file-cta,html.theme--documenter-dark .content kbd.file.is-hovered .file-cta{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:focus .file-cta,html.theme--documenter-dark .content kbd.file:focus .file-cta,html.theme--documenter-dark .file.is-dark.is-focused .file-cta,html.theme--documenter-dark .content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(40,47,47,0.25);color:#fff}html.theme--documenter-dark .file.is-dark:active .file-cta,html.theme--documenter-dark .content kbd.file:active .file-cta,html.theme--documenter-dark .file.is-dark.is-active .file-cta,html.theme--documenter-dark .content kbd.file.is-active .file-cta{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink .file-cta{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:hover .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:hover .file-cta,html.theme--documenter-dark .file.is-primary.is-hovered .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:focus .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:focus .file-cta,html.theme--documenter-dark .file.is-primary.is-focused .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(55,90,127,0.25);color:#fff}html.theme--documenter-dark .file.is-primary:active .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:active .file-cta,html.theme--documenter-dark .file.is-primary.is-active .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link .file-cta{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:hover .file-cta,html.theme--documenter-dark .file.is-link.is-hovered .file-cta{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:focus .file-cta,html.theme--documenter-dark .file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(26,188,156,0.25);color:#fff}html.theme--documenter-dark .file.is-link:active .file-cta,html.theme--documenter-dark .file.is-link.is-active .file-cta{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info .file-cta{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:hover .file-cta,html.theme--documenter-dark .file.is-info.is-hovered .file-cta{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:focus .file-cta,html.theme--documenter-dark .file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(2,76,125,0.25);color:#fff}html.theme--documenter-dark .file.is-info:active .file-cta,html.theme--documenter-dark .file.is-info.is-active .file-cta{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success .file-cta{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:hover .file-cta,html.theme--documenter-dark .file.is-success.is-hovered .file-cta{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:focus .file-cta,html.theme--documenter-dark .file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(0,132,56,0.25);color:#fff}html.theme--documenter-dark .file.is-success:active .file-cta,html.theme--documenter-dark .file.is-success.is-active .file-cta{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning .file-cta{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:hover .file-cta,html.theme--documenter-dark .file.is-warning.is-hovered .file-cta{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:focus .file-cta,html.theme--documenter-dark .file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(173,129,0,0.25);color:#fff}html.theme--documenter-dark .file.is-warning:active .file-cta,html.theme--documenter-dark .file.is-warning.is-active .file-cta{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger .file-cta{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:hover .file-cta,html.theme--documenter-dark .file.is-danger.is-hovered .file-cta{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:focus .file-cta,html.theme--documenter-dark .file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(158,27,13,0.25);color:#fff}html.theme--documenter-dark .file.is-danger:active .file-cta,html.theme--documenter-dark .file.is-danger.is-active .file-cta{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}html.theme--documenter-dark .file.is-normal{font-size:1rem}html.theme--documenter-dark .file.is-medium{font-size:1.25rem}html.theme--documenter-dark .file.is-medium .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-large{font-size:1.5rem}html.theme--documenter-dark .file.is-large .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .file.has-name.is-empty .file-cta{border-radius:.4em}html.theme--documenter-dark .file.has-name.is-empty .file-name{display:none}html.theme--documenter-dark .file.is-boxed .file-label{flex-direction:column}html.theme--documenter-dark .file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}html.theme--documenter-dark .file.is-boxed .file-name{border-width:0 1px 1px}html.theme--documenter-dark .file.is-boxed .file-icon{height:1.5em;width:1.5em}html.theme--documenter-dark .file.is-boxed .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-boxed.is-small .file-icon .fa,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}html.theme--documenter-dark .file.is-boxed.is-medium .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.is-boxed.is-large .file-icon .fa{font-size:35px}html.theme--documenter-dark .file.is-boxed.has-name .file-cta{border-radius:.4em .4em 0 0}html.theme--documenter-dark .file.is-boxed.has-name .file-name{border-radius:0 0 .4em .4em;border-width:0 1px 1px}html.theme--documenter-dark .file.is-centered{justify-content:center}html.theme--documenter-dark .file.is-fullwidth .file-label{width:100%}html.theme--documenter-dark .file.is-fullwidth .file-name{flex-grow:1;max-width:none}html.theme--documenter-dark .file.is-right{justify-content:flex-end}html.theme--documenter-dark .file.is-right .file-cta{border-radius:0 .4em .4em 0}html.theme--documenter-dark .file.is-right .file-name{border-radius:.4em 0 0 .4em;border-width:1px 0 1px 1px;order:-1}html.theme--documenter-dark .file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}html.theme--documenter-dark .file-label:hover .file-cta{background-color:#232829;color:#f2f2f2}html.theme--documenter-dark .file-label:hover .file-name{border-color:#596668}html.theme--documenter-dark .file-label:active .file-cta{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .file-label:active .file-name{border-color:#535f61}html.theme--documenter-dark .file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-radius:.4em;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}html.theme--documenter-dark .file-cta{background-color:#282f2f;color:#fff}html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}html.theme--documenter-dark .file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}html.theme--documenter-dark .file-icon .fa{font-size:14px}html.theme--documenter-dark .label{color:#f2f2f2;display:block;font-size:1rem;font-weight:700}html.theme--documenter-dark .label:not(:last-child){margin-bottom:0.5em}html.theme--documenter-dark .label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}html.theme--documenter-dark .label.is-medium{font-size:1.25rem}html.theme--documenter-dark .label.is-large{font-size:1.5rem}html.theme--documenter-dark .help{display:block;font-size:.75rem;margin-top:0.25rem}html.theme--documenter-dark .help.is-white{color:#fff}html.theme--documenter-dark .help.is-black{color:#0a0a0a}html.theme--documenter-dark .help.is-light{color:#ecf0f1}html.theme--documenter-dark .help.is-dark,html.theme--documenter-dark .content kbd.help{color:#282f2f}html.theme--documenter-dark .help.is-primary,html.theme--documenter-dark .docstring>section>a.help.docs-sourcelink{color:#375a7f}html.theme--documenter-dark .help.is-link{color:#1abc9c}html.theme--documenter-dark .help.is-info{color:#024c7d}html.theme--documenter-dark .help.is-success{color:#008438}html.theme--documenter-dark .help.is-warning{color:#ad8100}html.theme--documenter-dark .help.is-danger{color:#9e1b0d}html.theme--documenter-dark .field:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.has-addons{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.has-addons .control:not(:last-child){margin-right:-1px}html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .button,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]){z-index:3}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}html.theme--documenter-dark .field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.has-addons.has-addons-centered{justify-content:center}html.theme--documenter-dark .field.has-addons.has-addons-right{justify-content:flex-end}html.theme--documenter-dark .field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .field.is-grouped{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.is-grouped>.control{flex-shrink:0}html.theme--documenter-dark .field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.is-grouped.is-grouped-centered{justify-content:center}html.theme--documenter-dark .field.is-grouped.is-grouped-right{justify-content:flex-end}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline{flex-wrap:wrap}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:last-child,html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field.is-horizontal{display:flex}}html.theme--documenter-dark .field-label .label{font-size:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}html.theme--documenter-dark .field-label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-normal{padding-top:0.375em}html.theme--documenter-dark .field-label.is-medium{font-size:1.25rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-large{font-size:1.5rem;padding-top:0.375em}}html.theme--documenter-dark .field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}html.theme--documenter-dark .field-body .field{margin-bottom:0}html.theme--documenter-dark .field-body>.field{flex-shrink:1}html.theme--documenter-dark .field-body>.field:not(.is-narrow){flex-grow:1}html.theme--documenter-dark .field-body>.field:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}html.theme--documenter-dark .control.has-icons-left .input:focus~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-left .select:focus~.icon,html.theme--documenter-dark .control.has-icons-right .input:focus~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-right .select:focus~.icon{color:#282f2f}html.theme--documenter-dark .control.has-icons-left .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-small~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-small~.icon{font-size:.75rem}html.theme--documenter-dark .control.has-icons-left .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}html.theme--documenter-dark .control.has-icons-left .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-large~.icon{font-size:1.5rem}html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon{color:#5e6d6f;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}html.theme--documenter-dark .control.has-icons-left .input,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input,html.theme--documenter-dark .control.has-icons-left .select select{padding-left:2.5em}html.theme--documenter-dark .control.has-icons-left .icon.is-left{left:0}html.theme--documenter-dark .control.has-icons-right .input,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input,html.theme--documenter-dark .control.has-icons-right .select select{padding-right:2.5em}html.theme--documenter-dark .control.has-icons-right .icon.is-right{right:0}html.theme--documenter-dark .control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}html.theme--documenter-dark .control.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .control.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .control.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .breadcrumb{font-size:1rem;white-space:nowrap}html.theme--documenter-dark .breadcrumb a{align-items:center;color:#1abc9c;display:flex;justify-content:center;padding:0 .75em}html.theme--documenter-dark .breadcrumb a:hover{color:#1dd2af}html.theme--documenter-dark .breadcrumb li{align-items:center;display:flex}html.theme--documenter-dark .breadcrumb li:first-child a{padding-left:0}html.theme--documenter-dark .breadcrumb li.is-active a{color:#f2f2f2;cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb li+li::before{color:#8c9b9d;content:"\0002f"}html.theme--documenter-dark .breadcrumb ul,html.theme--documenter-dark .breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .breadcrumb .icon:first-child{margin-right:.5em}html.theme--documenter-dark .breadcrumb .icon:last-child{margin-left:.5em}html.theme--documenter-dark .breadcrumb.is-centered ol,html.theme--documenter-dark .breadcrumb.is-centered ul{justify-content:center}html.theme--documenter-dark .breadcrumb.is-right ol,html.theme--documenter-dark .breadcrumb.is-right ul{justify-content:flex-end}html.theme--documenter-dark .breadcrumb.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}html.theme--documenter-dark .breadcrumb.is-medium{font-size:1.25rem}html.theme--documenter-dark .breadcrumb.is-large{font-size:1.5rem}html.theme--documenter-dark .breadcrumb.has-arrow-separator li+li::before{content:"\02192"}html.theme--documenter-dark .breadcrumb.has-bullet-separator li+li::before{content:"\02022"}html.theme--documenter-dark .breadcrumb.has-dot-separator li+li::before{content:"\000b7"}html.theme--documenter-dark .breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}html.theme--documenter-dark .card{background-color:#fff;border-radius:.25rem;box-shadow:#171717;color:#fff;max-width:100%;position:relative}html.theme--documenter-dark .card-footer:first-child,html.theme--documenter-dark .card-content:first-child,html.theme--documenter-dark .card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-footer:last-child,html.theme--documenter-dark .card-content:last-child,html.theme--documenter-dark .card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}html.theme--documenter-dark .card-header-title{align-items:center;color:#f2f2f2;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}html.theme--documenter-dark .card-header-title.is-centered{justify-content:center}html.theme--documenter-dark .card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}html.theme--documenter-dark .card-image{display:block;position:relative}html.theme--documenter-dark .card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-content{background-color:rgba(0,0,0,0);padding:1.5rem}html.theme--documenter-dark .card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}html.theme--documenter-dark .card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}html.theme--documenter-dark .card-footer-item:not(:last-child){border-right:1px solid #ededed}html.theme--documenter-dark .card .media:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .dropdown{display:inline-flex;position:relative;vertical-align:top}html.theme--documenter-dark .dropdown.is-active .dropdown-menu,html.theme--documenter-dark .dropdown.is-hoverable:hover .dropdown-menu{display:block}html.theme--documenter-dark .dropdown.is-right .dropdown-menu{left:auto;right:0}html.theme--documenter-dark .dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}html.theme--documenter-dark .dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .dropdown-content{background-color:#282f2f;border-radius:.4em;box-shadow:#171717;padding-bottom:.5rem;padding-top:.5rem}html.theme--documenter-dark .dropdown-item{color:#fff;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}html.theme--documenter-dark a.dropdown-item,html.theme--documenter-dark button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}html.theme--documenter-dark a.dropdown-item:hover,html.theme--documenter-dark button.dropdown-item:hover{background-color:#282f2f;color:#0a0a0a}html.theme--documenter-dark a.dropdown-item.is-active,html.theme--documenter-dark button.dropdown-item.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}html.theme--documenter-dark .level{align-items:center;justify-content:space-between}html.theme--documenter-dark .level code{border-radius:.4em}html.theme--documenter-dark .level img{display:inline-block;vertical-align:top}html.theme--documenter-dark .level.is-mobile{display:flex}html.theme--documenter-dark .level.is-mobile .level-left,html.theme--documenter-dark .level.is-mobile .level-right{display:flex}html.theme--documenter-dark .level.is-mobile .level-left+.level-right{margin-top:0}html.theme--documenter-dark .level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level{display:flex}html.theme--documenter-dark .level>.level-item:not(.is-narrow){flex-grow:1}}html.theme--documenter-dark .level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}html.theme--documenter-dark .level-item .title,html.theme--documenter-dark .level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){html.theme--documenter-dark .level-item:not(:last-child){margin-bottom:.75rem}}html.theme--documenter-dark .level-left,html.theme--documenter-dark .level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .level-left .level-item.is-flexible,html.theme--documenter-dark .level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left .level-item:not(:last-child),html.theme--documenter-dark .level-right .level-item:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){html.theme--documenter-dark .level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left{display:flex}}html.theme--documenter-dark .level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-right{display:flex}}html.theme--documenter-dark .media{align-items:flex-start;display:flex;text-align:inherit}html.theme--documenter-dark .media .content:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .media .media{border-top:1px solid rgba(94,109,111,0.5);display:flex;padding-top:.75rem}html.theme--documenter-dark .media .media .content:not(:last-child),html.theme--documenter-dark .media .media .control:not(:last-child){margin-bottom:.5rem}html.theme--documenter-dark .media .media .media{padding-top:.5rem}html.theme--documenter-dark .media .media .media+.media{margin-top:.5rem}html.theme--documenter-dark .media+.media{border-top:1px solid rgba(94,109,111,0.5);margin-top:1rem;padding-top:1rem}html.theme--documenter-dark .media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}html.theme--documenter-dark .media-left,html.theme--documenter-dark .media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .media-left{margin-right:1rem}html.theme--documenter-dark .media-right{margin-left:1rem}html.theme--documenter-dark .media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .media-content{overflow-x:auto}}html.theme--documenter-dark .menu{font-size:1rem}html.theme--documenter-dark .menu.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}html.theme--documenter-dark .menu.is-medium{font-size:1.25rem}html.theme--documenter-dark .menu.is-large{font-size:1.5rem}html.theme--documenter-dark .menu-list{line-height:1.25}html.theme--documenter-dark .menu-list a{border-radius:3px;color:#fff;display:block;padding:0.5em 0.75em}html.theme--documenter-dark .menu-list a:hover{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .menu-list a.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .menu-list li ul{border-left:1px solid #5e6d6f;margin:.75em;padding-left:.75em}html.theme--documenter-dark .menu-label{color:#fff;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}html.theme--documenter-dark .menu-label:not(:first-child){margin-top:1em}html.theme--documenter-dark .menu-label:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .message{background-color:#282f2f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .message strong{color:currentColor}html.theme--documenter-dark .message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .message.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}html.theme--documenter-dark .message.is-medium{font-size:1.25rem}html.theme--documenter-dark .message.is-large{font-size:1.5rem}html.theme--documenter-dark .message.is-white{background-color:#fff}html.theme--documenter-dark .message.is-white .message-header{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .message.is-white .message-body{border-color:#fff}html.theme--documenter-dark .message.is-black{background-color:#fafafa}html.theme--documenter-dark .message.is-black .message-header{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .message.is-black .message-body{border-color:#0a0a0a}html.theme--documenter-dark .message.is-light{background-color:#f9fafb}html.theme--documenter-dark .message.is-light .message-header{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .message.is-light .message-body{border-color:#ecf0f1}html.theme--documenter-dark .message.is-dark,html.theme--documenter-dark .content kbd.message{background-color:#f9fafa}html.theme--documenter-dark .message.is-dark .message-header,html.theme--documenter-dark .content kbd.message .message-header{background-color:#282f2f;color:#fff}html.theme--documenter-dark .message.is-dark .message-body,html.theme--documenter-dark .content kbd.message .message-body{border-color:#282f2f}html.theme--documenter-dark .message.is-primary,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink{background-color:#f1f5f9}html.theme--documenter-dark .message.is-primary .message-header,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-header{background-color:#375a7f;color:#fff}html.theme--documenter-dark .message.is-primary .message-body,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-body{border-color:#375a7f;color:#4d7eb2}html.theme--documenter-dark .message.is-link{background-color:#edfdf9}html.theme--documenter-dark .message.is-link .message-header{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .message.is-link .message-body{border-color:#1abc9c;color:#15987e}html.theme--documenter-dark .message.is-info{background-color:#ebf7ff}html.theme--documenter-dark .message.is-info .message-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .message.is-info .message-body{border-color:#024c7d;color:#0e9dfb}html.theme--documenter-dark .message.is-success{background-color:#ebfff3}html.theme--documenter-dark .message.is-success .message-header{background-color:#008438;color:#fff}html.theme--documenter-dark .message.is-success .message-body{border-color:#008438;color:#00eb64}html.theme--documenter-dark .message.is-warning{background-color:#fffaeb}html.theme--documenter-dark .message.is-warning .message-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .message.is-warning .message-body{border-color:#ad8100;color:#d19c00}html.theme--documenter-dark .message.is-danger{background-color:#fdeeec}html.theme--documenter-dark .message.is-danger .message-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .message.is-danger .message-body{border-color:#9e1b0d;color:#ec311d}html.theme--documenter-dark .message-header{align-items:center;background-color:#fff;border-radius:.4em .4em 0 0;color:rgba(0,0,0,0.7);display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}html.theme--documenter-dark .message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}html.theme--documenter-dark .message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}html.theme--documenter-dark .message-body{border-color:#5e6d6f;border-radius:.4em;border-style:solid;border-width:0 0 0 4px;color:#fff;padding:1.25em 1.5em}html.theme--documenter-dark .message-body code,html.theme--documenter-dark .message-body pre{background-color:#fff}html.theme--documenter-dark .message-body pre code{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}html.theme--documenter-dark .modal.is-active{display:flex}html.theme--documenter-dark .modal-background{background-color:rgba(10,10,10,0.86)}html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}html.theme--documenter-dark .modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}html.theme--documenter-dark .modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}html.theme--documenter-dark .modal-card-head,html.theme--documenter-dark .modal-card-foot{align-items:center;background-color:#282f2f;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}html.theme--documenter-dark .modal-card-head{border-bottom:1px solid #5e6d6f;border-top-left-radius:8px;border-top-right-radius:8px}html.theme--documenter-dark .modal-card-title{color:#f2f2f2;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}html.theme--documenter-dark .modal-card-foot{border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid #5e6d6f}html.theme--documenter-dark .modal-card-foot .button:not(:last-child){margin-right:.5em}html.theme--documenter-dark .modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}html.theme--documenter-dark .navbar{background-color:#375a7f;min-height:4rem;position:relative;z-index:30}html.theme--documenter-dark .navbar.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-white .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}html.theme--documenter-dark .navbar.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-black .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}html.theme--documenter-dark .navbar.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-light .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}}html.theme--documenter-dark .navbar.is-dark,html.theme--documenter-dark .content kbd.navbar{background-color:#282f2f;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-burger,html.theme--documenter-dark .content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-dark .navbar-start>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-end>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#282f2f;color:#fff}}html.theme--documenter-dark .navbar.is-primary,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-burger,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-primary .navbar-start>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-end>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#375a7f;color:#fff}}html.theme--documenter-dark .navbar.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-link .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c;color:#fff}}html.theme--documenter-dark .navbar.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-info .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#024c7d;color:#fff}}html.theme--documenter-dark .navbar.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-success .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#008438;color:#fff}}html.theme--documenter-dark .navbar.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-warning .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ad8100;color:#fff}}html.theme--documenter-dark .navbar.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-danger .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#9e1b0d;color:#fff}}html.theme--documenter-dark .navbar>.container{align-items:stretch;display:flex;min-height:4rem;width:100%}html.theme--documenter-dark .navbar.has-shadow{box-shadow:0 2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-bottom,html.theme--documenter-dark .navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-top{top:0}html.theme--documenter-dark html.has-navbar-fixed-top,html.theme--documenter-dark body.has-navbar-fixed-top{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom,html.theme--documenter-dark body.has-navbar-fixed-bottom{padding-bottom:4rem}html.theme--documenter-dark .navbar-brand,html.theme--documenter-dark .navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:4rem}html.theme--documenter-dark .navbar-brand a.navbar-item:focus,html.theme--documenter-dark .navbar-brand a.navbar-item:hover{background-color:transparent}html.theme--documenter-dark .navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}html.theme--documenter-dark .navbar-burger{color:#fff;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:4rem;position:relative;width:4rem;margin-left:auto}html.theme--documenter-dark .navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}html.theme--documenter-dark .navbar-burger span:nth-child(1){top:calc(50% - 6px)}html.theme--documenter-dark .navbar-burger span:nth-child(2){top:calc(50% - 1px)}html.theme--documenter-dark .navbar-burger span:nth-child(3){top:calc(50% + 4px)}html.theme--documenter-dark .navbar-burger:hover{background-color:rgba(0,0,0,0.05)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(2){opacity:0}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}html.theme--documenter-dark .navbar-menu{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{color:#fff;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}html.theme--documenter-dark .navbar-item .icon:only-child,html.theme--documenter-dark .navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}html.theme--documenter-dark a.navbar-item,html.theme--documenter-dark .navbar-link{cursor:pointer}html.theme--documenter-dark a.navbar-item:focus,html.theme--documenter-dark a.navbar-item:focus-within,html.theme--documenter-dark a.navbar-item:hover,html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link:focus,html.theme--documenter-dark .navbar-link:focus-within,html.theme--documenter-dark .navbar-link:hover,html.theme--documenter-dark .navbar-link.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-item{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .navbar-item img{max-height:1.75rem}html.theme--documenter-dark .navbar-item.has-dropdown{padding:0}html.theme--documenter-dark .navbar-item.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-item.is-tab{border-bottom:1px solid transparent;min-height:4rem;padding-bottom:calc(0.5rem - 1px)}html.theme--documenter-dark .navbar-item.is-tab:focus,html.theme--documenter-dark .navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c}html.theme--documenter-dark .navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c;border-bottom-style:solid;border-bottom-width:3px;color:#1abc9c;padding-bottom:calc(0.5rem - 3px)}html.theme--documenter-dark .navbar-content{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-link:not(.is-arrowless){padding-right:2.5em}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after{border-color:#fff;margin-top:-0.375em;right:1.125em}html.theme--documenter-dark .navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}html.theme--documenter-dark .navbar-divider{background-color:rgba(0,0,0,0.2);border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar>.container{display:block}html.theme--documenter-dark .navbar-brand .navbar-item,html.theme--documenter-dark .navbar-tabs .navbar-item{align-items:center;display:flex}html.theme--documenter-dark .navbar-link::after{display:none}html.theme--documenter-dark .navbar-menu{background-color:#375a7f;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}html.theme--documenter-dark .navbar-menu.is-active{display:block}html.theme--documenter-dark .navbar.is-fixed-bottom-touch,html.theme--documenter-dark .navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-touch{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-touch{top:0}html.theme--documenter-dark .navbar.is-fixed-top .navbar-menu,html.theme--documenter-dark .navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 4rem);overflow:auto}html.theme--documenter-dark html.has-navbar-fixed-top-touch,html.theme--documenter-dark body.has-navbar-fixed-top-touch{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-touch,html.theme--documenter-dark body.has-navbar-fixed-bottom-touch{padding-bottom:4rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar,html.theme--documenter-dark .navbar-menu,html.theme--documenter-dark .navbar-start,html.theme--documenter-dark .navbar-end{align-items:stretch;display:flex}html.theme--documenter-dark .navbar{min-height:4rem}html.theme--documenter-dark .navbar.is-spaced{padding:1rem 2rem}html.theme--documenter-dark .navbar.is-spaced .navbar-start,html.theme--documenter-dark .navbar.is-spaced .navbar-end{align-items:center}html.theme--documenter-dark .navbar.is-spaced a.navbar-item,html.theme--documenter-dark .navbar.is-spaced .navbar-link{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent a.navbar-item:hover,html.theme--documenter-dark .navbar.is-transparent a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-transparent .navbar-link:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-link:hover,html.theme--documenter-dark .navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-burger{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{align-items:center;display:flex}html.theme--documenter-dark .navbar-item.has-dropdown{align-items:stretch}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:1px solid rgba(0,0,0,0.2);border-radius:8px 8px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}html.theme--documenter-dark .navbar-menu{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .navbar-start{justify-content:flex-start;margin-right:auto}html.theme--documenter-dark .navbar-end{justify-content:flex-end;margin-left:auto}html.theme--documenter-dark .navbar-dropdown{background-color:#375a7f;border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid rgba(0,0,0,0.2);box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}html.theme--documenter-dark .navbar-dropdown a.navbar-item{padding-right:3rem}html.theme--documenter-dark .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}.navbar.is-spaced html.theme--documenter-dark .navbar-dropdown,html.theme--documenter-dark .navbar-dropdown.is-boxed{border-radius:8px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}html.theme--documenter-dark .navbar-dropdown.is-right{left:auto;right:0}html.theme--documenter-dark .navbar-divider{display:block}html.theme--documenter-dark .navbar>.container .navbar-brand,html.theme--documenter-dark .container>.navbar .navbar-brand{margin-left:-.75rem}html.theme--documenter-dark .navbar>.container .navbar-menu,html.theme--documenter-dark .container>.navbar .navbar-menu{margin-right:-.75rem}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop,html.theme--documenter-dark .navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-desktop{top:0}html.theme--documenter-dark html.has-navbar-fixed-top-desktop,html.theme--documenter-dark body.has-navbar-fixed-top-desktop{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-desktop,html.theme--documenter-dark body.has-navbar-fixed-bottom-desktop{padding-bottom:4rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-top,html.theme--documenter-dark body.has-spaced-navbar-fixed-top{padding-top:6rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-bottom,html.theme--documenter-dark body.has-spaced-navbar-fixed-bottom{padding-bottom:6rem}html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link.is-active{color:#1abc9c}html.theme--documenter-dark a.navbar-item.is-active:not(:focus):not(:hover),html.theme--documenter-dark .navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}html.theme--documenter-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown.is-active .navbar-link{background-color:rgba(0,0,0,0)}}html.theme--documenter-dark .hero.is-fullheight-with-navbar{min-height:calc(100vh - 4rem)}html.theme--documenter-dark .pagination{font-size:1rem;margin:-.25rem}html.theme--documenter-dark .pagination.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}html.theme--documenter-dark .pagination.is-medium{font-size:1.25rem}html.theme--documenter-dark .pagination.is-large{font-size:1.5rem}html.theme--documenter-dark .pagination.is-rounded .pagination-previous,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,html.theme--documenter-dark .pagination.is-rounded .pagination-next,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}html.theme--documenter-dark .pagination.is-rounded .pagination-link,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}html.theme--documenter-dark .pagination,html.theme--documenter-dark .pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link{border-color:#5e6d6f;color:#1abc9c;min-width:2.5em}html.theme--documenter-dark .pagination-previous:hover,html.theme--documenter-dark .pagination-next:hover,html.theme--documenter-dark .pagination-link:hover{border-color:#8c9b9d;color:#1dd2af}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus{border-color:#8c9b9d}html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-previous.is-disabled,html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-next.is-disabled,html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-link.is-disabled{background-color:#5e6d6f;border-color:#5e6d6f;box-shadow:none;color:#fff;opacity:0.5}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}html.theme--documenter-dark .pagination-link.is-current{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .pagination-ellipsis{color:#8c9b9d;pointer-events:none}html.theme--documenter-dark .pagination-list{flex-wrap:wrap}html.theme--documenter-dark .pagination-list li{list-style:none}@media screen and (max-width: 768px){html.theme--documenter-dark .pagination{flex-wrap:wrap}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination-previous{order:2}html.theme--documenter-dark .pagination-next{order:3}html.theme--documenter-dark .pagination{justify-content:space-between;margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination.is-centered .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-centered .pagination-list{justify-content:center;order:2}html.theme--documenter-dark .pagination.is-centered .pagination-next{order:3}html.theme--documenter-dark .pagination.is-right .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-right .pagination-next{order:2}html.theme--documenter-dark .pagination.is-right .pagination-list{justify-content:flex-end;order:3}}html.theme--documenter-dark .panel{border-radius:8px;box-shadow:#171717;font-size:1rem}html.theme--documenter-dark .panel:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}html.theme--documenter-dark .panel.is-white .panel-block.is-active .panel-icon{color:#fff}html.theme--documenter-dark .panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}html.theme--documenter-dark .panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}html.theme--documenter-dark .panel.is-light .panel-heading{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .panel.is-light .panel-tabs a.is-active{border-bottom-color:#ecf0f1}html.theme--documenter-dark .panel.is-light .panel-block.is-active .panel-icon{color:#ecf0f1}html.theme--documenter-dark .panel.is-dark .panel-heading,html.theme--documenter-dark .content kbd.panel .panel-heading{background-color:#282f2f;color:#fff}html.theme--documenter-dark .panel.is-dark .panel-tabs a.is-active,html.theme--documenter-dark .content kbd.panel .panel-tabs a.is-active{border-bottom-color:#282f2f}html.theme--documenter-dark .panel.is-dark .panel-block.is-active .panel-icon,html.theme--documenter-dark .content kbd.panel .panel-block.is-active .panel-icon{color:#282f2f}html.theme--documenter-dark .panel.is-primary .panel-heading,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#375a7f;color:#fff}html.theme--documenter-dark .panel.is-primary .panel-tabs a.is-active,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#375a7f}html.theme--documenter-dark .panel.is-primary .panel-block.is-active .panel-icon,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#375a7f}html.theme--documenter-dark .panel.is-link .panel-heading{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .panel.is-link .panel-tabs a.is-active{border-bottom-color:#1abc9c}html.theme--documenter-dark .panel.is-link .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel.is-info .panel-heading{background-color:#024c7d;color:#fff}html.theme--documenter-dark .panel.is-info .panel-tabs a.is-active{border-bottom-color:#024c7d}html.theme--documenter-dark .panel.is-info .panel-block.is-active .panel-icon{color:#024c7d}html.theme--documenter-dark .panel.is-success .panel-heading{background-color:#008438;color:#fff}html.theme--documenter-dark .panel.is-success .panel-tabs a.is-active{border-bottom-color:#008438}html.theme--documenter-dark .panel.is-success .panel-block.is-active .panel-icon{color:#008438}html.theme--documenter-dark .panel.is-warning .panel-heading{background-color:#ad8100;color:#fff}html.theme--documenter-dark .panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ad8100}html.theme--documenter-dark .panel.is-warning .panel-block.is-active .panel-icon{color:#ad8100}html.theme--documenter-dark .panel.is-danger .panel-heading{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .panel.is-danger .panel-tabs a.is-active{border-bottom-color:#9e1b0d}html.theme--documenter-dark .panel.is-danger .panel-block.is-active .panel-icon{color:#9e1b0d}html.theme--documenter-dark .panel-tabs:not(:last-child),html.theme--documenter-dark .panel-block:not(:last-child){border-bottom:1px solid #ededed}html.theme--documenter-dark .panel-heading{background-color:#343c3d;border-radius:8px 8px 0 0;color:#f2f2f2;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}html.theme--documenter-dark .panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}html.theme--documenter-dark .panel-tabs a{border-bottom:1px solid #5e6d6f;margin-bottom:-1px;padding:0.5em}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#343c3d;color:#17a689}html.theme--documenter-dark .panel-list a{color:#fff}html.theme--documenter-dark .panel-list a:hover{color:#1abc9c}html.theme--documenter-dark .panel-block{align-items:center;color:#f2f2f2;display:flex;justify-content:flex-start;padding:0.5em 0.75em}html.theme--documenter-dark .panel-block input[type="checkbox"]{margin-right:.75em}html.theme--documenter-dark .panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}html.theme--documenter-dark .panel-block.is-wrapped{flex-wrap:wrap}html.theme--documenter-dark .panel-block.is-active{border-left-color:#1abc9c;color:#17a689}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel-block:last-child{border-bottom-left-radius:8px;border-bottom-right-radius:8px}html.theme--documenter-dark a.panel-block,html.theme--documenter-dark label.panel-block{cursor:pointer}html.theme--documenter-dark a.panel-block:hover,html.theme--documenter-dark label.panel-block:hover{background-color:#282f2f}html.theme--documenter-dark .panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#fff;margin-right:.75em}html.theme--documenter-dark .panel-icon .fa{font-size:inherit;line-height:inherit}html.theme--documenter-dark .tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}html.theme--documenter-dark .tabs a{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;color:#fff;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}html.theme--documenter-dark .tabs a:hover{border-bottom-color:#f2f2f2;color:#f2f2f2}html.theme--documenter-dark .tabs li{display:block}html.theme--documenter-dark .tabs li.is-active a{border-bottom-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .tabs ul{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}html.theme--documenter-dark .tabs ul.is-left{padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}html.theme--documenter-dark .tabs .icon:first-child{margin-right:.5em}html.theme--documenter-dark .tabs .icon:last-child{margin-left:.5em}html.theme--documenter-dark .tabs.is-centered ul{justify-content:center}html.theme--documenter-dark .tabs.is-right ul{justify-content:flex-end}html.theme--documenter-dark .tabs.is-boxed a{border:1px solid transparent;border-radius:.4em .4em 0 0}html.theme--documenter-dark .tabs.is-boxed a:hover{background-color:#282f2f;border-bottom-color:#5e6d6f}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#fff;border-color:#5e6d6f;border-bottom-color:rgba(0,0,0,0) !important}html.theme--documenter-dark .tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .tabs.is-toggle a{border-color:#5e6d6f;border-style:solid;border-width:1px;margin-bottom:0;position:relative}html.theme--documenter-dark .tabs.is-toggle a:hover{background-color:#282f2f;border-color:#8c9b9d;z-index:2}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .tabs.is-toggle li:first-child a{border-top-left-radius:.4em;border-bottom-left-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li:last-child a{border-top-right-radius:.4em;border-bottom-right-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li.is-active a{background-color:#1abc9c;border-color:#1abc9c;color:#fff;z-index:1}html.theme--documenter-dark .tabs.is-toggle ul{border-bottom:none}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}html.theme--documenter-dark .tabs.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}html.theme--documenter-dark .tabs.is-medium{font-size:1.25rem}html.theme--documenter-dark .tabs.is-large{font-size:1.5rem}html.theme--documenter-dark .column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>html.theme--documenter-dark .column.is-narrow{flex:none;width:unset}.columns.is-mobile>html.theme--documenter-dark .column.is-full{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-half{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-half{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-0{flex:none;width:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-0{margin-left:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-3{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-3{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-6{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-6{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-9{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-9{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-12{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){html.theme--documenter-dark .column.is-narrow-mobile{flex:none;width:unset}html.theme--documenter-dark .column.is-full-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-mobile{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-mobile{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-mobile{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-mobile{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-mobile{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-mobile{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-mobile{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-mobile{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-mobile{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-mobile{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-mobile{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-mobile{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-mobile{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-mobile{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-mobile{margin-left:80%}html.theme--documenter-dark .column.is-0-mobile{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-mobile{margin-left:0%}html.theme--documenter-dark .column.is-1-mobile{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-mobile{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-mobile{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-mobile{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-mobile{margin-left:25%}html.theme--documenter-dark .column.is-4-mobile{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-mobile{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-mobile{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-mobile{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-mobile{margin-left:50%}html.theme--documenter-dark .column.is-7-mobile{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-mobile{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-mobile{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-mobile{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-mobile{margin-left:75%}html.theme--documenter-dark .column.is-10-mobile{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-mobile{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-mobile{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-mobile{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .column.is-narrow,html.theme--documenter-dark .column.is-narrow-tablet{flex:none;width:unset}html.theme--documenter-dark .column.is-full,html.theme--documenter-dark .column.is-full-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters,html.theme--documenter-dark .column.is-three-quarters-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds,html.theme--documenter-dark .column.is-two-thirds-tablet{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half,html.theme--documenter-dark .column.is-half-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third,html.theme--documenter-dark .column.is-one-third-tablet{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter,html.theme--documenter-dark .column.is-one-quarter-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth,html.theme--documenter-dark .column.is-one-fifth-tablet{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths,html.theme--documenter-dark .column.is-two-fifths-tablet{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths,html.theme--documenter-dark .column.is-three-fifths-tablet{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths,html.theme--documenter-dark .column.is-four-fifths-tablet{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters,html.theme--documenter-dark .column.is-offset-three-quarters-tablet{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds,html.theme--documenter-dark .column.is-offset-two-thirds-tablet{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half,html.theme--documenter-dark .column.is-offset-half-tablet{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third,html.theme--documenter-dark .column.is-offset-one-third-tablet{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter,html.theme--documenter-dark .column.is-offset-one-quarter-tablet{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth,html.theme--documenter-dark .column.is-offset-one-fifth-tablet{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths,html.theme--documenter-dark .column.is-offset-two-fifths-tablet{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths,html.theme--documenter-dark .column.is-offset-three-fifths-tablet{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths,html.theme--documenter-dark .column.is-offset-four-fifths-tablet{margin-left:80%}html.theme--documenter-dark .column.is-0,html.theme--documenter-dark .column.is-0-tablet{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0,html.theme--documenter-dark .column.is-offset-0-tablet{margin-left:0%}html.theme--documenter-dark .column.is-1,html.theme--documenter-dark .column.is-1-tablet{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1,html.theme--documenter-dark .column.is-offset-1-tablet{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2,html.theme--documenter-dark .column.is-2-tablet{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2,html.theme--documenter-dark .column.is-offset-2-tablet{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3,html.theme--documenter-dark .column.is-3-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3,html.theme--documenter-dark .column.is-offset-3-tablet{margin-left:25%}html.theme--documenter-dark .column.is-4,html.theme--documenter-dark .column.is-4-tablet{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4,html.theme--documenter-dark .column.is-offset-4-tablet{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5,html.theme--documenter-dark .column.is-5-tablet{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5,html.theme--documenter-dark .column.is-offset-5-tablet{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6,html.theme--documenter-dark .column.is-6-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6,html.theme--documenter-dark .column.is-offset-6-tablet{margin-left:50%}html.theme--documenter-dark .column.is-7,html.theme--documenter-dark .column.is-7-tablet{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7,html.theme--documenter-dark .column.is-offset-7-tablet{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8,html.theme--documenter-dark .column.is-8-tablet{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8,html.theme--documenter-dark .column.is-offset-8-tablet{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9,html.theme--documenter-dark .column.is-9-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9,html.theme--documenter-dark .column.is-offset-9-tablet{margin-left:75%}html.theme--documenter-dark .column.is-10,html.theme--documenter-dark .column.is-10-tablet{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10,html.theme--documenter-dark .column.is-offset-10-tablet{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11,html.theme--documenter-dark .column.is-11-tablet{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11,html.theme--documenter-dark .column.is-offset-11-tablet{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12,html.theme--documenter-dark .column.is-12-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12,html.theme--documenter-dark .column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){html.theme--documenter-dark .column.is-narrow-touch{flex:none;width:unset}html.theme--documenter-dark .column.is-full-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-touch{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-touch{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-touch{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-touch{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-touch{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-touch{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-touch{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-touch{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-touch{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-touch{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-touch{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-touch{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-touch{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-touch{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-touch{margin-left:80%}html.theme--documenter-dark .column.is-0-touch{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-touch{margin-left:0%}html.theme--documenter-dark .column.is-1-touch{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-touch{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-touch{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-touch{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-touch{margin-left:25%}html.theme--documenter-dark .column.is-4-touch{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-touch{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-touch{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-touch{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-touch{margin-left:50%}html.theme--documenter-dark .column.is-7-touch{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-touch{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-touch{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-touch{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-touch{margin-left:75%}html.theme--documenter-dark .column.is-10-touch{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-touch{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-touch{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-touch{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){html.theme--documenter-dark .column.is-narrow-desktop{flex:none;width:unset}html.theme--documenter-dark .column.is-full-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-desktop{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-desktop{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-desktop{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-desktop{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-desktop{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-desktop{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-desktop{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-desktop{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-desktop{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-desktop{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-desktop{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-desktop{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-desktop{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-desktop{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-desktop{margin-left:80%}html.theme--documenter-dark .column.is-0-desktop{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-desktop{margin-left:0%}html.theme--documenter-dark .column.is-1-desktop{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-desktop{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-desktop{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-desktop{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-desktop{margin-left:25%}html.theme--documenter-dark .column.is-4-desktop{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-desktop{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-desktop{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-desktop{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-desktop{margin-left:50%}html.theme--documenter-dark .column.is-7-desktop{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-desktop{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-desktop{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-desktop{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-desktop{margin-left:75%}html.theme--documenter-dark .column.is-10-desktop{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-desktop{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-desktop{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-desktop{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){html.theme--documenter-dark .column.is-narrow-widescreen{flex:none;width:unset}html.theme--documenter-dark .column.is-full-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-widescreen{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-widescreen{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-widescreen{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-widescreen{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-widescreen{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-widescreen{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-widescreen{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-widescreen{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-widescreen{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-widescreen{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-widescreen{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-widescreen{margin-left:80%}html.theme--documenter-dark .column.is-0-widescreen{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-widescreen{margin-left:0%}html.theme--documenter-dark .column.is-1-widescreen{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-widescreen{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-widescreen{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-widescreen{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-4-widescreen{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-widescreen{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-widescreen{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-widescreen{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-7-widescreen{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-widescreen{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-widescreen{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-widescreen{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-10-widescreen{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-widescreen{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-widescreen{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-widescreen{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){html.theme--documenter-dark .column.is-narrow-fullhd{flex:none;width:unset}html.theme--documenter-dark .column.is-full-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-fullhd{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-fullhd{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-fullhd{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-fullhd{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-fullhd{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-fullhd{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-fullhd{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-fullhd{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-fullhd{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-fullhd{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-fullhd{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-fullhd{margin-left:80%}html.theme--documenter-dark .column.is-0-fullhd{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-fullhd{margin-left:0%}html.theme--documenter-dark .column.is-1-fullhd{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-fullhd{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-fullhd{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-fullhd{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-4-fullhd{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-fullhd{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-fullhd{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-fullhd{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-7-fullhd{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-fullhd{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-fullhd{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-fullhd{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-10-fullhd{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-fullhd{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-fullhd{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-fullhd{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-fullhd{margin-left:100%}}html.theme--documenter-dark .columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .columns:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}html.theme--documenter-dark .columns.is-centered{justify-content:center}html.theme--documenter-dark .columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}html.theme--documenter-dark .columns.is-gapless>.column{margin:0;padding:0 !important}html.theme--documenter-dark .columns.is-gapless:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .columns.is-gapless:last-child{margin-bottom:0}html.theme--documenter-dark .columns.is-mobile{display:flex}html.theme--documenter-dark .columns.is-multiline{flex-wrap:wrap}html.theme--documenter-dark .columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-desktop{display:flex}}html.theme--documenter-dark .columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}html.theme--documenter-dark .columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}html.theme--documenter-dark .columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-0-fullhd{--columnGap: 0rem}}html.theme--documenter-dark .columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-1-fullhd{--columnGap: .25rem}}html.theme--documenter-dark .columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-2-fullhd{--columnGap: .5rem}}html.theme--documenter-dark .columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-3-fullhd{--columnGap: .75rem}}html.theme--documenter-dark .columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-4-fullhd{--columnGap: 1rem}}html.theme--documenter-dark .columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}html.theme--documenter-dark .columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}html.theme--documenter-dark .columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}html.theme--documenter-dark .columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-8-fullhd{--columnGap: 2rem}}html.theme--documenter-dark .tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}html.theme--documenter-dark .tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .tile.is-ancestor:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .tile.is-ancestor:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .tile.is-child{margin:0 !important}html.theme--documenter-dark .tile.is-parent{padding:.75rem}html.theme--documenter-dark .tile.is-vertical{flex-direction:column}html.theme--documenter-dark .tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{html.theme--documenter-dark .tile:not(.is-child){display:flex}html.theme--documenter-dark .tile.is-1{flex:none;width:8.33333337%}html.theme--documenter-dark .tile.is-2{flex:none;width:16.66666674%}html.theme--documenter-dark .tile.is-3{flex:none;width:25%}html.theme--documenter-dark .tile.is-4{flex:none;width:33.33333337%}html.theme--documenter-dark .tile.is-5{flex:none;width:41.66666674%}html.theme--documenter-dark .tile.is-6{flex:none;width:50%}html.theme--documenter-dark .tile.is-7{flex:none;width:58.33333337%}html.theme--documenter-dark .tile.is-8{flex:none;width:66.66666674%}html.theme--documenter-dark .tile.is-9{flex:none;width:75%}html.theme--documenter-dark .tile.is-10{flex:none;width:83.33333337%}html.theme--documenter-dark .tile.is-11{flex:none;width:91.66666674%}html.theme--documenter-dark .tile.is-12{flex:none;width:100%}}html.theme--documenter-dark .hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}html.theme--documenter-dark .hero .navbar{background:none}html.theme--documenter-dark .hero .tabs ul{border-bottom:none}html.theme--documenter-dark .hero.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-white strong{color:inherit}html.theme--documenter-dark .hero.is-white .title{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .subtitle{color:rgba(10,10,10,0.9)}html.theme--documenter-dark .hero.is-white .subtitle a:not(.button),html.theme--documenter-dark .hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-white .navbar-menu{background-color:#fff}}html.theme--documenter-dark .hero.is-white .navbar-item,html.theme--documenter-dark .hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}html.theme--documenter-dark .hero.is-white a.navbar-item:hover,html.theme--documenter-dark .hero.is-white a.navbar-item.is-active,html.theme--documenter-dark .hero.is-white .navbar-link:hover,html.theme--documenter-dark .hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}html.theme--documenter-dark .hero.is-white .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}html.theme--documenter-dark .hero.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-black strong{color:inherit}html.theme--documenter-dark .hero.is-black .title{color:#fff}html.theme--documenter-dark .hero.is-black .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-black .subtitle a:not(.button),html.theme--documenter-dark .hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-black .navbar-menu{background-color:#0a0a0a}}html.theme--documenter-dark .hero.is-black .navbar-item,html.theme--documenter-dark .hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-black a.navbar-item:hover,html.theme--documenter-dark .hero.is-black a.navbar-item.is-active,html.theme--documenter-dark .hero.is-black .navbar-link:hover,html.theme--documenter-dark .hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .hero.is-black .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-black .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}html.theme--documenter-dark .hero.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-light strong{color:inherit}html.theme--documenter-dark .hero.is-light .title{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .subtitle{color:rgba(0,0,0,0.9)}html.theme--documenter-dark .hero.is-light .subtitle a:not(.button),html.theme--documenter-dark .hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-light .navbar-menu{background-color:#ecf0f1}}html.theme--documenter-dark .hero.is-light .navbar-item,html.theme--documenter-dark .hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a.navbar-item:hover,html.theme--documenter-dark .hero.is-light a.navbar-item.is-active,html.theme--documenter-dark .hero.is-light .navbar-link:hover,html.theme--documenter-dark .hero.is-light .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}html.theme--documenter-dark .hero.is-light .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-light .tabs li.is-active a{color:#ecf0f1 !important;opacity:1}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .hero.is-light.is-bold{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}}html.theme--documenter-dark .hero.is-dark,html.theme--documenter-dark .content kbd.hero{background-color:#282f2f;color:#fff}html.theme--documenter-dark .hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-dark strong,html.theme--documenter-dark .content kbd.hero strong{color:inherit}html.theme--documenter-dark .hero.is-dark .title,html.theme--documenter-dark .content kbd.hero .title{color:#fff}html.theme--documenter-dark .hero.is-dark .subtitle,html.theme--documenter-dark .content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-dark .subtitle a:not(.button),html.theme--documenter-dark .content kbd.hero .subtitle a:not(.button),html.theme--documenter-dark .hero.is-dark .subtitle strong,html.theme--documenter-dark .content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-dark .navbar-menu,html.theme--documenter-dark .content kbd.hero .navbar-menu{background-color:#282f2f}}html.theme--documenter-dark .hero.is-dark .navbar-item,html.theme--documenter-dark .content kbd.hero .navbar-item,html.theme--documenter-dark .hero.is-dark .navbar-link,html.theme--documenter-dark .content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-dark a.navbar-item:hover,html.theme--documenter-dark .content kbd.hero a.navbar-item:hover,html.theme--documenter-dark .hero.is-dark a.navbar-item.is-active,html.theme--documenter-dark .content kbd.hero a.navbar-item.is-active,html.theme--documenter-dark .hero.is-dark .navbar-link:hover,html.theme--documenter-dark .content kbd.hero .navbar-link:hover,html.theme--documenter-dark .hero.is-dark .navbar-link.is-active,html.theme--documenter-dark .content kbd.hero .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .hero.is-dark .tabs a,html.theme--documenter-dark .content kbd.hero .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-dark .tabs a:hover,html.theme--documenter-dark .content kbd.hero .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-dark .tabs li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs li.is-active a{color:#282f2f !important;opacity:1}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#282f2f}html.theme--documenter-dark .hero.is-dark.is-bold,html.theme--documenter-dark .content kbd.hero.is-bold{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-dark.is-bold .navbar-menu,html.theme--documenter-dark .content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}}html.theme--documenter-dark .hero.is-primary,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-primary strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink strong{color:inherit}html.theme--documenter-dark .hero.is-primary .title,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .title{color:#fff}html.theme--documenter-dark .hero.is-primary .subtitle,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-primary .subtitle a:not(.button),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),html.theme--documenter-dark .hero.is-primary .subtitle strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-primary .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#375a7f}}html.theme--documenter-dark .hero.is-primary .navbar-item,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-item,html.theme--documenter-dark .hero.is-primary .navbar-link,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-primary a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,html.theme--documenter-dark .hero.is-primary a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,html.theme--documenter-dark .hero.is-primary .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link:hover,html.theme--documenter-dark .hero.is-primary .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .hero.is-primary .tabs a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-primary .tabs a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-primary .tabs li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#375a7f !important;opacity:1}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#375a7f}html.theme--documenter-dark .hero.is-primary.is-bold,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-primary.is-bold .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}}html.theme--documenter-dark .hero.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-link strong{color:inherit}html.theme--documenter-dark .hero.is-link .title{color:#fff}html.theme--documenter-dark .hero.is-link .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-link .subtitle a:not(.button),html.theme--documenter-dark .hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-link .navbar-menu{background-color:#1abc9c}}html.theme--documenter-dark .hero.is-link .navbar-item,html.theme--documenter-dark .hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-link a.navbar-item:hover,html.theme--documenter-dark .hero.is-link a.navbar-item.is-active,html.theme--documenter-dark .hero.is-link .navbar-link:hover,html.theme--documenter-dark .hero.is-link .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .hero.is-link .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-link .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-link .tabs li.is-active a{color:#1abc9c !important;opacity:1}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#1abc9c}html.theme--documenter-dark .hero.is-link.is-bold{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}}html.theme--documenter-dark .hero.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-info strong{color:inherit}html.theme--documenter-dark .hero.is-info .title{color:#fff}html.theme--documenter-dark .hero.is-info .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-info .subtitle a:not(.button),html.theme--documenter-dark .hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-info .navbar-menu{background-color:#024c7d}}html.theme--documenter-dark .hero.is-info .navbar-item,html.theme--documenter-dark .hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-info a.navbar-item:hover,html.theme--documenter-dark .hero.is-info a.navbar-item.is-active,html.theme--documenter-dark .hero.is-info .navbar-link:hover,html.theme--documenter-dark .hero.is-info .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .hero.is-info .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-info .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-info .tabs li.is-active a{color:#024c7d !important;opacity:1}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#024c7d}html.theme--documenter-dark .hero.is-info.is-bold{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}}html.theme--documenter-dark .hero.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-success strong{color:inherit}html.theme--documenter-dark .hero.is-success .title{color:#fff}html.theme--documenter-dark .hero.is-success .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-success .subtitle a:not(.button),html.theme--documenter-dark .hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-success .navbar-menu{background-color:#008438}}html.theme--documenter-dark .hero.is-success .navbar-item,html.theme--documenter-dark .hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-success a.navbar-item:hover,html.theme--documenter-dark .hero.is-success a.navbar-item.is-active,html.theme--documenter-dark .hero.is-success .navbar-link:hover,html.theme--documenter-dark .hero.is-success .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .hero.is-success .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-success .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-success .tabs li.is-active a{color:#008438 !important;opacity:1}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#008438}html.theme--documenter-dark .hero.is-success.is-bold{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}}html.theme--documenter-dark .hero.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-warning strong{color:inherit}html.theme--documenter-dark .hero.is-warning .title{color:#fff}html.theme--documenter-dark .hero.is-warning .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-warning .subtitle a:not(.button),html.theme--documenter-dark .hero.is-warning .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-warning .navbar-menu{background-color:#ad8100}}html.theme--documenter-dark .hero.is-warning .navbar-item,html.theme--documenter-dark .hero.is-warning .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-warning a.navbar-item:hover,html.theme--documenter-dark .hero.is-warning a.navbar-item.is-active,html.theme--documenter-dark .hero.is-warning .navbar-link:hover,html.theme--documenter-dark .hero.is-warning .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .hero.is-warning .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-warning .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-warning .tabs li.is-active a{color:#ad8100 !important;opacity:1}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#ad8100}html.theme--documenter-dark .hero.is-warning.is-bold{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}}html.theme--documenter-dark .hero.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-danger strong{color:inherit}html.theme--documenter-dark .hero.is-danger .title{color:#fff}html.theme--documenter-dark .hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-danger .subtitle a:not(.button),html.theme--documenter-dark .hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-danger .navbar-menu{background-color:#9e1b0d}}html.theme--documenter-dark .hero.is-danger .navbar-item,html.theme--documenter-dark .hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-danger a.navbar-item:hover,html.theme--documenter-dark .hero.is-danger a.navbar-item.is-active,html.theme--documenter-dark .hero.is-danger .navbar-link:hover,html.theme--documenter-dark .hero.is-danger .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .hero.is-danger .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-danger .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-danger .tabs li.is-active a{color:#9e1b0d !important;opacity:1}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#9e1b0d}html.theme--documenter-dark .hero.is-danger.is-bold{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}}html.theme--documenter-dark .hero.is-small .hero-body,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-large .hero-body{padding:18rem 6rem}}html.theme--documenter-dark .hero.is-halfheight .hero-body,html.theme--documenter-dark .hero.is-fullheight .hero-body,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}html.theme--documenter-dark .hero.is-halfheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .hero.is-halfheight{min-height:50vh}html.theme--documenter-dark .hero.is-fullheight{min-height:100vh}html.theme--documenter-dark .hero-video{overflow:hidden}html.theme--documenter-dark .hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}html.theme--documenter-dark .hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-video{display:none}}html.theme--documenter-dark .hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-buttons .button{display:flex}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-buttons{display:flex;justify-content:center}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-right:1.5rem}}html.theme--documenter-dark .hero-head,html.theme--documenter-dark .hero-foot{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-body{padding:3rem 3rem}}html.theme--documenter-dark .section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){html.theme--documenter-dark .section{padding:3rem 3rem}html.theme--documenter-dark .section.is-medium{padding:9rem 4.5rem}html.theme--documenter-dark .section.is-large{padding:18rem 6rem}}html.theme--documenter-dark .footer{background-color:#282f2f;padding:3rem 1.5rem 6rem}html.theme--documenter-dark hr{height:1px}html.theme--documenter-dark h6{text-transform:uppercase;letter-spacing:0.5px}html.theme--documenter-dark .hero{background-color:#343c3d}html.theme--documenter-dark a{transition:all 200ms ease}html.theme--documenter-dark .button{transition:all 200ms ease;border-width:1px;color:#fff}html.theme--documenter-dark .button.is-active,html.theme--documenter-dark .button.is-focused,html.theme--documenter-dark .button:active,html.theme--documenter-dark .button:focus{box-shadow:0 0 0 2px rgba(140,155,157,0.5)}html.theme--documenter-dark .button.is-white.is-hovered,html.theme--documenter-dark .button.is-white:hover{background-color:#fff}html.theme--documenter-dark .button.is-white.is-active,html.theme--documenter-dark .button.is-white.is-focused,html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white:focus{border-color:#fff;box-shadow:0 0 0 2px rgba(255,255,255,0.5)}html.theme--documenter-dark .button.is-black.is-hovered,html.theme--documenter-dark .button.is-black:hover{background-color:#1d1d1d}html.theme--documenter-dark .button.is-black.is-active,html.theme--documenter-dark .button.is-black.is-focused,html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black:focus{border-color:#0a0a0a;box-shadow:0 0 0 2px rgba(10,10,10,0.5)}html.theme--documenter-dark .button.is-light.is-hovered,html.theme--documenter-dark .button.is-light:hover{background-color:#fff}html.theme--documenter-dark .button.is-light.is-active,html.theme--documenter-dark .button.is-light.is-focused,html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light:focus{border-color:#ecf0f1;box-shadow:0 0 0 2px rgba(236,240,241,0.5)}html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered,html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover{background-color:#3a4344}html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused,html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus{border-color:#282f2f;box-shadow:0 0 0 2px rgba(40,47,47,0.5)}html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover{background-color:#436d9a}html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink,html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus{border-color:#375a7f;box-shadow:0 0 0 2px rgba(55,90,127,0.5)}html.theme--documenter-dark .button.is-link.is-hovered,html.theme--documenter-dark .button.is-link:hover{background-color:#1fdeb8}html.theme--documenter-dark .button.is-link.is-active,html.theme--documenter-dark .button.is-link.is-focused,html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link:focus{border-color:#1abc9c;box-shadow:0 0 0 2px rgba(26,188,156,0.5)}html.theme--documenter-dark .button.is-info.is-hovered,html.theme--documenter-dark .button.is-info:hover{background-color:#0363a3}html.theme--documenter-dark .button.is-info.is-active,html.theme--documenter-dark .button.is-info.is-focused,html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info:focus{border-color:#024c7d;box-shadow:0 0 0 2px rgba(2,76,125,0.5)}html.theme--documenter-dark .button.is-success.is-hovered,html.theme--documenter-dark .button.is-success:hover{background-color:#00aa48}html.theme--documenter-dark .button.is-success.is-active,html.theme--documenter-dark .button.is-success.is-focused,html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success:focus{border-color:#008438;box-shadow:0 0 0 2px rgba(0,132,56,0.5)}html.theme--documenter-dark .button.is-warning.is-hovered,html.theme--documenter-dark .button.is-warning:hover{background-color:#d39e00}html.theme--documenter-dark .button.is-warning.is-active,html.theme--documenter-dark .button.is-warning.is-focused,html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning:focus{border-color:#ad8100;box-shadow:0 0 0 2px rgba(173,129,0,0.5)}html.theme--documenter-dark .button.is-danger.is-hovered,html.theme--documenter-dark .button.is-danger:hover{background-color:#c12110}html.theme--documenter-dark .button.is-danger.is-active,html.theme--documenter-dark .button.is-danger.is-focused,html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger:focus{border-color:#9e1b0d;box-shadow:0 0 0 2px rgba(158,27,13,0.5)}html.theme--documenter-dark .label{color:#dbdee0}html.theme--documenter-dark .button,html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .select,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea{height:2.5em}html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .textarea{transition:all 200ms ease;box-shadow:none;border-width:1px;padding-left:1em;padding-right:1em}html.theme--documenter-dark .select:after,html.theme--documenter-dark .select select{border-width:1px}html.theme--documenter-dark .control.has-addons .button,html.theme--documenter-dark .control.has-addons .input,html.theme--documenter-dark .control.has-addons #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-addons form.docs-search>input,html.theme--documenter-dark .control.has-addons .select{margin-right:-1px}html.theme--documenter-dark .notification{background-color:#343c3d}html.theme--documenter-dark .card{box-shadow:none;border:1px solid #343c3d;background-color:#282f2f;border-radius:.4em}html.theme--documenter-dark .card .card-image img{border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-header{box-shadow:none;background-color:rgba(18,18,18,0.2);border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-footer{background-color:rgba(18,18,18,0.2)}html.theme--documenter-dark .card .card-footer,html.theme--documenter-dark .card .card-footer-item{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .notification.is-white a:not(.button){color:#0a0a0a;text-decoration:underline}html.theme--documenter-dark .notification.is-black a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-light a:not(.button){color:rgba(0,0,0,0.7);text-decoration:underline}html.theme--documenter-dark .notification.is-dark a:not(.button),html.theme--documenter-dark .content kbd.notification a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-primary a:not(.button),html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-link a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-info a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-success a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-warning a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-danger a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .tag,html.theme--documenter-dark .content kbd,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{border-radius:.4em}html.theme--documenter-dark .menu-list a{transition:all 300ms ease}html.theme--documenter-dark .modal-card-body{background-color:#282f2f}html.theme--documenter-dark .modal-card-foot,html.theme--documenter-dark .modal-card-head{border-color:#343c3d}html.theme--documenter-dark .message-header{font-weight:700;background-color:#343c3d;color:#fff}html.theme--documenter-dark .message-body{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .navbar{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent{background:none}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar .navbar-menu{background-color:#375a7f;border-radius:0 0 .4em .4em}}html.theme--documenter-dark .hero .navbar,html.theme--documenter-dark body>.navbar{border-radius:0}html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous{border-width:1px}html.theme--documenter-dark .panel-block,html.theme--documenter-dark .panel-heading,html.theme--documenter-dark .panel-tabs{border-width:1px}html.theme--documenter-dark .panel-block:first-child,html.theme--documenter-dark .panel-heading:first-child,html.theme--documenter-dark .panel-tabs:first-child{border-top-width:1px}html.theme--documenter-dark .panel-heading{font-weight:700}html.theme--documenter-dark .panel-tabs a{border-width:1px;margin-bottom:-1px}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#17a689}html.theme--documenter-dark .panel-block:hover{color:#1dd2af}html.theme--documenter-dark .panel-block:hover .panel-icon{color:#1dd2af}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#17a689}html.theme--documenter-dark .tabs a{border-bottom-width:1px;margin-bottom:-1px}html.theme--documenter-dark .tabs ul{border-bottom-width:1px}html.theme--documenter-dark .tabs.is-boxed a{border-width:1px}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#1f2424}html.theme--documenter-dark .tabs.is-toggle li a{border-width:1px;margin-bottom:0}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .hero.is-white .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-black .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-light .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-dark .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .content kbd.hero .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-primary .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-link .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-info .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-success .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-warning .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-danger .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark h1 .docs-heading-anchor,html.theme--documenter-dark h1 .docs-heading-anchor:hover,html.theme--documenter-dark h1 .docs-heading-anchor:visited,html.theme--documenter-dark h2 .docs-heading-anchor,html.theme--documenter-dark h2 .docs-heading-anchor:hover,html.theme--documenter-dark h2 .docs-heading-anchor:visited,html.theme--documenter-dark h3 .docs-heading-anchor,html.theme--documenter-dark h3 .docs-heading-anchor:hover,html.theme--documenter-dark h3 .docs-heading-anchor:visited,html.theme--documenter-dark h4 .docs-heading-anchor,html.theme--documenter-dark h4 .docs-heading-anchor:hover,html.theme--documenter-dark h4 .docs-heading-anchor:visited,html.theme--documenter-dark h5 .docs-heading-anchor,html.theme--documenter-dark h5 .docs-heading-anchor:hover,html.theme--documenter-dark h5 .docs-heading-anchor:visited,html.theme--documenter-dark h6 .docs-heading-anchor,html.theme--documenter-dark h6 .docs-heading-anchor:hover,html.theme--documenter-dark h6 .docs-heading-anchor:visited{color:#f2f2f2}html.theme--documenter-dark h1 .docs-heading-anchor-permalink,html.theme--documenter-dark h2 .docs-heading-anchor-permalink,html.theme--documenter-dark h3 .docs-heading-anchor-permalink,html.theme--documenter-dark h4 .docs-heading-anchor-permalink,html.theme--documenter-dark h5 .docs-heading-anchor-permalink,html.theme--documenter-dark h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}html.theme--documenter-dark h1 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h2 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h3 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h4 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h5 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}html.theme--documenter-dark h1:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h2:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h3:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h4:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h5:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h6:hover .docs-heading-anchor-permalink{visibility:visible}html.theme--documenter-dark .docs-light-only{display:none !important}html.theme--documenter-dark pre{position:relative;overflow:hidden}html.theme--documenter-dark pre code,html.theme--documenter-dark pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}html.theme--documenter-dark pre code:first-of-type,html.theme--documenter-dark pre code.hljs:first-of-type{padding-top:0.5rem !important}html.theme--documenter-dark pre code:last-of-type,html.theme--documenter-dark pre code.hljs:last-of-type{padding-bottom:0.5rem !important}html.theme--documenter-dark pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#fff;cursor:pointer;text-align:center}html.theme--documenter-dark pre .copy-button:focus,html.theme--documenter-dark pre .copy-button:hover{opacity:1;background:rgba(255,255,255,0.1);color:#1abc9c}html.theme--documenter-dark pre .copy-button.success{color:#259a12;opacity:1}html.theme--documenter-dark pre .copy-button.error{color:#cb3c33;opacity:1}html.theme--documenter-dark pre:hover .copy-button{opacity:1}html.theme--documenter-dark .admonition{background-color:#282f2f;border-style:solid;border-width:1px;border-color:#5e6d6f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .admonition strong{color:currentColor}html.theme--documenter-dark .admonition.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}html.theme--documenter-dark .admonition.is-medium{font-size:1.25rem}html.theme--documenter-dark .admonition.is-large{font-size:1.5rem}html.theme--documenter-dark .admonition.is-default{background-color:#282f2f;border-color:#5e6d6f}html.theme--documenter-dark .admonition.is-default>.admonition-header{background-color:#5e6d6f;color:#fff}html.theme--documenter-dark .admonition.is-default>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-info{background-color:#282f2f;border-color:#024c7d}html.theme--documenter-dark .admonition.is-info>.admonition-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .admonition.is-info>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-success{background-color:#282f2f;border-color:#008438}html.theme--documenter-dark .admonition.is-success>.admonition-header{background-color:#008438;color:#fff}html.theme--documenter-dark .admonition.is-success>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-warning{background-color:#282f2f;border-color:#ad8100}html.theme--documenter-dark .admonition.is-warning>.admonition-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .admonition.is-warning>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-danger{background-color:#282f2f;border-color:#9e1b0d}html.theme--documenter-dark .admonition.is-danger>.admonition-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .admonition.is-danger>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-compat{background-color:#282f2f;border-color:#137886}html.theme--documenter-dark .admonition.is-compat>.admonition-header{background-color:#137886;color:#fff}html.theme--documenter-dark .admonition.is-compat>.admonition-body{color:#fff}html.theme--documenter-dark .admonition-header{color:#fff;background-color:#5e6d6f;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}html.theme--documenter-dark .admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}html.theme--documenter-dark details.admonition.is-details>.admonition-header{list-style:none}html.theme--documenter-dark details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}html.theme--documenter-dark details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}html.theme--documenter-dark .admonition-body{color:#fff;padding:0.5rem .75rem}html.theme--documenter-dark .admonition-body pre{background-color:#282f2f}html.theme--documenter-dark .admonition-body code{background-color:rgba(255,255,255,0.05)}html.theme--documenter-dark .docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #5e6d6f;box-shadow:none;max-width:100%}html.theme--documenter-dark .docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#282f2f;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #5e6d6f;overflow:auto}html.theme--documenter-dark .docstring>header code{background-color:transparent}html.theme--documenter-dark .docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}html.theme--documenter-dark .docstring>header .docstring-binding{margin-right:0.3em}html.theme--documenter-dark .docstring>header .docstring-category{margin-left:0.3em}html.theme--documenter-dark .docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .docstring>section:last-child{border-bottom:none}html.theme--documenter-dark .docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}html.theme--documenter-dark .docstring>section>a.docs-sourcelink:focus{opacity:1 !important}html.theme--documenter-dark .docstring:hover>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring>section:hover a.docs-sourcelink{opacity:1}html.theme--documenter-dark .documenter-example-output{background-color:#1f2424}html.theme--documenter-dark .outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#282f2f;color:#fff;border-bottom:3px solid #9e1b0d;padding:10px 35px;text-align:center;font-size:15px}html.theme--documenter-dark .outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}html.theme--documenter-dark .outdated-warning-overlay a{color:#1abc9c}html.theme--documenter-dark .outdated-warning-overlay a:hover{color:#1dd2af}html.theme--documenter-dark .content pre{border:1px solid #5e6d6f}html.theme--documenter-dark .content code{font-weight:inherit}html.theme--documenter-dark .content a code{color:#1abc9c}html.theme--documenter-dark .content h1 code,html.theme--documenter-dark .content h2 code,html.theme--documenter-dark .content h3 code,html.theme--documenter-dark .content h4 code,html.theme--documenter-dark .content h5 code,html.theme--documenter-dark .content h6 code{color:#f2f2f2}html.theme--documenter-dark .content table{display:block;width:initial;max-width:100%;overflow-x:auto}html.theme--documenter-dark .content blockquote>ul:first-child,html.theme--documenter-dark .content blockquote>ol:first-child,html.theme--documenter-dark .content .admonition-body>ul:first-child,html.theme--documenter-dark .content .admonition-body>ol:first-child{margin-top:0}html.theme--documenter-dark pre,html.theme--documenter-dark code{font-variant-ligatures:no-contextual}html.theme--documenter-dark .breadcrumb a.is-disabled{cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb a.is-disabled,html.theme--documenter-dark .breadcrumb a.is-disabled:hover{color:#f2f2f2}html.theme--documenter-dark .hljs{background:initial !important}html.theme--documenter-dark .katex .katex-mathml{top:0;right:0}html.theme--documenter-dark .katex-display,html.theme--documenter-dark mjx-container,html.theme--documenter-dark .MathJax_Display{margin:0.5em 0 !important}html.theme--documenter-dark html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}html.theme--documenter-dark li.no-marker{list-style:none}html.theme--documenter-dark #documenter .docs-main>article{overflow-wrap:break-word}html.theme--documenter-dark #documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main{width:100%}html.theme--documenter-dark #documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-main>header,html.theme--documenter-dark #documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar{background-color:#1f2424;border-bottom:1px solid #5e6d6f;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-icon,html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #171717;transition-duration:0.7s;-webkit-transition-duration:0.7s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}html.theme--documenter-dark #documenter .docs-main section.footnotes{border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-main section.footnotes li .tag:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .content kbd:first-child,html.theme--documenter-dark .content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}html.theme--documenter-dark #documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #5e6d6f;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage,html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}html.theme--documenter-dark #documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}html.theme--documenter-dark #documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}html.theme--documenter-dark #documenter .docs-sidebar{display:flex;flex-direction:column;color:#fff;background-color:#282f2f;border-right:1px solid #5e6d6f;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}html.theme--documenter-dark #documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #171717}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar{left:0;top:0}}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a,html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a:hover{color:#fff}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector{border-top:1px solid #5e6d6f;display:none;padding:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector.visible{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #5e6d6f;padding-bottom:1.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#fff;background:#282f2f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu a.tocitem:hover,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#fff;background-color:#32393a}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #5e6d6f;border-bottom:1px solid #5e6d6f;background-color:#1f2424}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#1f2424;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#32393a;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{width:14.4rem}html.theme--documenter-dark #documenter .docs-sidebar #documenter-search-query{color:#868c98;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}html.theme--documenter-dark kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(245,245,245,0.6);box-shadow:0 2px 0 1px rgba(245,245,245,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}html.theme--documenter-dark .search-min-width-50{min-width:50%}html.theme--documenter-dark .search-min-height-100{min-height:100%}html.theme--documenter-dark .search-modal-card-body{max-height:calc(100vh - 15rem)}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333;background-color:#f1f5f9}html.theme--documenter-dark .search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}html.theme--documenter-dark .search-filter:hover,html.theme--documenter-dark .search-filter:focus{color:#333}html.theme--documenter-dark .search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}html.theme--documenter-dark .search-filter-selected:hover,html.theme--documenter-dark .search-filter-selected:focus{color:#f5f5f5}html.theme--documenter-dark .search-result-highlight{background-color:#ffdd57;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .search-result-title{width:85%;color:#f5f5f5}html.theme--documenter-dark .search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-thumb,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-track,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem}html.theme--documenter-dark .gap-8{gap:2rem}html.theme--documenter-dark{background-color:#1f2424;font-size:16px;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark .ansi span.sgr1{font-weight:bolder}html.theme--documenter-dark .ansi span.sgr2{font-weight:lighter}html.theme--documenter-dark .ansi span.sgr3{font-style:italic}html.theme--documenter-dark .ansi span.sgr4{text-decoration:underline}html.theme--documenter-dark .ansi span.sgr7{color:#1f2424;background-color:#fff}html.theme--documenter-dark .ansi span.sgr8{color:transparent}html.theme--documenter-dark .ansi span.sgr8 span{color:transparent}html.theme--documenter-dark .ansi span.sgr9{text-decoration:line-through}html.theme--documenter-dark .ansi span.sgr30{color:#242424}html.theme--documenter-dark .ansi span.sgr31{color:#f6705f}html.theme--documenter-dark .ansi span.sgr32{color:#4fb43a}html.theme--documenter-dark .ansi span.sgr33{color:#f4c72f}html.theme--documenter-dark .ansi span.sgr34{color:#7587f0}html.theme--documenter-dark .ansi span.sgr35{color:#bc89d3}html.theme--documenter-dark .ansi span.sgr36{color:#49b6ca}html.theme--documenter-dark .ansi span.sgr37{color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr40{background-color:#242424}html.theme--documenter-dark .ansi span.sgr41{background-color:#f6705f}html.theme--documenter-dark .ansi span.sgr42{background-color:#4fb43a}html.theme--documenter-dark .ansi span.sgr43{background-color:#f4c72f}html.theme--documenter-dark .ansi span.sgr44{background-color:#7587f0}html.theme--documenter-dark .ansi span.sgr45{background-color:#bc89d3}html.theme--documenter-dark .ansi span.sgr46{background-color:#49b6ca}html.theme--documenter-dark .ansi span.sgr47{background-color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr90{color:#92a0a2}html.theme--documenter-dark .ansi span.sgr91{color:#ff8674}html.theme--documenter-dark .ansi span.sgr92{color:#79d462}html.theme--documenter-dark .ansi span.sgr93{color:#ffe76b}html.theme--documenter-dark .ansi span.sgr94{color:#8a98ff}html.theme--documenter-dark .ansi span.sgr95{color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr96{color:#6bc8db}html.theme--documenter-dark .ansi span.sgr97{color:#ecf0f1}html.theme--documenter-dark .ansi span.sgr100{background-color:#92a0a2}html.theme--documenter-dark .ansi span.sgr101{background-color:#ff8674}html.theme--documenter-dark .ansi span.sgr102{background-color:#79d462}html.theme--documenter-dark .ansi span.sgr103{background-color:#ffe76b}html.theme--documenter-dark .ansi span.sgr104{background-color:#8a98ff}html.theme--documenter-dark .ansi span.sgr105{background-color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr106{background-color:#6bc8db}html.theme--documenter-dark .ansi span.sgr107{background-color:#ecf0f1}html.theme--documenter-dark code.language-julia-repl>span.hljs-meta{color:#4fb43a;font-weight:bolder}html.theme--documenter-dark .hljs{background:#2b2b2b;color:#f8f8f2}html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-quote{color:#d4d0ab}html.theme--documenter-dark .hljs-variable,html.theme--documenter-dark .hljs-template-variable,html.theme--documenter-dark .hljs-tag,html.theme--documenter-dark .hljs-name,html.theme--documenter-dark .hljs-selector-id,html.theme--documenter-dark .hljs-selector-class,html.theme--documenter-dark .hljs-regexp,html.theme--documenter-dark .hljs-deletion{color:#ffa07a}html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-link{color:#f5ab35}html.theme--documenter-dark .hljs-attribute{color:#ffd700}html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-addition{color:#abe338}html.theme--documenter-dark .hljs-title,html.theme--documenter-dark .hljs-section{color:#00e0e0}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{color:#dcc6e0}html.theme--documenter-dark .hljs-emphasis{font-style:italic}html.theme--documenter-dark .hljs-strong{font-weight:bold}@media screen and (-ms-high-contrast: active){html.theme--documenter-dark .hljs-addition,html.theme--documenter-dark .hljs-attribute,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-link,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-quote{color:highlight}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{font-weight:bold}}html.theme--documenter-dark .hljs-subst{color:#f8f8f2}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333 !important;background-color:#f1f5f9 !important}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:whitesmoke;background-color:#33415580;border-radius:0.6rem}html.theme--documenter-dark .search-result-title{color:whitesmoke}html.theme--documenter-dark .search-result-highlight{background-color:greenyellow;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f50}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem} diff --git a/v2.16.0/assets/themes/documenter-light.css b/v2.16.0/assets/themes/documenter-light.css new file mode 100644 index 000000000..2f168c77b --- /dev/null +++ b/v2.16.0/assets/themes/documenter-light.css @@ -0,0 +1,9 @@ +.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.file-cta,.file-name,.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input,.button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:4px;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus,.pagination-ellipsis:focus,.file-cta:focus,.file-name:focus,.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.button:focus,.is-focused.pagination-previous,.is-focused.pagination-next,.is-focused.pagination-link,.is-focused.pagination-ellipsis,.is-focused.file-cta,.is-focused.file-name,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-focused.button,.pagination-previous:active,.pagination-next:active,.pagination-link:active,.pagination-ellipsis:active,.file-cta:active,.file-name:active,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.button:active,.is-active.pagination-previous,.is-active.pagination-next,.is-active.pagination-link,.is-active.pagination-ellipsis,.is-active.file-cta,.is-active.file-name,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.is-active.button{outline:none}.pagination-previous[disabled],.pagination-next[disabled],.pagination-link[disabled],.pagination-ellipsis[disabled],.file-cta[disabled],.file-name[disabled],.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],.button[disabled],fieldset[disabled] .pagination-previous,fieldset[disabled] .pagination-next,fieldset[disabled] .pagination-link,fieldset[disabled] .pagination-ellipsis,fieldset[disabled] .file-cta,fieldset[disabled] .file-name,fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] .button{cursor:not-allowed}.tabs,.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.breadcrumb,.file,.button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.navbar-link:not(.is-arrowless)::after,.select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}.admonition:not(:last-child),.tabs:not(:last-child),.pagination:not(:last-child),.message:not(:last-child),.level:not(:last-child),.breadcrumb:not(:last-child),.block:not(:last-child),.title:not(:last-child),.subtitle:not(:last-child),.table-container:not(:last-child),.table:not(:last-child),.progress:not(:last-child),.notification:not(:last-child),.content:not(:last-child),.box:not(:last-child){margin-bottom:1.5rem}.modal-close,.delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}.modal-close::before,.delete::before,.modal-close::after,.delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.modal-close::before,.delete::before{height:2px;width:50%}.modal-close::after,.delete::after{height:50%;width:2px}.modal-close:hover,.delete:hover,.modal-close:focus,.delete:focus{background-color:rgba(10,10,10,0.3)}.modal-close:active,.delete:active{background-color:rgba(10,10,10,0.4)}.is-small.modal-close,#documenter .docs-sidebar form.docs-search>input.modal-close,.is-small.delete,#documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}.is-medium.modal-close,.is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}.is-large.modal-close,.is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}.control.is-loading::after,.select.is-loading::after,.loader,.button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdbdb;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}.hero-video,.modal-background,.modal,.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}.navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#f5f5f5 !important}a.has-text-light:hover,a.has-text-light:focus{color:#dbdbdb !important}.has-background-light{background-color:#f5f5f5 !important}.has-text-dark{color:#363636 !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#1c1c1c !important}.has-background-dark{background-color:#363636 !important}.has-text-primary{color:#4eb5de !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#27a1d2 !important}.has-background-primary{background-color:#4eb5de !important}.has-text-primary-light{color:#eef8fc !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#c3e6f4 !important}.has-background-primary-light{background-color:#eef8fc !important}.has-text-primary-dark{color:#1a6d8e !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#228eb9 !important}.has-background-primary-dark{background-color:#1a6d8e !important}.has-text-link{color:#2e63b8 !important}a.has-text-link:hover,a.has-text-link:focus{color:#244d8f !important}.has-background-link{background-color:#2e63b8 !important}.has-text-link-light{color:#eff3fb !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c6d6f1 !important}.has-background-link-light{background-color:#eff3fb !important}.has-text-link-dark{color:#3169c4 !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#5485d4 !important}.has-background-link-dark{background-color:#3169c4 !important}.has-text-info{color:#209cee !important}a.has-text-info:hover,a.has-text-info:focus{color:#1081cb !important}.has-background-info{background-color:#209cee !important}.has-text-info-light{color:#ecf7fe !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#bde2fa !important}.has-background-info-light{background-color:#ecf7fe !important}.has-text-info-dark{color:#0e72b4 !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#1190e3 !important}.has-background-info-dark{background-color:#0e72b4 !important}.has-text-success{color:#22c35b !important}a.has-text-success:hover,a.has-text-success:focus{color:#1a9847 !important}.has-background-success{background-color:#22c35b !important}.has-text-success-light{color:#eefcf3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#c2f4d4 !important}.has-background-success-light{background-color:#eefcf3 !important}.has-text-success-dark{color:#198f43 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#21bb57 !important}.has-background-success-dark{background-color:#198f43 !important}.has-text-warning{color:#ffdd57 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#ffd324 !important}.has-background-warning{background-color:#ffdd57 !important}.has-text-warning-light{color:#fffbeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#fff1b8 !important}.has-background-warning-light{background-color:#fffbeb !important}.has-text-warning-dark{color:#947600 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#c79f00 !important}.has-background-warning-dark{background-color:#947600 !important}.has-text-danger{color:#da0b00 !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#a70800 !important}.has-background-danger{background-color:#da0b00 !important}.has-text-danger-light{color:#ffeceb !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#ffbbb8 !important}.has-background-danger-light{background-color:#ffeceb !important}.has-text-danger-dark{color:#f50c00 !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#ff3429 !important}.has-background-danger-dark{background-color:#f50c00 !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#363636 !important}.has-background-grey-darker{background-color:#363636 !important}.has-text-grey-dark{color:#4a4a4a !important}.has-background-grey-dark{background-color:#4a4a4a !important}.has-text-grey{color:#6b6b6b !important}.has-background-grey{background-color:#6b6b6b !important}.has-text-grey-light{color:#b5b5b5 !important}.has-background-grey-light{background-color:#b5b5b5 !important}.has-text-grey-lighter{color:#dbdbdb !important}.has-background-grey-lighter{background-color:#dbdbdb !important}.has-text-white-ter{color:#f5f5f5 !important}.has-background-white-ter{background-color:#f5f5f5 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,.docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}html{background-color:#fff;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}article,aside,figure,footer,header,hgroup,section{display:block}body,button,input,optgroup,select,textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}code,pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}body{color:#222;font-size:1em;font-weight:400;line-height:1.5}a{color:#2e63b8;cursor:pointer;text-decoration:none}a strong{color:currentColor}a:hover{color:#363636}code{background-color:rgba(0,0,0,0.05);color:#000;font-size:.875em;font-weight:normal;padding:.1em}hr{background-color:#f5f5f5;border:none;display:block;height:2px;margin:1.5rem 0}img{height:auto;max-width:100%}input[type="checkbox"],input[type="radio"]{vertical-align:baseline}small{font-size:.875em}span{font-style:inherit;font-weight:inherit}strong{color:#222;font-weight:700}fieldset{border:none}pre{-webkit-overflow-scrolling:touch;background-color:#f5f5f5;color:#222;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}table td,table th{vertical-align:top}table td:not([align]),table th:not([align]){text-align:inherit}table th{color:#222}@keyframes spinAround{from{transform:rotate(0deg)}to{transform:rotate(359deg)}}.box{background-color:#fff;border-radius:6px;box-shadow:#bbb;color:#222;display:block;padding:1.25rem}a.box:hover,a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #2e63b8}a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #2e63b8}.button{background-color:#fff;border-color:#dbdbdb;border-width:1px;color:#222;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}.button strong{color:inherit}.button .icon,.button .icon.is-small,.button #documenter .docs-sidebar form.docs-search>input.icon,#documenter .docs-sidebar .button form.docs-search>input.icon,.button .icon.is-medium,.button .icon.is-large{height:1.5em;width:1.5em}.button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}.button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}.button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}.button:hover,.button.is-hovered{border-color:#b5b5b5;color:#363636}.button:focus,.button.is-focused{border-color:#3c5dcd;color:#363636}.button:focus:not(:active),.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button:active,.button.is-active{border-color:#4a4a4a;color:#363636}.button.is-text{background-color:transparent;border-color:transparent;color:#222;text-decoration:underline}.button.is-text:hover,.button.is-text.is-hovered,.button.is-text:focus,.button.is-text.is-focused{background-color:#f5f5f5;color:#222}.button.is-text:active,.button.is-text.is-active{background-color:#e8e8e8;color:#222}.button.is-text[disabled],fieldset[disabled] .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}.button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#2e63b8;text-decoration:none}.button.is-ghost:hover,.button.is-ghost.is-hovered{color:#2e63b8;text-decoration:underline}.button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}.button.is-white:hover,.button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.button.is-white:focus,.button.is-white.is-focused{border-color:transparent;color:#0a0a0a}.button.is-white:focus:not(:active),.button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.button.is-white:active,.button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.button.is-white[disabled],fieldset[disabled] .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}.button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted:hover,.button.is-white.is-inverted.is-hovered{background-color:#000}.button.is-white.is-inverted[disabled],fieldset[disabled] .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}.button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-white.is-outlined:hover,.button.is-white.is-outlined.is-hovered,.button.is-white.is-outlined:focus,.button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}.button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-outlined.is-loading:hover::after,.button.is-white.is-outlined.is-loading.is-hovered::after,.button.is-white.is-outlined.is-loading:focus::after,.button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined[disabled],fieldset[disabled] .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-white.is-inverted.is-outlined:hover,.button.is-white.is-inverted.is-outlined.is-hovered,.button.is-white.is-inverted.is-outlined:focus,.button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted.is-outlined.is-loading:hover::after,.button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-white.is-inverted.is-outlined.is-loading:focus::after,.button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}.button.is-black:hover,.button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}.button.is-black:focus,.button.is-black.is-focused{border-color:transparent;color:#fff}.button.is-black:focus:not(:active),.button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.button.is-black:active,.button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}.button.is-black[disabled],fieldset[disabled] .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}.button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted:hover,.button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-black.is-inverted[disabled],fieldset[disabled] .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}.button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-black.is-outlined:hover,.button.is-black.is-outlined.is-hovered,.button.is-black.is-outlined:focus,.button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-outlined.is-loading:hover::after,.button.is-black.is-outlined.is-loading.is-hovered::after,.button.is-black.is-outlined.is-loading:focus::after,.button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined[disabled],fieldset[disabled] .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-black.is-inverted.is-outlined:hover,.button.is-black.is-inverted.is-outlined.is-hovered,.button.is-black.is-inverted.is-outlined:focus,.button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted.is-outlined.is-loading:hover::after,.button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-black.is-inverted.is-outlined.is-loading:focus::after,.button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-light{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:hover,.button.is-light.is-hovered{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus,.button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus:not(:active),.button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.button.is-light:active,.button.is-light.is-active{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light[disabled],fieldset[disabled] .button.is-light{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none}.button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted:hover,.button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-light.is-inverted[disabled],fieldset[disabled] .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#f5f5f5}.button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;color:#f5f5f5}.button.is-light.is-outlined:hover,.button.is-light.is-outlined.is-hovered,.button.is-light.is-outlined:focus,.button.is-light.is-outlined.is-focused{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-outlined.is-loading:hover::after,.button.is-light.is-outlined.is-loading.is-hovered::after,.button.is-light.is-outlined.is-loading:focus::after,.button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined[disabled],fieldset[disabled] .button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;box-shadow:none;color:#f5f5f5}.button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-light.is-inverted.is-outlined:hover,.button.is-light.is-inverted.is-outlined.is-hovered,.button.is-light.is-inverted.is-outlined:focus,.button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted.is-outlined.is-loading:hover::after,.button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-light.is-inverted.is-outlined.is-loading:focus::after,.button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-dark,.content kbd.button{background-color:#363636;border-color:transparent;color:#fff}.button.is-dark:hover,.content kbd.button:hover,.button.is-dark.is-hovered,.content kbd.button.is-hovered{background-color:#2f2f2f;border-color:transparent;color:#fff}.button.is-dark:focus,.content kbd.button:focus,.button.is-dark.is-focused,.content kbd.button.is-focused{border-color:transparent;color:#fff}.button.is-dark:focus:not(:active),.content kbd.button:focus:not(:active),.button.is-dark.is-focused:not(:active),.content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.button.is-dark:active,.content kbd.button:active,.button.is-dark.is-active,.content kbd.button.is-active{background-color:#292929;border-color:transparent;color:#fff}.button.is-dark[disabled],.content kbd.button[disabled],fieldset[disabled] .button.is-dark,fieldset[disabled] .content kbd.button,.content fieldset[disabled] kbd.button{background-color:#363636;border-color:#363636;box-shadow:none}.button.is-dark.is-inverted,.content kbd.button.is-inverted{background-color:#fff;color:#363636}.button.is-dark.is-inverted:hover,.content kbd.button.is-inverted:hover,.button.is-dark.is-inverted.is-hovered,.content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-dark.is-inverted[disabled],.content kbd.button.is-inverted[disabled],fieldset[disabled] .button.is-dark.is-inverted,fieldset[disabled] .content kbd.button.is-inverted,.content fieldset[disabled] kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#363636}.button.is-dark.is-loading::after,.content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined,.content kbd.button.is-outlined{background-color:transparent;border-color:#363636;color:#363636}.button.is-dark.is-outlined:hover,.content kbd.button.is-outlined:hover,.button.is-dark.is-outlined.is-hovered,.content kbd.button.is-outlined.is-hovered,.button.is-dark.is-outlined:focus,.content kbd.button.is-outlined:focus,.button.is-dark.is-outlined.is-focused,.content kbd.button.is-outlined.is-focused{background-color:#363636;border-color:#363636;color:#fff}.button.is-dark.is-outlined.is-loading::after,.content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-outlined.is-loading:hover::after,.content kbd.button.is-outlined.is-loading:hover::after,.button.is-dark.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-outlined.is-loading:focus::after,.content kbd.button.is-outlined.is-loading:focus::after,.button.is-dark.is-outlined.is-loading.is-focused::after,.content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined[disabled],.content kbd.button.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-outlined,fieldset[disabled] .content kbd.button.is-outlined,.content fieldset[disabled] kbd.button.is-outlined{background-color:transparent;border-color:#363636;box-shadow:none;color:#363636}.button.is-dark.is-inverted.is-outlined,.content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-dark.is-inverted.is-outlined:hover,.content kbd.button.is-inverted.is-outlined:hover,.button.is-dark.is-inverted.is-outlined.is-hovered,.content kbd.button.is-inverted.is-outlined.is-hovered,.button.is-dark.is-inverted.is-outlined:focus,.content kbd.button.is-inverted.is-outlined:focus,.button.is-dark.is-inverted.is-outlined.is-focused,.content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#363636}.button.is-dark.is-inverted.is-outlined.is-loading:hover::after,.content kbd.button.is-inverted.is-outlined.is-loading:hover::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-inverted.is-outlined.is-loading:focus::after,.content kbd.button.is-inverted.is-outlined.is-loading:focus::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-inverted.is-outlined[disabled],.content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-inverted.is-outlined,fieldset[disabled] .content kbd.button.is-inverted.is-outlined,.content fieldset[disabled] kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary,.docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:transparent;color:#fff}.button.is-primary:hover,.docstring>section>a.button.docs-sourcelink:hover,.button.is-primary.is-hovered,.docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#43b1dc;border-color:transparent;color:#fff}.button.is-primary:focus,.docstring>section>a.button.docs-sourcelink:focus,.button.is-primary.is-focused,.docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}.button.is-primary:focus:not(:active),.docstring>section>a.button.docs-sourcelink:focus:not(:active),.button.is-primary.is-focused:not(:active),.docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.button.is-primary:active,.docstring>section>a.button.docs-sourcelink:active,.button.is-primary.is-active,.docstring>section>a.button.is-active.docs-sourcelink{background-color:#39acda;border-color:transparent;color:#fff}.button.is-primary[disabled],.docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary,fieldset[disabled] .docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;box-shadow:none}.button.is-primary.is-inverted,.docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted:hover,.docstring>section>a.button.is-inverted.docs-sourcelink:hover,.button.is-primary.is-inverted.is-hovered,.docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}.button.is-primary.is-inverted[disabled],.docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted,fieldset[disabled] .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#4eb5de}.button.is-primary.is-loading::after,.docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined,.docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;color:#4eb5de}.button.is-primary.is-outlined:hover,.docstring>section>a.button.is-outlined.docs-sourcelink:hover,.button.is-primary.is-outlined.is-hovered,.docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-outlined:focus,.docstring>section>a.button.is-outlined.docs-sourcelink:focus,.button.is-primary.is-outlined.is-focused,.docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.button.is-primary.is-outlined.is-loading::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined[disabled],.docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-outlined,fieldset[disabled] .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;box-shadow:none;color:#4eb5de}.button.is-primary.is-inverted.is-outlined,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}.button.is-primary.is-inverted.is-outlined:hover,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,.button.is-primary.is-inverted.is-outlined.is-hovered,.docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-inverted.is-outlined:focus,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,.button.is-primary.is-inverted.is-outlined.is-focused,.docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-inverted.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-inverted.is-outlined[disabled],.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted.is-outlined,fieldset[disabled] .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary.is-light,.docstring>section>a.button.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.button.is-primary.is-light:hover,.docstring>section>a.button.is-light.docs-sourcelink:hover,.button.is-primary.is-light.is-hovered,.docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e3f3fa;border-color:transparent;color:#1a6d8e}.button.is-primary.is-light:active,.docstring>section>a.button.is-light.docs-sourcelink:active,.button.is-primary.is-light.is-active,.docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#d8eff8;border-color:transparent;color:#1a6d8e}.button.is-link{background-color:#2e63b8;border-color:transparent;color:#fff}.button.is-link:hover,.button.is-link.is-hovered{background-color:#2b5eae;border-color:transparent;color:#fff}.button.is-link:focus,.button.is-link.is-focused{border-color:transparent;color:#fff}.button.is-link:focus:not(:active),.button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button.is-link:active,.button.is-link.is-active{background-color:#2958a4;border-color:transparent;color:#fff}.button.is-link[disabled],fieldset[disabled] .button.is-link{background-color:#2e63b8;border-color:#2e63b8;box-shadow:none}.button.is-link.is-inverted{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted:hover,.button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-link.is-inverted[disabled],fieldset[disabled] .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#2e63b8}.button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;color:#2e63b8}.button.is-link.is-outlined:hover,.button.is-link.is-outlined.is-hovered,.button.is-link.is-outlined:focus,.button.is-link.is-outlined.is-focused{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-outlined.is-loading:hover::after,.button.is-link.is-outlined.is-loading.is-hovered::after,.button.is-link.is-outlined.is-loading:focus::after,.button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined[disabled],fieldset[disabled] .button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;box-shadow:none;color:#2e63b8}.button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-link.is-inverted.is-outlined:hover,.button.is-link.is-inverted.is-outlined.is-hovered,.button.is-link.is-inverted.is-outlined:focus,.button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted.is-outlined.is-loading:hover::after,.button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-link.is-inverted.is-outlined.is-loading:focus::after,.button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-link.is-light{background-color:#eff3fb;color:#3169c4}.button.is-link.is-light:hover,.button.is-link.is-light.is-hovered{background-color:#e4ecf8;border-color:transparent;color:#3169c4}.button.is-link.is-light:active,.button.is-link.is-light.is-active{background-color:#dae5f6;border-color:transparent;color:#3169c4}.button.is-info{background-color:#209cee;border-color:transparent;color:#fff}.button.is-info:hover,.button.is-info.is-hovered{background-color:#1497ed;border-color:transparent;color:#fff}.button.is-info:focus,.button.is-info.is-focused{border-color:transparent;color:#fff}.button.is-info:focus:not(:active),.button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.button.is-info:active,.button.is-info.is-active{background-color:#1190e3;border-color:transparent;color:#fff}.button.is-info[disabled],fieldset[disabled] .button.is-info{background-color:#209cee;border-color:#209cee;box-shadow:none}.button.is-info.is-inverted{background-color:#fff;color:#209cee}.button.is-info.is-inverted:hover,.button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-info.is-inverted[disabled],fieldset[disabled] .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#209cee}.button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined{background-color:transparent;border-color:#209cee;color:#209cee}.button.is-info.is-outlined:hover,.button.is-info.is-outlined.is-hovered,.button.is-info.is-outlined:focus,.button.is-info.is-outlined.is-focused{background-color:#209cee;border-color:#209cee;color:#fff}.button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-outlined.is-loading:hover::after,.button.is-info.is-outlined.is-loading.is-hovered::after,.button.is-info.is-outlined.is-loading:focus::after,.button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined[disabled],fieldset[disabled] .button.is-info.is-outlined{background-color:transparent;border-color:#209cee;box-shadow:none;color:#209cee}.button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-info.is-inverted.is-outlined:hover,.button.is-info.is-inverted.is-outlined.is-hovered,.button.is-info.is-inverted.is-outlined:focus,.button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#209cee}.button.is-info.is-inverted.is-outlined.is-loading:hover::after,.button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-info.is-inverted.is-outlined.is-loading:focus::after,.button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.button.is-info.is-light:hover,.button.is-info.is-light.is-hovered{background-color:#e0f1fd;border-color:transparent;color:#0e72b4}.button.is-info.is-light:active,.button.is-info.is-light.is-active{background-color:#d4ecfc;border-color:transparent;color:#0e72b4}.button.is-success{background-color:#22c35b;border-color:transparent;color:#fff}.button.is-success:hover,.button.is-success.is-hovered{background-color:#20b856;border-color:transparent;color:#fff}.button.is-success:focus,.button.is-success.is-focused{border-color:transparent;color:#fff}.button.is-success:focus:not(:active),.button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.button.is-success:active,.button.is-success.is-active{background-color:#1ead51;border-color:transparent;color:#fff}.button.is-success[disabled],fieldset[disabled] .button.is-success{background-color:#22c35b;border-color:#22c35b;box-shadow:none}.button.is-success.is-inverted{background-color:#fff;color:#22c35b}.button.is-success.is-inverted:hover,.button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-success.is-inverted[disabled],fieldset[disabled] .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#22c35b}.button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;color:#22c35b}.button.is-success.is-outlined:hover,.button.is-success.is-outlined.is-hovered,.button.is-success.is-outlined:focus,.button.is-success.is-outlined.is-focused{background-color:#22c35b;border-color:#22c35b;color:#fff}.button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-outlined.is-loading:hover::after,.button.is-success.is-outlined.is-loading.is-hovered::after,.button.is-success.is-outlined.is-loading:focus::after,.button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined[disabled],fieldset[disabled] .button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;box-shadow:none;color:#22c35b}.button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-success.is-inverted.is-outlined:hover,.button.is-success.is-inverted.is-outlined.is-hovered,.button.is-success.is-inverted.is-outlined:focus,.button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#22c35b}.button.is-success.is-inverted.is-outlined.is-loading:hover::after,.button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-success.is-inverted.is-outlined.is-loading:focus::after,.button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-success.is-light{background-color:#eefcf3;color:#198f43}.button.is-success.is-light:hover,.button.is-success.is-light.is-hovered{background-color:#e3faeb;border-color:transparent;color:#198f43}.button.is-success.is-light:active,.button.is-success.is-light.is-active{background-color:#d8f8e3;border-color:transparent;color:#198f43}.button.is-warning{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:hover,.button.is-warning.is-hovered{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus,.button.is-warning.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus:not(:active),.button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.button.is-warning:active,.button.is-warning.is-active{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning[disabled],fieldset[disabled] .button.is-warning{background-color:#ffdd57;border-color:#ffdd57;box-shadow:none}.button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted:hover,.button.is-warning.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted[disabled],fieldset[disabled] .button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ffdd57}.button.is-warning.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;color:#ffdd57}.button.is-warning.is-outlined:hover,.button.is-warning.is-outlined.is-hovered,.button.is-warning.is-outlined:focus,.button.is-warning.is-outlined.is-focused{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-outlined.is-loading:hover::after,.button.is-warning.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-outlined.is-loading:focus::after,.button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;box-shadow:none;color:#ffdd57}.button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted.is-outlined:hover,.button.is-warning.is-inverted.is-outlined.is-hovered,.button.is-warning.is-inverted.is-outlined:focus,.button.is-warning.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted.is-outlined.is-loading:hover::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-inverted.is-outlined.is-loading:focus::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-warning.is-light{background-color:#fffbeb;color:#947600}.button.is-warning.is-light:hover,.button.is-warning.is-light.is-hovered{background-color:#fff8de;border-color:transparent;color:#947600}.button.is-warning.is-light:active,.button.is-warning.is-light.is-active{background-color:#fff6d1;border-color:transparent;color:#947600}.button.is-danger{background-color:#da0b00;border-color:transparent;color:#fff}.button.is-danger:hover,.button.is-danger.is-hovered{background-color:#cd0a00;border-color:transparent;color:#fff}.button.is-danger:focus,.button.is-danger.is-focused{border-color:transparent;color:#fff}.button.is-danger:focus:not(:active),.button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.button.is-danger:active,.button.is-danger.is-active{background-color:#c10a00;border-color:transparent;color:#fff}.button.is-danger[disabled],fieldset[disabled] .button.is-danger{background-color:#da0b00;border-color:#da0b00;box-shadow:none}.button.is-danger.is-inverted{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted:hover,.button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-danger.is-inverted[disabled],fieldset[disabled] .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#da0b00}.button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;color:#da0b00}.button.is-danger.is-outlined:hover,.button.is-danger.is-outlined.is-hovered,.button.is-danger.is-outlined:focus,.button.is-danger.is-outlined.is-focused{background-color:#da0b00;border-color:#da0b00;color:#fff}.button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-outlined.is-loading:hover::after,.button.is-danger.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-outlined.is-loading:focus::after,.button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;box-shadow:none;color:#da0b00}.button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-danger.is-inverted.is-outlined:hover,.button.is-danger.is-inverted.is-outlined.is-hovered,.button.is-danger.is-inverted.is-outlined:focus,.button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted.is-outlined.is-loading:hover::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-inverted.is-outlined.is-loading:focus::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.button.is-danger.is-light:hover,.button.is-danger.is-light.is-hovered{background-color:#ffe0de;border-color:transparent;color:#f50c00}.button.is-danger.is-light:active,.button.is-danger.is-light.is-active{background-color:#ffd3d1;border-color:transparent;color:#f50c00}.button.is-small,#documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}.button.is-small:not(.is-rounded),#documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:2px}.button.is-normal{font-size:1rem}.button.is-medium{font-size:1.25rem}.button.is-large{font-size:1.5rem}.button[disabled],fieldset[disabled] .button{background-color:#fff;border-color:#dbdbdb;box-shadow:none;opacity:.5}.button.is-fullwidth{display:flex;width:100%}.button.is-loading{color:transparent !important;pointer-events:none}.button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}.button.is-static{background-color:#f5f5f5;border-color:#dbdbdb;color:#6b6b6b;box-shadow:none;pointer-events:none}.button.is-rounded,#documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}.buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.buttons .button{margin-bottom:0.5rem}.buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}.buttons:last-child{margin-bottom:-0.5rem}.buttons:not(:last-child){margin-bottom:1rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:2px}.buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}.buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}.buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}.buttons.has-addons .button:last-child{margin-right:0}.buttons.has-addons .button:hover,.buttons.has-addons .button.is-hovered{z-index:2}.buttons.has-addons .button:focus,.buttons.has-addons .button.is-focused,.buttons.has-addons .button:active,.buttons.has-addons .button.is-active,.buttons.has-addons .button.is-selected{z-index:3}.buttons.has-addons .button:focus:hover,.buttons.has-addons .button.is-focused:hover,.buttons.has-addons .button:active:hover,.buttons.has-addons .button.is-active:hover,.buttons.has-addons .button.is-selected:hover{z-index:4}.buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}.buttons.is-centered{justify-content:center}.buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}.buttons.is-right{justify-content:flex-end}.buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.65625rem}.button.is-responsive.is-medium{font-size:.75rem}.button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.75rem}.button.is-responsive.is-medium{font-size:1rem}.button.is-responsive.is-large{font-size:1.25rem}}.container{flex-grow:1;margin:0 auto;position:relative;width:auto}.container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){.container{max-width:992px}}@media screen and (max-width: 1215px){.container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){.container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){.container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){.container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}.content li+li{margin-top:0.25em}.content p:not(:last-child),.content dl:not(:last-child),.content ol:not(:last-child),.content ul:not(:last-child),.content blockquote:not(:last-child),.content pre:not(:last-child),.content table:not(:last-child){margin-bottom:1em}.content h1,.content h2,.content h3,.content h4,.content h5,.content h6{color:#222;font-weight:600;line-height:1.125}.content h1{font-size:2em;margin-bottom:0.5em}.content h1:not(:first-child){margin-top:1em}.content h2{font-size:1.75em;margin-bottom:0.5714em}.content h2:not(:first-child){margin-top:1.1428em}.content h3{font-size:1.5em;margin-bottom:0.6666em}.content h3:not(:first-child){margin-top:1.3333em}.content h4{font-size:1.25em;margin-bottom:0.8em}.content h5{font-size:1.125em;margin-bottom:0.8888em}.content h6{font-size:1em;margin-bottom:1em}.content blockquote{background-color:#f5f5f5;border-left:5px solid #dbdbdb;padding:1.25em 1.5em}.content ol{list-style-position:outside;margin-left:2em;margin-top:1em}.content ol:not([type]){list-style-type:decimal}.content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}.content ol.is-lower-roman:not([type]){list-style-type:lower-roman}.content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}.content ol.is-upper-roman:not([type]){list-style-type:upper-roman}.content ul{list-style:disc outside;margin-left:2em;margin-top:1em}.content ul ul{list-style-type:circle;margin-top:0.5em}.content ul ul ul{list-style-type:square}.content dd{margin-left:2em}.content figure{margin-left:2em;margin-right:2em;text-align:center}.content figure:not(:first-child){margin-top:2em}.content figure:not(:last-child){margin-bottom:2em}.content figure img{display:inline-block}.content figure figcaption{font-style:italic}.content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}.content sup,.content sub{font-size:75%}.content table{width:100%}.content table td,.content table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.content table th{color:#222}.content table th:not([align]){text-align:inherit}.content table thead td,.content table thead th{border-width:0 0 2px;color:#222}.content table tfoot td,.content table tfoot th{border-width:2px 0 0;color:#222}.content table tbody tr:last-child td,.content table tbody tr:last-child th{border-bottom-width:0}.content .tabs li+li{margin-top:0}.content.is-small,#documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}.content.is-normal{font-size:1rem}.content.is-medium{font-size:1.25rem}.content.is-large{font-size:1.5rem}.icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}.icon.is-small,#documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}.icon.is-medium{height:2rem;width:2rem}.icon.is-large{height:3rem;width:3rem}.icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}.icon-text .icon{flex-grow:0;flex-shrink:0}.icon-text .icon:not(:last-child){margin-right:.25em}.icon-text .icon:not(:first-child){margin-left:.25em}div.icon-text{display:flex}.image,#documenter .docs-sidebar .docs-logo>img{display:block;position:relative}.image img,#documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}.image img.is-rounded,#documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}.image.is-fullwidth,#documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}.image.is-square,#documenter .docs-sidebar .docs-logo>img.is-square,.image.is-1by1,#documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}.image.is-5by4,#documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}.image.is-4by3,#documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}.image.is-3by2,#documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}.image.is-5by3,#documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}.image.is-16by9,#documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}.image.is-2by1,#documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}.image.is-3by1,#documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}.image.is-4by5,#documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}.image.is-3by4,#documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}.image.is-2by3,#documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}.image.is-3by5,#documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}.image.is-9by16,#documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}.image.is-1by2,#documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}.image.is-1by3,#documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}.image.is-16x16,#documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}.image.is-24x24,#documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}.image.is-32x32,#documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}.image.is-48x48,#documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}.image.is-64x64,#documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}.image.is-96x96,#documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}.image.is-128x128,#documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}.notification{background-color:#f5f5f5;border-radius:4px;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}.notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}.notification strong{color:currentColor}.notification code,.notification pre{background:#fff}.notification pre code{background:transparent}.notification>.delete{right:.5rem;position:absolute;top:0.5rem}.notification .title,.notification .subtitle,.notification .content{color:currentColor}.notification.is-white{background-color:#fff;color:#0a0a0a}.notification.is-black{background-color:#0a0a0a;color:#fff}.notification.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.notification.is-dark,.content kbd.notification{background-color:#363636;color:#fff}.notification.is-primary,.docstring>section>a.notification.docs-sourcelink{background-color:#4eb5de;color:#fff}.notification.is-primary.is-light,.docstring>section>a.notification.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.notification.is-link{background-color:#2e63b8;color:#fff}.notification.is-link.is-light{background-color:#eff3fb;color:#3169c4}.notification.is-info{background-color:#209cee;color:#fff}.notification.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.notification.is-success{background-color:#22c35b;color:#fff}.notification.is-success.is-light{background-color:#eefcf3;color:#198f43}.notification.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.notification.is-warning.is-light{background-color:#fffbeb;color:#947600}.notification.is-danger{background-color:#da0b00;color:#fff}.notification.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}.progress::-webkit-progress-bar{background-color:#ededed}.progress::-webkit-progress-value{background-color:#222}.progress::-moz-progress-bar{background-color:#222}.progress::-ms-fill{background-color:#222;border:none}.progress.is-white::-webkit-progress-value{background-color:#fff}.progress.is-white::-moz-progress-bar{background-color:#fff}.progress.is-white::-ms-fill{background-color:#fff}.progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #ededed 30%)}.progress.is-black::-webkit-progress-value{background-color:#0a0a0a}.progress.is-black::-moz-progress-bar{background-color:#0a0a0a}.progress.is-black::-ms-fill{background-color:#0a0a0a}.progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #ededed 30%)}.progress.is-light::-webkit-progress-value{background-color:#f5f5f5}.progress.is-light::-moz-progress-bar{background-color:#f5f5f5}.progress.is-light::-ms-fill{background-color:#f5f5f5}.progress.is-light:indeterminate{background-image:linear-gradient(to right, #f5f5f5 30%, #ededed 30%)}.progress.is-dark::-webkit-progress-value,.content kbd.progress::-webkit-progress-value{background-color:#363636}.progress.is-dark::-moz-progress-bar,.content kbd.progress::-moz-progress-bar{background-color:#363636}.progress.is-dark::-ms-fill,.content kbd.progress::-ms-fill{background-color:#363636}.progress.is-dark:indeterminate,.content kbd.progress:indeterminate{background-image:linear-gradient(to right, #363636 30%, #ededed 30%)}.progress.is-primary::-webkit-progress-value,.docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#4eb5de}.progress.is-primary::-moz-progress-bar,.docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#4eb5de}.progress.is-primary::-ms-fill,.docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#4eb5de}.progress.is-primary:indeterminate,.docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #4eb5de 30%, #ededed 30%)}.progress.is-link::-webkit-progress-value{background-color:#2e63b8}.progress.is-link::-moz-progress-bar{background-color:#2e63b8}.progress.is-link::-ms-fill{background-color:#2e63b8}.progress.is-link:indeterminate{background-image:linear-gradient(to right, #2e63b8 30%, #ededed 30%)}.progress.is-info::-webkit-progress-value{background-color:#209cee}.progress.is-info::-moz-progress-bar{background-color:#209cee}.progress.is-info::-ms-fill{background-color:#209cee}.progress.is-info:indeterminate{background-image:linear-gradient(to right, #209cee 30%, #ededed 30%)}.progress.is-success::-webkit-progress-value{background-color:#22c35b}.progress.is-success::-moz-progress-bar{background-color:#22c35b}.progress.is-success::-ms-fill{background-color:#22c35b}.progress.is-success:indeterminate{background-image:linear-gradient(to right, #22c35b 30%, #ededed 30%)}.progress.is-warning::-webkit-progress-value{background-color:#ffdd57}.progress.is-warning::-moz-progress-bar{background-color:#ffdd57}.progress.is-warning::-ms-fill{background-color:#ffdd57}.progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ffdd57 30%, #ededed 30%)}.progress.is-danger::-webkit-progress-value{background-color:#da0b00}.progress.is-danger::-moz-progress-bar{background-color:#da0b00}.progress.is-danger::-ms-fill{background-color:#da0b00}.progress.is-danger:indeterminate{background-image:linear-gradient(to right, #da0b00 30%, #ededed 30%)}.progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#ededed;background-image:linear-gradient(to right, #222 30%, #ededed 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}.progress:indeterminate::-webkit-progress-bar{background-color:transparent}.progress:indeterminate::-moz-progress-bar{background-color:transparent}.progress:indeterminate::-ms-fill{animation-name:none}.progress.is-small,#documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}.progress.is-medium{height:1.25rem}.progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}.table{background-color:#fff;color:#222}.table td,.table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.table td.is-white,.table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}.table td.is-black,.table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.table td.is-light,.table th.is-light{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.table td.is-dark,.table th.is-dark{background-color:#363636;border-color:#363636;color:#fff}.table td.is-primary,.table th.is-primary{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.table td.is-link,.table th.is-link{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.table td.is-info,.table th.is-info{background-color:#209cee;border-color:#209cee;color:#fff}.table td.is-success,.table th.is-success{background-color:#22c35b;border-color:#22c35b;color:#fff}.table td.is-warning,.table th.is-warning{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.table td.is-danger,.table th.is-danger{background-color:#da0b00;border-color:#da0b00;color:#fff}.table td.is-narrow,.table th.is-narrow{white-space:nowrap;width:1%}.table td.is-selected,.table th.is-selected{background-color:#4eb5de;color:#fff}.table td.is-selected a,.table td.is-selected strong,.table th.is-selected a,.table th.is-selected strong{color:currentColor}.table td.is-vcentered,.table th.is-vcentered{vertical-align:middle}.table th{color:#222}.table th:not([align]){text-align:left}.table tr.is-selected{background-color:#4eb5de;color:#fff}.table tr.is-selected a,.table tr.is-selected strong{color:currentColor}.table tr.is-selected td,.table tr.is-selected th{border-color:#fff;color:currentColor}.table thead{background-color:rgba(0,0,0,0)}.table thead td,.table thead th{border-width:0 0 2px;color:#222}.table tfoot{background-color:rgba(0,0,0,0)}.table tfoot td,.table tfoot th{border-width:2px 0 0;color:#222}.table tbody{background-color:rgba(0,0,0,0)}.table tbody tr:last-child td,.table tbody tr:last-child th{border-bottom-width:0}.table.is-bordered td,.table.is-bordered th{border-width:1px}.table.is-bordered tr:last-child td,.table.is-bordered tr:last-child th{border-bottom-width:1px}.table.is-fullwidth{width:100%}.table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#f5f5f5}.table.is-narrow td,.table.is-narrow th{padding:0.25em 0.5em}.table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#fafafa}.table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}.tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.tags .tag,.tags .content kbd,.content .tags kbd,.tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}.tags .tag:not(:last-child),.tags .content kbd:not(:last-child),.content .tags kbd:not(:last-child),.tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}.tags:last-child{margin-bottom:-0.5rem}.tags:not(:last-child){margin-bottom:1rem}.tags.are-medium .tag:not(.is-normal):not(.is-large),.tags.are-medium .content kbd:not(.is-normal):not(.is-large),.content .tags.are-medium kbd:not(.is-normal):not(.is-large),.tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}.tags.are-large .tag:not(.is-normal):not(.is-medium),.tags.are-large .content kbd:not(.is-normal):not(.is-medium),.content .tags.are-large kbd:not(.is-normal):not(.is-medium),.tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}.tags.is-centered{justify-content:center}.tags.is-centered .tag,.tags.is-centered .content kbd,.content .tags.is-centered kbd,.tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}.tags.is-right{justify-content:flex-end}.tags.is-right .tag:not(:first-child),.tags.is-right .content kbd:not(:first-child),.content .tags.is-right kbd:not(:first-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}.tags.is-right .tag:not(:last-child),.tags.is-right .content kbd:not(:last-child),.content .tags.is-right kbd:not(:last-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}.tags.has-addons .tag,.tags.has-addons .content kbd,.content .tags.has-addons kbd,.tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}.tags.has-addons .tag:not(:first-child),.tags.has-addons .content kbd:not(:first-child),.content .tags.has-addons kbd:not(:first-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}.tags.has-addons .tag:not(:last-child),.tags.has-addons .content kbd:not(:last-child),.content .tags.has-addons kbd:not(:last-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.tag:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#f5f5f5;border-radius:4px;color:#222;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}.tag:not(body) .delete,.content kbd:not(body) .delete,.docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}.tag.is-white:not(body),.content kbd.is-white:not(body),.docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}.tag.is-black:not(body),.content kbd.is-black:not(body),.docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}.tag.is-light:not(body),.content kbd.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.tag.is-dark:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink.is-dark:not(body),.content .docstring>section>kbd:not(body){background-color:#363636;color:#fff}.tag.is-primary:not(body),.content kbd.is-primary:not(body),.docstring>section>a.docs-sourcelink:not(body){background-color:#4eb5de;color:#fff}.tag.is-primary.is-light:not(body),.content kbd.is-primary.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#eef8fc;color:#1a6d8e}.tag.is-link:not(body),.content kbd.is-link:not(body),.docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#2e63b8;color:#fff}.tag.is-link.is-light:not(body),.content kbd.is-link.is-light:not(body),.docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#eff3fb;color:#3169c4}.tag.is-info:not(body),.content kbd.is-info:not(body),.docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#209cee;color:#fff}.tag.is-info.is-light:not(body),.content kbd.is-info.is-light:not(body),.docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ecf7fe;color:#0e72b4}.tag.is-success:not(body),.content kbd.is-success:not(body),.docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#22c35b;color:#fff}.tag.is-success.is-light:not(body),.content kbd.is-success.is-light:not(body),.docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#eefcf3;color:#198f43}.tag.is-warning:not(body),.content kbd.is-warning:not(body),.docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ffdd57;color:rgba(0,0,0,0.7)}.tag.is-warning.is-light:not(body),.content kbd.is-warning.is-light:not(body),.docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffbeb;color:#947600}.tag.is-danger:not(body),.content kbd.is-danger:not(body),.docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#da0b00;color:#fff}.tag.is-danger.is-light:not(body),.content kbd.is-danger.is-light:not(body),.docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#ffeceb;color:#f50c00}.tag.is-normal:not(body),.content kbd.is-normal:not(body),.docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}.tag.is-medium:not(body),.content kbd.is-medium:not(body),.docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}.tag.is-large:not(body),.content kbd.is-large:not(body),.docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}.tag:not(body) .icon:first-child:not(:last-child),.content kbd:not(body) .icon:first-child:not(:last-child),.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}.tag:not(body) .icon:last-child:not(:first-child),.content kbd:not(body) .icon:last-child:not(:first-child),.docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}.tag:not(body) .icon:first-child:last-child,.content kbd:not(body) .icon:first-child:last-child,.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}.tag.is-delete:not(body),.content kbd.is-delete:not(body),.docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before,.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}.tag.is-delete:not(body):hover,.content kbd.is-delete:not(body):hover,.docstring>section>a.docs-sourcelink.is-delete:not(body):hover,.tag.is-delete:not(body):focus,.content kbd.is-delete:not(body):focus,.docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#e8e8e8}.tag.is-delete:not(body):active,.content kbd.is-delete:not(body):active,.docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#dbdbdb}.tag.is-rounded:not(body),#documenter .docs-sidebar form.docs-search>input:not(body),.content kbd.is-rounded:not(body),#documenter .docs-sidebar .content form.docs-search>input:not(body),.docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}a.tag:hover,.docstring>section>a.docs-sourcelink:hover{text-decoration:underline}.title,.subtitle{word-break:break-word}.title em,.title span,.subtitle em,.subtitle span{font-weight:inherit}.title sub,.subtitle sub{font-size:.75em}.title sup,.subtitle sup{font-size:.75em}.title .tag,.title .content kbd,.content .title kbd,.title .docstring>section>a.docs-sourcelink,.subtitle .tag,.subtitle .content kbd,.content .subtitle kbd,.subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}.title{color:#222;font-size:2rem;font-weight:600;line-height:1.125}.title strong{color:inherit;font-weight:inherit}.title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}.title.is-1{font-size:3rem}.title.is-2{font-size:2.5rem}.title.is-3{font-size:2rem}.title.is-4{font-size:1.5rem}.title.is-5{font-size:1.25rem}.title.is-6{font-size:1rem}.title.is-7{font-size:.75rem}.subtitle{color:#222;font-size:1.25rem;font-weight:400;line-height:1.25}.subtitle strong{color:#222;font-weight:600}.subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}.subtitle.is-1{font-size:3rem}.subtitle.is-2{font-size:2.5rem}.subtitle.is-3{font-size:2rem}.subtitle.is-4{font-size:1.5rem}.subtitle.is-5{font-size:1.25rem}.subtitle.is-6{font-size:1rem}.subtitle.is-7{font-size:.75rem}.heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}.number{align-items:center;background-color:#f5f5f5;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input{background-color:#fff;border-color:#dbdbdb;border-radius:4px;color:#222}.select select::-moz-placeholder,.textarea::-moz-placeholder,.input::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#707070}.select select::-webkit-input-placeholder,.textarea::-webkit-input-placeholder,.input::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#707070}.select select:-moz-placeholder,.textarea:-moz-placeholder,.input:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#707070}.select select:-ms-input-placeholder,.textarea:-ms-input-placeholder,.input:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#707070}.select select:hover,.textarea:hover,.input:hover,#documenter .docs-sidebar form.docs-search>input:hover,.select select.is-hovered,.is-hovered.textarea,.is-hovered.input,#documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#b5b5b5}.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{border-color:#2e63b8;box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none;color:#6b6b6b}.select select[disabled]::-moz-placeholder,.textarea[disabled]::-moz-placeholder,.input[disabled]::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] .select select::-moz-placeholder,.select fieldset[disabled] select::-moz-placeholder,fieldset[disabled] .textarea::-moz-placeholder,fieldset[disabled] .input::-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]::-webkit-input-placeholder,.textarea[disabled]::-webkit-input-placeholder,.input[disabled]::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] .select select::-webkit-input-placeholder,.select fieldset[disabled] select::-webkit-input-placeholder,fieldset[disabled] .textarea::-webkit-input-placeholder,fieldset[disabled] .input::-webkit-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-webkit-input-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-moz-placeholder,.textarea[disabled]:-moz-placeholder,.input[disabled]:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] .select select:-moz-placeholder,.select fieldset[disabled] select:-moz-placeholder,fieldset[disabled] .textarea:-moz-placeholder,fieldset[disabled] .input:-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-ms-input-placeholder,.textarea[disabled]:-ms-input-placeholder,.input[disabled]:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] .select select:-ms-input-placeholder,.select fieldset[disabled] select:-ms-input-placeholder,fieldset[disabled] .textarea:-ms-input-placeholder,fieldset[disabled] .input:-ms-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-ms-input-placeholder{color:rgba(107,107,107,0.3)}.textarea,.input,#documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}.textarea[readonly],.input[readonly],#documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}.is-white.textarea,.is-white.input,#documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}.is-white.textarea:focus,.is-white.input:focus,#documenter .docs-sidebar form.docs-search>input.is-white:focus,.is-white.is-focused.textarea,.is-white.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-white.textarea:active,.is-white.input:active,#documenter .docs-sidebar form.docs-search>input.is-white:active,.is-white.is-active.textarea,.is-white.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.is-black.textarea,.is-black.input,#documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}.is-black.textarea:focus,.is-black.input:focus,#documenter .docs-sidebar form.docs-search>input.is-black:focus,.is-black.is-focused.textarea,.is-black.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-black.textarea:active,.is-black.input:active,#documenter .docs-sidebar form.docs-search>input.is-black:active,.is-black.is-active.textarea,.is-black.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.is-light.textarea,.is-light.input,#documenter .docs-sidebar form.docs-search>input.is-light{border-color:#f5f5f5}.is-light.textarea:focus,.is-light.input:focus,#documenter .docs-sidebar form.docs-search>input.is-light:focus,.is-light.is-focused.textarea,.is-light.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-light.textarea:active,.is-light.input:active,#documenter .docs-sidebar form.docs-search>input.is-light:active,.is-light.is-active.textarea,.is-light.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.is-dark.textarea,.content kbd.textarea,.is-dark.input,#documenter .docs-sidebar form.docs-search>input.is-dark,.content kbd.input{border-color:#363636}.is-dark.textarea:focus,.content kbd.textarea:focus,.is-dark.input:focus,#documenter .docs-sidebar form.docs-search>input.is-dark:focus,.content kbd.input:focus,.is-dark.is-focused.textarea,.content kbd.is-focused.textarea,.is-dark.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.content kbd.is-focused.input,#documenter .docs-sidebar .content form.docs-search>input.is-focused,.is-dark.textarea:active,.content kbd.textarea:active,.is-dark.input:active,#documenter .docs-sidebar form.docs-search>input.is-dark:active,.content kbd.input:active,.is-dark.is-active.textarea,.content kbd.is-active.textarea,.is-dark.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.content kbd.is-active.input,#documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.is-primary.textarea,.docstring>section>a.textarea.docs-sourcelink,.is-primary.input,#documenter .docs-sidebar form.docs-search>input.is-primary,.docstring>section>a.input.docs-sourcelink{border-color:#4eb5de}.is-primary.textarea:focus,.docstring>section>a.textarea.docs-sourcelink:focus,.is-primary.input:focus,#documenter .docs-sidebar form.docs-search>input.is-primary:focus,.docstring>section>a.input.docs-sourcelink:focus,.is-primary.is-focused.textarea,.docstring>section>a.is-focused.textarea.docs-sourcelink,.is-primary.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.docstring>section>a.is-focused.input.docs-sourcelink,.is-primary.textarea:active,.docstring>section>a.textarea.docs-sourcelink:active,.is-primary.input:active,#documenter .docs-sidebar form.docs-search>input.is-primary:active,.docstring>section>a.input.docs-sourcelink:active,.is-primary.is-active.textarea,.docstring>section>a.is-active.textarea.docs-sourcelink,.is-primary.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.is-link.textarea,.is-link.input,#documenter .docs-sidebar form.docs-search>input.is-link{border-color:#2e63b8}.is-link.textarea:focus,.is-link.input:focus,#documenter .docs-sidebar form.docs-search>input.is-link:focus,.is-link.is-focused.textarea,.is-link.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-link.textarea:active,.is-link.input:active,#documenter .docs-sidebar form.docs-search>input.is-link:active,.is-link.is-active.textarea,.is-link.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.is-info.textarea,.is-info.input,#documenter .docs-sidebar form.docs-search>input.is-info{border-color:#209cee}.is-info.textarea:focus,.is-info.input:focus,#documenter .docs-sidebar form.docs-search>input.is-info:focus,.is-info.is-focused.textarea,.is-info.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-info.textarea:active,.is-info.input:active,#documenter .docs-sidebar form.docs-search>input.is-info:active,.is-info.is-active.textarea,.is-info.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.is-success.textarea,.is-success.input,#documenter .docs-sidebar form.docs-search>input.is-success{border-color:#22c35b}.is-success.textarea:focus,.is-success.input:focus,#documenter .docs-sidebar form.docs-search>input.is-success:focus,.is-success.is-focused.textarea,.is-success.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-success.textarea:active,.is-success.input:active,#documenter .docs-sidebar form.docs-search>input.is-success:active,.is-success.is-active.textarea,.is-success.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.is-warning.textarea,.is-warning.input,#documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ffdd57}.is-warning.textarea:focus,.is-warning.input:focus,#documenter .docs-sidebar form.docs-search>input.is-warning:focus,.is-warning.is-focused.textarea,.is-warning.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-warning.textarea:active,.is-warning.input:active,#documenter .docs-sidebar form.docs-search>input.is-warning:active,.is-warning.is-active.textarea,.is-warning.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.is-danger.textarea,.is-danger.input,#documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#da0b00}.is-danger.textarea:focus,.is-danger.input:focus,#documenter .docs-sidebar form.docs-search>input.is-danger:focus,.is-danger.is-focused.textarea,.is-danger.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-danger.textarea:active,.is-danger.input:active,#documenter .docs-sidebar form.docs-search>input.is-danger:active,.is-danger.is-active.textarea,.is-danger.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.is-small.textarea,.is-small.input,#documenter .docs-sidebar form.docs-search>input{border-radius:2px;font-size:.75rem}.is-medium.textarea,.is-medium.input,#documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}.is-large.textarea,.is-large.input,#documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}.is-fullwidth.textarea,.is-fullwidth.input,#documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}.is-inline.textarea,.is-inline.input,#documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}.input.is-rounded,#documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}.input.is-static,#documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}.textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}.textarea:not([rows]){max-height:40em;min-height:8em}.textarea[rows]{height:initial}.textarea.has-fixed-size{resize:none}.radio,.checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}.radio input,.checkbox input{cursor:pointer}.radio:hover,.checkbox:hover{color:#222}.radio[disabled],.checkbox[disabled],fieldset[disabled] .radio,fieldset[disabled] .checkbox,.radio input[disabled],.checkbox input[disabled]{color:#6b6b6b;cursor:not-allowed}.radio+.radio{margin-left:.5em}.select{display:inline-block;max-width:100%;position:relative;vertical-align:top}.select:not(.is-multiple){height:2.5em}.select:not(.is-multiple):not(.is-loading)::after{border-color:#2e63b8;right:1.125em;z-index:4}.select.is-rounded select,#documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}.select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}.select select::-ms-expand{display:none}.select select[disabled]:hover,fieldset[disabled] .select select:hover{border-color:#f5f5f5}.select select:not([multiple]){padding-right:2.5em}.select select[multiple]{height:auto;padding:0}.select select[multiple] option{padding:0.5em 1em}.select:not(.is-multiple):not(.is-loading):hover::after{border-color:#222}.select.is-white:not(:hover)::after{border-color:#fff}.select.is-white select{border-color:#fff}.select.is-white select:hover,.select.is-white select.is-hovered{border-color:#f2f2f2}.select.is-white select:focus,.select.is-white select.is-focused,.select.is-white select:active,.select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.select.is-black:not(:hover)::after{border-color:#0a0a0a}.select.is-black select{border-color:#0a0a0a}.select.is-black select:hover,.select.is-black select.is-hovered{border-color:#000}.select.is-black select:focus,.select.is-black select.is-focused,.select.is-black select:active,.select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.select.is-light:not(:hover)::after{border-color:#f5f5f5}.select.is-light select{border-color:#f5f5f5}.select.is-light select:hover,.select.is-light select.is-hovered{border-color:#e8e8e8}.select.is-light select:focus,.select.is-light select.is-focused,.select.is-light select:active,.select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.select.is-dark:not(:hover)::after,.content kbd.select:not(:hover)::after{border-color:#363636}.select.is-dark select,.content kbd.select select{border-color:#363636}.select.is-dark select:hover,.content kbd.select select:hover,.select.is-dark select.is-hovered,.content kbd.select select.is-hovered{border-color:#292929}.select.is-dark select:focus,.content kbd.select select:focus,.select.is-dark select.is-focused,.content kbd.select select.is-focused,.select.is-dark select:active,.content kbd.select select:active,.select.is-dark select.is-active,.content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.select.is-primary:not(:hover)::after,.docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#4eb5de}.select.is-primary select,.docstring>section>a.select.docs-sourcelink select{border-color:#4eb5de}.select.is-primary select:hover,.docstring>section>a.select.docs-sourcelink select:hover,.select.is-primary select.is-hovered,.docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#39acda}.select.is-primary select:focus,.docstring>section>a.select.docs-sourcelink select:focus,.select.is-primary select.is-focused,.docstring>section>a.select.docs-sourcelink select.is-focused,.select.is-primary select:active,.docstring>section>a.select.docs-sourcelink select:active,.select.is-primary select.is-active,.docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.select.is-link:not(:hover)::after{border-color:#2e63b8}.select.is-link select{border-color:#2e63b8}.select.is-link select:hover,.select.is-link select.is-hovered{border-color:#2958a4}.select.is-link select:focus,.select.is-link select.is-focused,.select.is-link select:active,.select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select.is-info:not(:hover)::after{border-color:#209cee}.select.is-info select{border-color:#209cee}.select.is-info select:hover,.select.is-info select.is-hovered{border-color:#1190e3}.select.is-info select:focus,.select.is-info select.is-focused,.select.is-info select:active,.select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.select.is-success:not(:hover)::after{border-color:#22c35b}.select.is-success select{border-color:#22c35b}.select.is-success select:hover,.select.is-success select.is-hovered{border-color:#1ead51}.select.is-success select:focus,.select.is-success select.is-focused,.select.is-success select:active,.select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.select.is-warning:not(:hover)::after{border-color:#ffdd57}.select.is-warning select{border-color:#ffdd57}.select.is-warning select:hover,.select.is-warning select.is-hovered{border-color:#ffd83e}.select.is-warning select:focus,.select.is-warning select.is-focused,.select.is-warning select:active,.select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.select.is-danger:not(:hover)::after{border-color:#da0b00}.select.is-danger select{border-color:#da0b00}.select.is-danger select:hover,.select.is-danger select.is-hovered{border-color:#c10a00}.select.is-danger select:focus,.select.is-danger select.is-focused,.select.is-danger select:active,.select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.select.is-small,#documenter .docs-sidebar form.docs-search>input.select{border-radius:2px;font-size:.75rem}.select.is-medium{font-size:1.25rem}.select.is-large{font-size:1.5rem}.select.is-disabled::after{border-color:#6b6b6b !important;opacity:0.5}.select.is-fullwidth{width:100%}.select.is-fullwidth select{width:100%}.select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}.select.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.select.is-loading.is-medium:after{font-size:1.25rem}.select.is-loading.is-large:after{font-size:1.5rem}.file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}.file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}.file.is-white:hover .file-cta,.file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.file.is-white:focus .file-cta,.file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}.file.is-white:active .file-cta,.file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}.file.is-black:hover .file-cta,.file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}.file.is-black:focus .file-cta,.file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}.file.is-black:active .file-cta,.file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}.file.is-light .file-cta{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:hover .file-cta,.file.is-light.is-hovered .file-cta{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:focus .file-cta,.file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(245,245,245,0.25);color:rgba(0,0,0,0.7)}.file.is-light:active .file-cta,.file.is-light.is-active .file-cta{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-dark .file-cta,.content kbd.file .file-cta{background-color:#363636;border-color:transparent;color:#fff}.file.is-dark:hover .file-cta,.content kbd.file:hover .file-cta,.file.is-dark.is-hovered .file-cta,.content kbd.file.is-hovered .file-cta{background-color:#2f2f2f;border-color:transparent;color:#fff}.file.is-dark:focus .file-cta,.content kbd.file:focus .file-cta,.file.is-dark.is-focused .file-cta,.content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(54,54,54,0.25);color:#fff}.file.is-dark:active .file-cta,.content kbd.file:active .file-cta,.file.is-dark.is-active .file-cta,.content kbd.file.is-active .file-cta{background-color:#292929;border-color:transparent;color:#fff}.file.is-primary .file-cta,.docstring>section>a.file.docs-sourcelink .file-cta{background-color:#4eb5de;border-color:transparent;color:#fff}.file.is-primary:hover .file-cta,.docstring>section>a.file.docs-sourcelink:hover .file-cta,.file.is-primary.is-hovered .file-cta,.docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#43b1dc;border-color:transparent;color:#fff}.file.is-primary:focus .file-cta,.docstring>section>a.file.docs-sourcelink:focus .file-cta,.file.is-primary.is-focused .file-cta,.docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(78,181,222,0.25);color:#fff}.file.is-primary:active .file-cta,.docstring>section>a.file.docs-sourcelink:active .file-cta,.file.is-primary.is-active .file-cta,.docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#39acda;border-color:transparent;color:#fff}.file.is-link .file-cta{background-color:#2e63b8;border-color:transparent;color:#fff}.file.is-link:hover .file-cta,.file.is-link.is-hovered .file-cta{background-color:#2b5eae;border-color:transparent;color:#fff}.file.is-link:focus .file-cta,.file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(46,99,184,0.25);color:#fff}.file.is-link:active .file-cta,.file.is-link.is-active .file-cta{background-color:#2958a4;border-color:transparent;color:#fff}.file.is-info .file-cta{background-color:#209cee;border-color:transparent;color:#fff}.file.is-info:hover .file-cta,.file.is-info.is-hovered .file-cta{background-color:#1497ed;border-color:transparent;color:#fff}.file.is-info:focus .file-cta,.file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(32,156,238,0.25);color:#fff}.file.is-info:active .file-cta,.file.is-info.is-active .file-cta{background-color:#1190e3;border-color:transparent;color:#fff}.file.is-success .file-cta{background-color:#22c35b;border-color:transparent;color:#fff}.file.is-success:hover .file-cta,.file.is-success.is-hovered .file-cta{background-color:#20b856;border-color:transparent;color:#fff}.file.is-success:focus .file-cta,.file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(34,195,91,0.25);color:#fff}.file.is-success:active .file-cta,.file.is-success.is-active .file-cta{background-color:#1ead51;border-color:transparent;color:#fff}.file.is-warning .file-cta{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:hover .file-cta,.file.is-warning.is-hovered .file-cta{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:focus .file-cta,.file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,221,87,0.25);color:rgba(0,0,0,0.7)}.file.is-warning:active .file-cta,.file.is-warning.is-active .file-cta{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-danger .file-cta{background-color:#da0b00;border-color:transparent;color:#fff}.file.is-danger:hover .file-cta,.file.is-danger.is-hovered .file-cta{background-color:#cd0a00;border-color:transparent;color:#fff}.file.is-danger:focus .file-cta,.file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(218,11,0,0.25);color:#fff}.file.is-danger:active .file-cta,.file.is-danger.is-active .file-cta{background-color:#c10a00;border-color:transparent;color:#fff}.file.is-small,#documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}.file.is-normal{font-size:1rem}.file.is-medium{font-size:1.25rem}.file.is-medium .file-icon .fa{font-size:21px}.file.is-large{font-size:1.5rem}.file.is-large .file-icon .fa{font-size:28px}.file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}.file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}.file.has-name.is-empty .file-cta{border-radius:4px}.file.has-name.is-empty .file-name{display:none}.file.is-boxed .file-label{flex-direction:column}.file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}.file.is-boxed .file-name{border-width:0 1px 1px}.file.is-boxed .file-icon{height:1.5em;width:1.5em}.file.is-boxed .file-icon .fa{font-size:21px}.file.is-boxed.is-small .file-icon .fa,#documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}.file.is-boxed.is-medium .file-icon .fa{font-size:28px}.file.is-boxed.is-large .file-icon .fa{font-size:35px}.file.is-boxed.has-name .file-cta{border-radius:4px 4px 0 0}.file.is-boxed.has-name .file-name{border-radius:0 0 4px 4px;border-width:0 1px 1px}.file.is-centered{justify-content:center}.file.is-fullwidth .file-label{width:100%}.file.is-fullwidth .file-name{flex-grow:1;max-width:none}.file.is-right{justify-content:flex-end}.file.is-right .file-cta{border-radius:0 4px 4px 0}.file.is-right .file-name{border-radius:4px 0 0 4px;border-width:1px 0 1px 1px;order:-1}.file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}.file-label:hover .file-cta{background-color:#eee;color:#222}.file-label:hover .file-name{border-color:#d5d5d5}.file-label:active .file-cta{background-color:#e8e8e8;color:#222}.file-label:active .file-name{border-color:#cfcfcf}.file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}.file-cta,.file-name{border-color:#dbdbdb;border-radius:4px;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}.file-cta{background-color:#f5f5f5;color:#222}.file-name{border-color:#dbdbdb;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}.file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}.file-icon .fa{font-size:14px}.label{color:#222;display:block;font-size:1rem;font-weight:700}.label:not(:last-child){margin-bottom:0.5em}.label.is-small,#documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}.label.is-medium{font-size:1.25rem}.label.is-large{font-size:1.5rem}.help{display:block;font-size:.75rem;margin-top:0.25rem}.help.is-white{color:#fff}.help.is-black{color:#0a0a0a}.help.is-light{color:#f5f5f5}.help.is-dark,.content kbd.help{color:#363636}.help.is-primary,.docstring>section>a.help.docs-sourcelink{color:#4eb5de}.help.is-link{color:#2e63b8}.help.is-info{color:#209cee}.help.is-success{color:#22c35b}.help.is-warning{color:#ffdd57}.help.is-danger{color:#da0b00}.field:not(:last-child){margin-bottom:0.75rem}.field.has-addons{display:flex;justify-content:flex-start}.field.has-addons .control:not(:last-child){margin-right:-1px}.field.has-addons .control:not(:first-child):not(:last-child) .button,.field.has-addons .control:not(:first-child):not(:last-child) .input,.field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,.field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}.field.has-addons .control:first-child:not(:only-child) .button,.field.has-addons .control:first-child:not(:only-child) .input,.field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,.field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}.field.has-addons .control:last-child:not(:only-child) .button,.field.has-addons .control:last-child:not(:only-child) .input,.field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,.field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}.field.has-addons .control .button:not([disabled]):hover,.field.has-addons .control .button.is-hovered:not([disabled]),.field.has-addons .control .input:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,.field.has-addons .control .input.is-hovered:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),.field.has-addons .control .select select:not([disabled]):hover,.field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}.field.has-addons .control .button:not([disabled]):focus,.field.has-addons .control .button.is-focused:not([disabled]),.field.has-addons .control .button:not([disabled]):active,.field.has-addons .control .button.is-active:not([disabled]),.field.has-addons .control .input:not([disabled]):focus,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,.field.has-addons .control .input.is-focused:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),.field.has-addons .control .input:not([disabled]):active,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,.field.has-addons .control .input.is-active:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),.field.has-addons .control .select select:not([disabled]):focus,.field.has-addons .control .select select.is-focused:not([disabled]),.field.has-addons .control .select select:not([disabled]):active,.field.has-addons .control .select select.is-active:not([disabled]){z-index:3}.field.has-addons .control .button:not([disabled]):focus:hover,.field.has-addons .control .button.is-focused:not([disabled]):hover,.field.has-addons .control .button:not([disabled]):active:hover,.field.has-addons .control .button.is-active:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):focus:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,.field.has-addons .control .input.is-focused:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):active:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,.field.has-addons .control .input.is-active:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):focus:hover,.field.has-addons .control .select select.is-focused:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):active:hover,.field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}.field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}.field.has-addons.has-addons-centered{justify-content:center}.field.has-addons.has-addons-right{justify-content:flex-end}.field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}.field.is-grouped{display:flex;justify-content:flex-start}.field.is-grouped>.control{flex-shrink:0}.field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}.field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}.field.is-grouped.is-grouped-centered{justify-content:center}.field.is-grouped.is-grouped-right{justify-content:flex-end}.field.is-grouped.is-grouped-multiline{flex-wrap:wrap}.field.is-grouped.is-grouped-multiline>.control:last-child,.field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}.field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}.field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{.field.is-horizontal{display:flex}}.field-label .label{font-size:inherit}@media screen and (max-width: 768px){.field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{.field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}.field-label.is-small,#documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}.field-label.is-normal{padding-top:0.375em}.field-label.is-medium{font-size:1.25rem;padding-top:0.375em}.field-label.is-large{font-size:1.5rem;padding-top:0.375em}}.field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{.field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}.field-body .field{margin-bottom:0}.field-body>.field{flex-shrink:1}.field-body>.field:not(.is-narrow){flex-grow:1}.field-body>.field:not(:last-child){margin-right:.75rem}}.control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}.control.has-icons-left .input:focus~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,.control.has-icons-left .select:focus~.icon,.control.has-icons-right .input:focus~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,.control.has-icons-right .select:focus~.icon{color:#222}.control.has-icons-left .input.is-small~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,.control.has-icons-left .select.is-small~.icon,.control.has-icons-right .input.is-small~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,.control.has-icons-right .select.is-small~.icon{font-size:.75rem}.control.has-icons-left .input.is-medium~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,.control.has-icons-left .select.is-medium~.icon,.control.has-icons-right .input.is-medium~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,.control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}.control.has-icons-left .input.is-large~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,.control.has-icons-left .select.is-large~.icon,.control.has-icons-right .input.is-large~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,.control.has-icons-right .select.is-large~.icon{font-size:1.5rem}.control.has-icons-left .icon,.control.has-icons-right .icon{color:#dbdbdb;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}.control.has-icons-left .input,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input,.control.has-icons-left .select select{padding-left:2.5em}.control.has-icons-left .icon.is-left{left:0}.control.has-icons-right .input,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input,.control.has-icons-right .select select{padding-right:2.5em}.control.has-icons-right .icon.is-right{right:0}.control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}.control.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.control.is-loading.is-medium:after{font-size:1.25rem}.control.is-loading.is-large:after{font-size:1.5rem}.breadcrumb{font-size:1rem;white-space:nowrap}.breadcrumb a{align-items:center;color:#2e63b8;display:flex;justify-content:center;padding:0 .75em}.breadcrumb a:hover{color:#363636}.breadcrumb li{align-items:center;display:flex}.breadcrumb li:first-child a{padding-left:0}.breadcrumb li.is-active a{color:#222;cursor:default;pointer-events:none}.breadcrumb li+li::before{color:#b5b5b5;content:"\0002f"}.breadcrumb ul,.breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}.breadcrumb .icon:first-child{margin-right:.5em}.breadcrumb .icon:last-child{margin-left:.5em}.breadcrumb.is-centered ol,.breadcrumb.is-centered ul{justify-content:center}.breadcrumb.is-right ol,.breadcrumb.is-right ul{justify-content:flex-end}.breadcrumb.is-small,#documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}.breadcrumb.is-medium{font-size:1.25rem}.breadcrumb.is-large{font-size:1.5rem}.breadcrumb.has-arrow-separator li+li::before{content:"\02192"}.breadcrumb.has-bullet-separator li+li::before{content:"\02022"}.breadcrumb.has-dot-separator li+li::before{content:"\000b7"}.breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}.card{background-color:#fff;border-radius:.25rem;box-shadow:#bbb;color:#222;max-width:100%;position:relative}.card-footer:first-child,.card-content:first-child,.card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-footer:last-child,.card-content:last-child,.card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}.card-header-title{align-items:center;color:#222;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}.card-header-title.is-centered{justify-content:center}.card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}.card-image{display:block;position:relative}.card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-content{background-color:rgba(0,0,0,0);padding:1.5rem}.card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}.card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}.card-footer-item:not(:last-child){border-right:1px solid #ededed}.card .media:not(:last-child){margin-bottom:1.5rem}.dropdown{display:inline-flex;position:relative;vertical-align:top}.dropdown.is-active .dropdown-menu,.dropdown.is-hoverable:hover .dropdown-menu{display:block}.dropdown.is-right .dropdown-menu{left:auto;right:0}.dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}.dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}.dropdown-content{background-color:#fff;border-radius:4px;box-shadow:#bbb;padding-bottom:.5rem;padding-top:.5rem}.dropdown-item{color:#222;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}a.dropdown-item,button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}a.dropdown-item:hover,button.dropdown-item:hover{background-color:#f5f5f5;color:#0a0a0a}a.dropdown-item.is-active,button.dropdown-item.is-active{background-color:#2e63b8;color:#fff}.dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}.level{align-items:center;justify-content:space-between}.level code{border-radius:4px}.level img{display:inline-block;vertical-align:top}.level.is-mobile{display:flex}.level.is-mobile .level-left,.level.is-mobile .level-right{display:flex}.level.is-mobile .level-left+.level-right{margin-top:0}.level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}.level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{.level{display:flex}.level>.level-item:not(.is-narrow){flex-grow:1}}.level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}.level-item .title,.level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){.level-item:not(:last-child){margin-bottom:.75rem}}.level-left,.level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.level-left .level-item.is-flexible,.level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{.level-left .level-item:not(:last-child),.level-right .level-item:not(:last-child){margin-right:.75rem}}.level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){.level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{.level-left{display:flex}}.level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{.level-right{display:flex}}.media{align-items:flex-start;display:flex;text-align:inherit}.media .content:not(:last-child){margin-bottom:.75rem}.media .media{border-top:1px solid rgba(219,219,219,0.5);display:flex;padding-top:.75rem}.media .media .content:not(:last-child),.media .media .control:not(:last-child){margin-bottom:.5rem}.media .media .media{padding-top:.5rem}.media .media .media+.media{margin-top:.5rem}.media+.media{border-top:1px solid rgba(219,219,219,0.5);margin-top:1rem;padding-top:1rem}.media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}.media-left,.media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.media-left{margin-right:1rem}.media-right{margin-left:1rem}.media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){.media-content{overflow-x:auto}}.menu{font-size:1rem}.menu.is-small,#documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}.menu.is-medium{font-size:1.25rem}.menu.is-large{font-size:1.5rem}.menu-list{line-height:1.25}.menu-list a{border-radius:2px;color:#222;display:block;padding:0.5em 0.75em}.menu-list a:hover{background-color:#f5f5f5;color:#222}.menu-list a.is-active{background-color:#2e63b8;color:#fff}.menu-list li ul{border-left:1px solid #dbdbdb;margin:.75em;padding-left:.75em}.menu-label{color:#6b6b6b;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}.menu-label:not(:first-child){margin-top:1em}.menu-label:not(:last-child){margin-bottom:1em}.message{background-color:#f5f5f5;border-radius:4px;font-size:1rem}.message strong{color:currentColor}.message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}.message.is-small,#documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}.message.is-medium{font-size:1.25rem}.message.is-large{font-size:1.5rem}.message.is-white{background-color:#fff}.message.is-white .message-header{background-color:#fff;color:#0a0a0a}.message.is-white .message-body{border-color:#fff}.message.is-black{background-color:#fafafa}.message.is-black .message-header{background-color:#0a0a0a;color:#fff}.message.is-black .message-body{border-color:#0a0a0a}.message.is-light{background-color:#fafafa}.message.is-light .message-header{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.message.is-light .message-body{border-color:#f5f5f5}.message.is-dark,.content kbd.message{background-color:#fafafa}.message.is-dark .message-header,.content kbd.message .message-header{background-color:#363636;color:#fff}.message.is-dark .message-body,.content kbd.message .message-body{border-color:#363636}.message.is-primary,.docstring>section>a.message.docs-sourcelink{background-color:#eef8fc}.message.is-primary .message-header,.docstring>section>a.message.docs-sourcelink .message-header{background-color:#4eb5de;color:#fff}.message.is-primary .message-body,.docstring>section>a.message.docs-sourcelink .message-body{border-color:#4eb5de;color:#1a6d8e}.message.is-link{background-color:#eff3fb}.message.is-link .message-header{background-color:#2e63b8;color:#fff}.message.is-link .message-body{border-color:#2e63b8;color:#3169c4}.message.is-info{background-color:#ecf7fe}.message.is-info .message-header{background-color:#209cee;color:#fff}.message.is-info .message-body{border-color:#209cee;color:#0e72b4}.message.is-success{background-color:#eefcf3}.message.is-success .message-header{background-color:#22c35b;color:#fff}.message.is-success .message-body{border-color:#22c35b;color:#198f43}.message.is-warning{background-color:#fffbeb}.message.is-warning .message-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.message.is-warning .message-body{border-color:#ffdd57;color:#947600}.message.is-danger{background-color:#ffeceb}.message.is-danger .message-header{background-color:#da0b00;color:#fff}.message.is-danger .message-body{border-color:#da0b00;color:#f50c00}.message-header{align-items:center;background-color:#222;border-radius:4px 4px 0 0;color:#fff;display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}.message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}.message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}.message-body{border-color:#dbdbdb;border-radius:4px;border-style:solid;border-width:0 0 0 4px;color:#222;padding:1.25em 1.5em}.message-body code,.message-body pre{background-color:#fff}.message-body pre code{background-color:rgba(0,0,0,0)}.modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}.modal.is-active{display:flex}.modal-background{background-color:rgba(10,10,10,0.86)}.modal-content,.modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){.modal-content,.modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}.modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}.modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}.modal-card-head,.modal-card-foot{align-items:center;background-color:#f5f5f5;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}.modal-card-head{border-bottom:1px solid #dbdbdb;border-top-left-radius:6px;border-top-right-radius:6px}.modal-card-title{color:#222;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}.modal-card-foot{border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:1px solid #dbdbdb}.modal-card-foot .button:not(:last-child){margin-right:.5em}.modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}.navbar{background-color:#fff;min-height:3.25rem;position:relative;z-index:30}.navbar.is-white{background-color:#fff;color:#0a0a0a}.navbar.is-white .navbar-brand>.navbar-item,.navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-brand>a.navbar-item:focus,.navbar.is-white .navbar-brand>a.navbar-item:hover,.navbar.is-white .navbar-brand>a.navbar-item.is-active,.navbar.is-white .navbar-brand .navbar-link:focus,.navbar.is-white .navbar-brand .navbar-link:hover,.navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){.navbar.is-white .navbar-start>.navbar-item,.navbar.is-white .navbar-start .navbar-link,.navbar.is-white .navbar-end>.navbar-item,.navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-start>a.navbar-item:focus,.navbar.is-white .navbar-start>a.navbar-item:hover,.navbar.is-white .navbar-start>a.navbar-item.is-active,.navbar.is-white .navbar-start .navbar-link:focus,.navbar.is-white .navbar-start .navbar-link:hover,.navbar.is-white .navbar-start .navbar-link.is-active,.navbar.is-white .navbar-end>a.navbar-item:focus,.navbar.is-white .navbar-end>a.navbar-item:hover,.navbar.is-white .navbar-end>a.navbar-item.is-active,.navbar.is-white .navbar-end .navbar-link:focus,.navbar.is-white .navbar-end .navbar-link:hover,.navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-start .navbar-link::after,.navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}.navbar.is-black{background-color:#0a0a0a;color:#fff}.navbar.is-black .navbar-brand>.navbar-item,.navbar.is-black .navbar-brand .navbar-link{color:#fff}.navbar.is-black .navbar-brand>a.navbar-item:focus,.navbar.is-black .navbar-brand>a.navbar-item:hover,.navbar.is-black .navbar-brand>a.navbar-item.is-active,.navbar.is-black .navbar-brand .navbar-link:focus,.navbar.is-black .navbar-brand .navbar-link:hover,.navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-black .navbar-start>.navbar-item,.navbar.is-black .navbar-start .navbar-link,.navbar.is-black .navbar-end>.navbar-item,.navbar.is-black .navbar-end .navbar-link{color:#fff}.navbar.is-black .navbar-start>a.navbar-item:focus,.navbar.is-black .navbar-start>a.navbar-item:hover,.navbar.is-black .navbar-start>a.navbar-item.is-active,.navbar.is-black .navbar-start .navbar-link:focus,.navbar.is-black .navbar-start .navbar-link:hover,.navbar.is-black .navbar-start .navbar-link.is-active,.navbar.is-black .navbar-end>a.navbar-item:focus,.navbar.is-black .navbar-end>a.navbar-item:hover,.navbar.is-black .navbar-end>a.navbar-item.is-active,.navbar.is-black .navbar-end .navbar-link:focus,.navbar.is-black .navbar-end .navbar-link:hover,.navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-start .navbar-link::after,.navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}.navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}.navbar.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>.navbar-item,.navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>a.navbar-item:focus,.navbar.is-light .navbar-brand>a.navbar-item:hover,.navbar.is-light .navbar-brand>a.navbar-item.is-active,.navbar.is-light .navbar-brand .navbar-link:focus,.navbar.is-light .navbar-brand .navbar-link:hover,.navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-light .navbar-start>.navbar-item,.navbar.is-light .navbar-start .navbar-link,.navbar.is-light .navbar-end>.navbar-item,.navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start>a.navbar-item:focus,.navbar.is-light .navbar-start>a.navbar-item:hover,.navbar.is-light .navbar-start>a.navbar-item.is-active,.navbar.is-light .navbar-start .navbar-link:focus,.navbar.is-light .navbar-start .navbar-link:hover,.navbar.is-light .navbar-start .navbar-link.is-active,.navbar.is-light .navbar-end>a.navbar-item:focus,.navbar.is-light .navbar-end>a.navbar-item:hover,.navbar.is-light .navbar-end>a.navbar-item.is-active,.navbar.is-light .navbar-end .navbar-link:focus,.navbar.is-light .navbar-end .navbar-link:hover,.navbar.is-light .navbar-end .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start .navbar-link::after,.navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}}.navbar.is-dark,.content kbd.navbar{background-color:#363636;color:#fff}.navbar.is-dark .navbar-brand>.navbar-item,.content kbd.navbar .navbar-brand>.navbar-item,.navbar.is-dark .navbar-brand .navbar-link,.content kbd.navbar .navbar-brand .navbar-link{color:#fff}.navbar.is-dark .navbar-brand>a.navbar-item:focus,.content kbd.navbar .navbar-brand>a.navbar-item:focus,.navbar.is-dark .navbar-brand>a.navbar-item:hover,.content kbd.navbar .navbar-brand>a.navbar-item:hover,.navbar.is-dark .navbar-brand>a.navbar-item.is-active,.content kbd.navbar .navbar-brand>a.navbar-item.is-active,.navbar.is-dark .navbar-brand .navbar-link:focus,.content kbd.navbar .navbar-brand .navbar-link:focus,.navbar.is-dark .navbar-brand .navbar-link:hover,.content kbd.navbar .navbar-brand .navbar-link:hover,.navbar.is-dark .navbar-brand .navbar-link.is-active,.content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-brand .navbar-link::after,.content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-burger,.content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-dark .navbar-start>.navbar-item,.content kbd.navbar .navbar-start>.navbar-item,.navbar.is-dark .navbar-start .navbar-link,.content kbd.navbar .navbar-start .navbar-link,.navbar.is-dark .navbar-end>.navbar-item,.content kbd.navbar .navbar-end>.navbar-item,.navbar.is-dark .navbar-end .navbar-link,.content kbd.navbar .navbar-end .navbar-link{color:#fff}.navbar.is-dark .navbar-start>a.navbar-item:focus,.content kbd.navbar .navbar-start>a.navbar-item:focus,.navbar.is-dark .navbar-start>a.navbar-item:hover,.content kbd.navbar .navbar-start>a.navbar-item:hover,.navbar.is-dark .navbar-start>a.navbar-item.is-active,.content kbd.navbar .navbar-start>a.navbar-item.is-active,.navbar.is-dark .navbar-start .navbar-link:focus,.content kbd.navbar .navbar-start .navbar-link:focus,.navbar.is-dark .navbar-start .navbar-link:hover,.content kbd.navbar .navbar-start .navbar-link:hover,.navbar.is-dark .navbar-start .navbar-link.is-active,.content kbd.navbar .navbar-start .navbar-link.is-active,.navbar.is-dark .navbar-end>a.navbar-item:focus,.content kbd.navbar .navbar-end>a.navbar-item:focus,.navbar.is-dark .navbar-end>a.navbar-item:hover,.content kbd.navbar .navbar-end>a.navbar-item:hover,.navbar.is-dark .navbar-end>a.navbar-item.is-active,.content kbd.navbar .navbar-end>a.navbar-item.is-active,.navbar.is-dark .navbar-end .navbar-link:focus,.content kbd.navbar .navbar-end .navbar-link:focus,.navbar.is-dark .navbar-end .navbar-link:hover,.content kbd.navbar .navbar-end .navbar-link:hover,.navbar.is-dark .navbar-end .navbar-link.is-active,.content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-start .navbar-link::after,.content kbd.navbar .navbar-start .navbar-link::after,.navbar.is-dark .navbar-end .navbar-link::after,.content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,.content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#292929;color:#fff}.navbar.is-dark .navbar-dropdown a.navbar-item.is-active,.content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#363636;color:#fff}}.navbar.is-primary,.docstring>section>a.navbar.docs-sourcelink{background-color:#4eb5de;color:#fff}.navbar.is-primary .navbar-brand>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,.navbar.is-primary .navbar-brand .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}.navbar.is-primary .navbar-brand>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,.navbar.is-primary .navbar-brand>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,.navbar.is-primary .navbar-brand>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,.navbar.is-primary .navbar-brand .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,.navbar.is-primary .navbar-brand .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,.navbar.is-primary .navbar-brand .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-brand .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-burger,.docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-primary .navbar-start>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,.navbar.is-primary .navbar-start .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,.navbar.is-primary .navbar-end>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,.navbar.is-primary .navbar-end .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}.navbar.is-primary .navbar-start>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,.navbar.is-primary .navbar-start>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,.navbar.is-primary .navbar-start>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,.navbar.is-primary .navbar-start .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,.navbar.is-primary .navbar-start .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,.navbar.is-primary .navbar-start .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,.navbar.is-primary .navbar-end>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,.navbar.is-primary .navbar-end>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,.navbar.is-primary .navbar-end>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,.navbar.is-primary .navbar-end .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,.navbar.is-primary .navbar-end .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,.navbar.is-primary .navbar-end .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-start .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,.navbar.is-primary .navbar-end .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-dropdown a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#4eb5de;color:#fff}}.navbar.is-link{background-color:#2e63b8;color:#fff}.navbar.is-link .navbar-brand>.navbar-item,.navbar.is-link .navbar-brand .navbar-link{color:#fff}.navbar.is-link .navbar-brand>a.navbar-item:focus,.navbar.is-link .navbar-brand>a.navbar-item:hover,.navbar.is-link .navbar-brand>a.navbar-item.is-active,.navbar.is-link .navbar-brand .navbar-link:focus,.navbar.is-link .navbar-brand .navbar-link:hover,.navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-link .navbar-start>.navbar-item,.navbar.is-link .navbar-start .navbar-link,.navbar.is-link .navbar-end>.navbar-item,.navbar.is-link .navbar-end .navbar-link{color:#fff}.navbar.is-link .navbar-start>a.navbar-item:focus,.navbar.is-link .navbar-start>a.navbar-item:hover,.navbar.is-link .navbar-start>a.navbar-item.is-active,.navbar.is-link .navbar-start .navbar-link:focus,.navbar.is-link .navbar-start .navbar-link:hover,.navbar.is-link .navbar-start .navbar-link.is-active,.navbar.is-link .navbar-end>a.navbar-item:focus,.navbar.is-link .navbar-end>a.navbar-item:hover,.navbar.is-link .navbar-end>a.navbar-item.is-active,.navbar.is-link .navbar-end .navbar-link:focus,.navbar.is-link .navbar-end .navbar-link:hover,.navbar.is-link .navbar-end .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-start .navbar-link::after,.navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#2e63b8;color:#fff}}.navbar.is-info{background-color:#209cee;color:#fff}.navbar.is-info .navbar-brand>.navbar-item,.navbar.is-info .navbar-brand .navbar-link{color:#fff}.navbar.is-info .navbar-brand>a.navbar-item:focus,.navbar.is-info .navbar-brand>a.navbar-item:hover,.navbar.is-info .navbar-brand>a.navbar-item.is-active,.navbar.is-info .navbar-brand .navbar-link:focus,.navbar.is-info .navbar-brand .navbar-link:hover,.navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-info .navbar-start>.navbar-item,.navbar.is-info .navbar-start .navbar-link,.navbar.is-info .navbar-end>.navbar-item,.navbar.is-info .navbar-end .navbar-link{color:#fff}.navbar.is-info .navbar-start>a.navbar-item:focus,.navbar.is-info .navbar-start>a.navbar-item:hover,.navbar.is-info .navbar-start>a.navbar-item.is-active,.navbar.is-info .navbar-start .navbar-link:focus,.navbar.is-info .navbar-start .navbar-link:hover,.navbar.is-info .navbar-start .navbar-link.is-active,.navbar.is-info .navbar-end>a.navbar-item:focus,.navbar.is-info .navbar-end>a.navbar-item:hover,.navbar.is-info .navbar-end>a.navbar-item.is-active,.navbar.is-info .navbar-end .navbar-link:focus,.navbar.is-info .navbar-end .navbar-link:hover,.navbar.is-info .navbar-end .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-start .navbar-link::after,.navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#209cee;color:#fff}}.navbar.is-success{background-color:#22c35b;color:#fff}.navbar.is-success .navbar-brand>.navbar-item,.navbar.is-success .navbar-brand .navbar-link{color:#fff}.navbar.is-success .navbar-brand>a.navbar-item:focus,.navbar.is-success .navbar-brand>a.navbar-item:hover,.navbar.is-success .navbar-brand>a.navbar-item.is-active,.navbar.is-success .navbar-brand .navbar-link:focus,.navbar.is-success .navbar-brand .navbar-link:hover,.navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-success .navbar-start>.navbar-item,.navbar.is-success .navbar-start .navbar-link,.navbar.is-success .navbar-end>.navbar-item,.navbar.is-success .navbar-end .navbar-link{color:#fff}.navbar.is-success .navbar-start>a.navbar-item:focus,.navbar.is-success .navbar-start>a.navbar-item:hover,.navbar.is-success .navbar-start>a.navbar-item.is-active,.navbar.is-success .navbar-start .navbar-link:focus,.navbar.is-success .navbar-start .navbar-link:hover,.navbar.is-success .navbar-start .navbar-link.is-active,.navbar.is-success .navbar-end>a.navbar-item:focus,.navbar.is-success .navbar-end>a.navbar-item:hover,.navbar.is-success .navbar-end>a.navbar-item.is-active,.navbar.is-success .navbar-end .navbar-link:focus,.navbar.is-success .navbar-end .navbar-link:hover,.navbar.is-success .navbar-end .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-start .navbar-link::after,.navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#22c35b;color:#fff}}.navbar.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>.navbar-item,.navbar.is-warning .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>a.navbar-item:focus,.navbar.is-warning .navbar-brand>a.navbar-item:hover,.navbar.is-warning .navbar-brand>a.navbar-item.is-active,.navbar.is-warning .navbar-brand .navbar-link:focus,.navbar.is-warning .navbar-brand .navbar-link:hover,.navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-warning .navbar-start>.navbar-item,.navbar.is-warning .navbar-start .navbar-link,.navbar.is-warning .navbar-end>.navbar-item,.navbar.is-warning .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start>a.navbar-item:focus,.navbar.is-warning .navbar-start>a.navbar-item:hover,.navbar.is-warning .navbar-start>a.navbar-item.is-active,.navbar.is-warning .navbar-start .navbar-link:focus,.navbar.is-warning .navbar-start .navbar-link:hover,.navbar.is-warning .navbar-start .navbar-link.is-active,.navbar.is-warning .navbar-end>a.navbar-item:focus,.navbar.is-warning .navbar-end>a.navbar-item:hover,.navbar.is-warning .navbar-end>a.navbar-item.is-active,.navbar.is-warning .navbar-end .navbar-link:focus,.navbar.is-warning .navbar-end .navbar-link:hover,.navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start .navbar-link::after,.navbar.is-warning .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ffdd57;color:rgba(0,0,0,0.7)}}.navbar.is-danger{background-color:#da0b00;color:#fff}.navbar.is-danger .navbar-brand>.navbar-item,.navbar.is-danger .navbar-brand .navbar-link{color:#fff}.navbar.is-danger .navbar-brand>a.navbar-item:focus,.navbar.is-danger .navbar-brand>a.navbar-item:hover,.navbar.is-danger .navbar-brand>a.navbar-item.is-active,.navbar.is-danger .navbar-brand .navbar-link:focus,.navbar.is-danger .navbar-brand .navbar-link:hover,.navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-danger .navbar-start>.navbar-item,.navbar.is-danger .navbar-start .navbar-link,.navbar.is-danger .navbar-end>.navbar-item,.navbar.is-danger .navbar-end .navbar-link{color:#fff}.navbar.is-danger .navbar-start>a.navbar-item:focus,.navbar.is-danger .navbar-start>a.navbar-item:hover,.navbar.is-danger .navbar-start>a.navbar-item.is-active,.navbar.is-danger .navbar-start .navbar-link:focus,.navbar.is-danger .navbar-start .navbar-link:hover,.navbar.is-danger .navbar-start .navbar-link.is-active,.navbar.is-danger .navbar-end>a.navbar-item:focus,.navbar.is-danger .navbar-end>a.navbar-item:hover,.navbar.is-danger .navbar-end>a.navbar-item.is-active,.navbar.is-danger .navbar-end .navbar-link:focus,.navbar.is-danger .navbar-end .navbar-link:hover,.navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-start .navbar-link::after,.navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#da0b00;color:#fff}}.navbar>.container{align-items:stretch;display:flex;min-height:3.25rem;width:100%}.navbar.has-shadow{box-shadow:0 2px 0 0 #f5f5f5}.navbar.is-fixed-bottom,.navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom{bottom:0}.navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #f5f5f5}.navbar.is-fixed-top{top:0}html.has-navbar-fixed-top,body.has-navbar-fixed-top{padding-top:3.25rem}html.has-navbar-fixed-bottom,body.has-navbar-fixed-bottom{padding-bottom:3.25rem}.navbar-brand,.navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:3.25rem}.navbar-brand a.navbar-item:focus,.navbar-brand a.navbar-item:hover{background-color:transparent}.navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}.navbar-burger{color:#222;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:3.25rem;position:relative;width:3.25rem;margin-left:auto}.navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}.navbar-burger span:nth-child(1){top:calc(50% - 6px)}.navbar-burger span:nth-child(2){top:calc(50% - 1px)}.navbar-burger span:nth-child(3){top:calc(50% + 4px)}.navbar-burger:hover{background-color:rgba(0,0,0,0.05)}.navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}.navbar-burger.is-active span:nth-child(2){opacity:0}.navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}.navbar-menu{display:none}.navbar-item,.navbar-link{color:#222;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}.navbar-item .icon:only-child,.navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}a.navbar-item,.navbar-link{cursor:pointer}a.navbar-item:focus,a.navbar-item:focus-within,a.navbar-item:hover,a.navbar-item.is-active,.navbar-link:focus,.navbar-link:focus-within,.navbar-link:hover,.navbar-link.is-active{background-color:#fafafa;color:#2e63b8}.navbar-item{flex-grow:0;flex-shrink:0}.navbar-item img{max-height:1.75rem}.navbar-item.has-dropdown{padding:0}.navbar-item.is-expanded{flex-grow:1;flex-shrink:1}.navbar-item.is-tab{border-bottom:1px solid transparent;min-height:3.25rem;padding-bottom:calc(0.5rem - 1px)}.navbar-item.is-tab:focus,.navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8}.navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8;border-bottom-style:solid;border-bottom-width:3px;color:#2e63b8;padding-bottom:calc(0.5rem - 3px)}.navbar-content{flex-grow:1;flex-shrink:1}.navbar-link:not(.is-arrowless){padding-right:2.5em}.navbar-link:not(.is-arrowless)::after{border-color:#2e63b8;margin-top:-0.375em;right:1.125em}.navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}.navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}.navbar-divider{background-color:#f5f5f5;border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){.navbar>.container{display:block}.navbar-brand .navbar-item,.navbar-tabs .navbar-item{align-items:center;display:flex}.navbar-link::after{display:none}.navbar-menu{background-color:#fff;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}.navbar-menu.is-active{display:block}.navbar.is-fixed-bottom-touch,.navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-touch{bottom:0}.navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-touch{top:0}.navbar.is-fixed-top .navbar-menu,.navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 3.25rem);overflow:auto}html.has-navbar-fixed-top-touch,body.has-navbar-fixed-top-touch{padding-top:3.25rem}html.has-navbar-fixed-bottom-touch,body.has-navbar-fixed-bottom-touch{padding-bottom:3.25rem}}@media screen and (min-width: 1056px){.navbar,.navbar-menu,.navbar-start,.navbar-end{align-items:stretch;display:flex}.navbar{min-height:3.25rem}.navbar.is-spaced{padding:1rem 2rem}.navbar.is-spaced .navbar-start,.navbar.is-spaced .navbar-end{align-items:center}.navbar.is-spaced a.navbar-item,.navbar.is-spaced .navbar-link{border-radius:4px}.navbar.is-transparent a.navbar-item:focus,.navbar.is-transparent a.navbar-item:hover,.navbar.is-transparent a.navbar-item.is-active,.navbar.is-transparent .navbar-link:focus,.navbar.is-transparent .navbar-link:hover,.navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}.navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}.navbar.is-transparent .navbar-dropdown a.navbar-item:focus,.navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar-burger{display:none}.navbar-item,.navbar-link{align-items:center;display:flex}.navbar-item.has-dropdown{align-items:stretch}.navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}.navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:2px solid #dbdbdb;border-radius:6px 6px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}.navbar-item.is-active .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced .navbar-item.is-active .navbar-dropdown,.navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:hover .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}.navbar-menu{flex-grow:1;flex-shrink:0}.navbar-start{justify-content:flex-start;margin-right:auto}.navbar-end{justify-content:flex-end;margin-left:auto}.navbar-dropdown{background-color:#fff;border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:2px solid #dbdbdb;box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}.navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}.navbar-dropdown a.navbar-item{padding-right:3rem}.navbar-dropdown a.navbar-item:focus,.navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar.is-spaced .navbar-dropdown,.navbar-dropdown.is-boxed{border-radius:6px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}.navbar-dropdown.is-right{left:auto;right:0}.navbar-divider{display:block}.navbar>.container .navbar-brand,.container>.navbar .navbar-brand{margin-left:-.75rem}.navbar>.container .navbar-menu,.container>.navbar .navbar-menu{margin-right:-.75rem}.navbar.is-fixed-bottom-desktop,.navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-desktop{bottom:0}.navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-desktop{top:0}html.has-navbar-fixed-top-desktop,body.has-navbar-fixed-top-desktop{padding-top:3.25rem}html.has-navbar-fixed-bottom-desktop,body.has-navbar-fixed-bottom-desktop{padding-bottom:3.25rem}html.has-spaced-navbar-fixed-top,body.has-spaced-navbar-fixed-top{padding-top:5.25rem}html.has-spaced-navbar-fixed-bottom,body.has-spaced-navbar-fixed-bottom{padding-bottom:5.25rem}a.navbar-item.is-active,.navbar-link.is-active{color:#0a0a0a}a.navbar-item.is-active:not(:focus):not(:hover),.navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}.navbar-item.has-dropdown:focus .navbar-link,.navbar-item.has-dropdown:hover .navbar-link,.navbar-item.has-dropdown.is-active .navbar-link{background-color:#fafafa}}.hero.is-fullheight-with-navbar{min-height:calc(100vh - 3.25rem)}.pagination{font-size:1rem;margin:-.25rem}.pagination.is-small,#documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}.pagination.is-medium{font-size:1.25rem}.pagination.is-large{font-size:1.5rem}.pagination.is-rounded .pagination-previous,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,.pagination.is-rounded .pagination-next,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}.pagination.is-rounded .pagination-link,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}.pagination,.pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}.pagination-previous,.pagination-next,.pagination-link{border-color:#dbdbdb;color:#222;min-width:2.5em}.pagination-previous:hover,.pagination-next:hover,.pagination-link:hover{border-color:#b5b5b5;color:#363636}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus{border-color:#3c5dcd}.pagination-previous:active,.pagination-next:active,.pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}.pagination-previous[disabled],.pagination-previous.is-disabled,.pagination-next[disabled],.pagination-next.is-disabled,.pagination-link[disabled],.pagination-link.is-disabled{background-color:#dbdbdb;border-color:#dbdbdb;box-shadow:none;color:#6b6b6b;opacity:0.5}.pagination-previous,.pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}.pagination-link.is-current{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.pagination-ellipsis{color:#b5b5b5;pointer-events:none}.pagination-list{flex-wrap:wrap}.pagination-list li{list-style:none}@media screen and (max-width: 768px){.pagination{flex-wrap:wrap}.pagination-previous,.pagination-next{flex-grow:1;flex-shrink:1}.pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{.pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{margin-bottom:0;margin-top:0}.pagination-previous{order:2}.pagination-next{order:3}.pagination{justify-content:space-between;margin-bottom:0;margin-top:0}.pagination.is-centered .pagination-previous{order:1}.pagination.is-centered .pagination-list{justify-content:center;order:2}.pagination.is-centered .pagination-next{order:3}.pagination.is-right .pagination-previous{order:1}.pagination.is-right .pagination-next{order:2}.pagination.is-right .pagination-list{justify-content:flex-end;order:3}}.panel{border-radius:6px;box-shadow:#bbb;font-size:1rem}.panel:not(:last-child){margin-bottom:1.5rem}.panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}.panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}.panel.is-white .panel-block.is-active .panel-icon{color:#fff}.panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}.panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}.panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}.panel.is-light .panel-heading{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.panel.is-light .panel-tabs a.is-active{border-bottom-color:#f5f5f5}.panel.is-light .panel-block.is-active .panel-icon{color:#f5f5f5}.panel.is-dark .panel-heading,.content kbd.panel .panel-heading{background-color:#363636;color:#fff}.panel.is-dark .panel-tabs a.is-active,.content kbd.panel .panel-tabs a.is-active{border-bottom-color:#363636}.panel.is-dark .panel-block.is-active .panel-icon,.content kbd.panel .panel-block.is-active .panel-icon{color:#363636}.panel.is-primary .panel-heading,.docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#4eb5de;color:#fff}.panel.is-primary .panel-tabs a.is-active,.docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#4eb5de}.panel.is-primary .panel-block.is-active .panel-icon,.docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#4eb5de}.panel.is-link .panel-heading{background-color:#2e63b8;color:#fff}.panel.is-link .panel-tabs a.is-active{border-bottom-color:#2e63b8}.panel.is-link .panel-block.is-active .panel-icon{color:#2e63b8}.panel.is-info .panel-heading{background-color:#209cee;color:#fff}.panel.is-info .panel-tabs a.is-active{border-bottom-color:#209cee}.panel.is-info .panel-block.is-active .panel-icon{color:#209cee}.panel.is-success .panel-heading{background-color:#22c35b;color:#fff}.panel.is-success .panel-tabs a.is-active{border-bottom-color:#22c35b}.panel.is-success .panel-block.is-active .panel-icon{color:#22c35b}.panel.is-warning .panel-heading{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ffdd57}.panel.is-warning .panel-block.is-active .panel-icon{color:#ffdd57}.panel.is-danger .panel-heading{background-color:#da0b00;color:#fff}.panel.is-danger .panel-tabs a.is-active{border-bottom-color:#da0b00}.panel.is-danger .panel-block.is-active .panel-icon{color:#da0b00}.panel-tabs:not(:last-child),.panel-block:not(:last-child){border-bottom:1px solid #ededed}.panel-heading{background-color:#ededed;border-radius:6px 6px 0 0;color:#222;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}.panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}.panel-tabs a{border-bottom:1px solid #dbdbdb;margin-bottom:-1px;padding:0.5em}.panel-tabs a.is-active{border-bottom-color:#4a4a4a;color:#363636}.panel-list a{color:#222}.panel-list a:hover{color:#2e63b8}.panel-block{align-items:center;color:#222;display:flex;justify-content:flex-start;padding:0.5em 0.75em}.panel-block input[type="checkbox"]{margin-right:.75em}.panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}.panel-block.is-wrapped{flex-wrap:wrap}.panel-block.is-active{border-left-color:#2e63b8;color:#363636}.panel-block.is-active .panel-icon{color:#2e63b8}.panel-block:last-child{border-bottom-left-radius:6px;border-bottom-right-radius:6px}a.panel-block,label.panel-block{cursor:pointer}a.panel-block:hover,label.panel-block:hover{background-color:#f5f5f5}.panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#6b6b6b;margin-right:.75em}.panel-icon .fa{font-size:inherit;line-height:inherit}.tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}.tabs a{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;color:#222;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}.tabs a:hover{border-bottom-color:#222;color:#222}.tabs li{display:block}.tabs li.is-active a{border-bottom-color:#2e63b8;color:#2e63b8}.tabs ul{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}.tabs ul.is-left{padding-right:0.75em}.tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}.tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}.tabs .icon:first-child{margin-right:.5em}.tabs .icon:last-child{margin-left:.5em}.tabs.is-centered ul{justify-content:center}.tabs.is-right ul{justify-content:flex-end}.tabs.is-boxed a{border:1px solid transparent;border-radius:4px 4px 0 0}.tabs.is-boxed a:hover{background-color:#f5f5f5;border-bottom-color:#dbdbdb}.tabs.is-boxed li.is-active a{background-color:#fff;border-color:#dbdbdb;border-bottom-color:rgba(0,0,0,0) !important}.tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}.tabs.is-toggle a{border-color:#dbdbdb;border-style:solid;border-width:1px;margin-bottom:0;position:relative}.tabs.is-toggle a:hover{background-color:#f5f5f5;border-color:#b5b5b5;z-index:2}.tabs.is-toggle li+li{margin-left:-1px}.tabs.is-toggle li:first-child a{border-top-left-radius:4px;border-bottom-left-radius:4px}.tabs.is-toggle li:last-child a{border-top-right-radius:4px;border-bottom-right-radius:4px}.tabs.is-toggle li.is-active a{background-color:#2e63b8;border-color:#2e63b8;color:#fff;z-index:1}.tabs.is-toggle ul{border-bottom:none}.tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}.tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}.tabs.is-small,#documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}.tabs.is-medium{font-size:1.25rem}.tabs.is-large{font-size:1.5rem}.column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>.column.is-narrow{flex:none;width:unset}.columns.is-mobile>.column.is-full{flex:none;width:100%}.columns.is-mobile>.column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>.column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>.column.is-half{flex:none;width:50%}.columns.is-mobile>.column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>.column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>.column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>.column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>.column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>.column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>.column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>.column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>.column.is-offset-half{margin-left:50%}.columns.is-mobile>.column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>.column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>.column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>.column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>.column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>.column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>.column.is-0{flex:none;width:0%}.columns.is-mobile>.column.is-offset-0{margin-left:0%}.columns.is-mobile>.column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>.column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>.column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>.column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>.column.is-3{flex:none;width:25%}.columns.is-mobile>.column.is-offset-3{margin-left:25%}.columns.is-mobile>.column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>.column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>.column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>.column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>.column.is-6{flex:none;width:50%}.columns.is-mobile>.column.is-offset-6{margin-left:50%}.columns.is-mobile>.column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>.column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>.column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>.column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>.column.is-9{flex:none;width:75%}.columns.is-mobile>.column.is-offset-9{margin-left:75%}.columns.is-mobile>.column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>.column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>.column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>.column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>.column.is-12{flex:none;width:100%}.columns.is-mobile>.column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){.column.is-narrow-mobile{flex:none;width:unset}.column.is-full-mobile{flex:none;width:100%}.column.is-three-quarters-mobile{flex:none;width:75%}.column.is-two-thirds-mobile{flex:none;width:66.6666%}.column.is-half-mobile{flex:none;width:50%}.column.is-one-third-mobile{flex:none;width:33.3333%}.column.is-one-quarter-mobile{flex:none;width:25%}.column.is-one-fifth-mobile{flex:none;width:20%}.column.is-two-fifths-mobile{flex:none;width:40%}.column.is-three-fifths-mobile{flex:none;width:60%}.column.is-four-fifths-mobile{flex:none;width:80%}.column.is-offset-three-quarters-mobile{margin-left:75%}.column.is-offset-two-thirds-mobile{margin-left:66.6666%}.column.is-offset-half-mobile{margin-left:50%}.column.is-offset-one-third-mobile{margin-left:33.3333%}.column.is-offset-one-quarter-mobile{margin-left:25%}.column.is-offset-one-fifth-mobile{margin-left:20%}.column.is-offset-two-fifths-mobile{margin-left:40%}.column.is-offset-three-fifths-mobile{margin-left:60%}.column.is-offset-four-fifths-mobile{margin-left:80%}.column.is-0-mobile{flex:none;width:0%}.column.is-offset-0-mobile{margin-left:0%}.column.is-1-mobile{flex:none;width:8.33333337%}.column.is-offset-1-mobile{margin-left:8.33333337%}.column.is-2-mobile{flex:none;width:16.66666674%}.column.is-offset-2-mobile{margin-left:16.66666674%}.column.is-3-mobile{flex:none;width:25%}.column.is-offset-3-mobile{margin-left:25%}.column.is-4-mobile{flex:none;width:33.33333337%}.column.is-offset-4-mobile{margin-left:33.33333337%}.column.is-5-mobile{flex:none;width:41.66666674%}.column.is-offset-5-mobile{margin-left:41.66666674%}.column.is-6-mobile{flex:none;width:50%}.column.is-offset-6-mobile{margin-left:50%}.column.is-7-mobile{flex:none;width:58.33333337%}.column.is-offset-7-mobile{margin-left:58.33333337%}.column.is-8-mobile{flex:none;width:66.66666674%}.column.is-offset-8-mobile{margin-left:66.66666674%}.column.is-9-mobile{flex:none;width:75%}.column.is-offset-9-mobile{margin-left:75%}.column.is-10-mobile{flex:none;width:83.33333337%}.column.is-offset-10-mobile{margin-left:83.33333337%}.column.is-11-mobile{flex:none;width:91.66666674%}.column.is-offset-11-mobile{margin-left:91.66666674%}.column.is-12-mobile{flex:none;width:100%}.column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{.column.is-narrow,.column.is-narrow-tablet{flex:none;width:unset}.column.is-full,.column.is-full-tablet{flex:none;width:100%}.column.is-three-quarters,.column.is-three-quarters-tablet{flex:none;width:75%}.column.is-two-thirds,.column.is-two-thirds-tablet{flex:none;width:66.6666%}.column.is-half,.column.is-half-tablet{flex:none;width:50%}.column.is-one-third,.column.is-one-third-tablet{flex:none;width:33.3333%}.column.is-one-quarter,.column.is-one-quarter-tablet{flex:none;width:25%}.column.is-one-fifth,.column.is-one-fifth-tablet{flex:none;width:20%}.column.is-two-fifths,.column.is-two-fifths-tablet{flex:none;width:40%}.column.is-three-fifths,.column.is-three-fifths-tablet{flex:none;width:60%}.column.is-four-fifths,.column.is-four-fifths-tablet{flex:none;width:80%}.column.is-offset-three-quarters,.column.is-offset-three-quarters-tablet{margin-left:75%}.column.is-offset-two-thirds,.column.is-offset-two-thirds-tablet{margin-left:66.6666%}.column.is-offset-half,.column.is-offset-half-tablet{margin-left:50%}.column.is-offset-one-third,.column.is-offset-one-third-tablet{margin-left:33.3333%}.column.is-offset-one-quarter,.column.is-offset-one-quarter-tablet{margin-left:25%}.column.is-offset-one-fifth,.column.is-offset-one-fifth-tablet{margin-left:20%}.column.is-offset-two-fifths,.column.is-offset-two-fifths-tablet{margin-left:40%}.column.is-offset-three-fifths,.column.is-offset-three-fifths-tablet{margin-left:60%}.column.is-offset-four-fifths,.column.is-offset-four-fifths-tablet{margin-left:80%}.column.is-0,.column.is-0-tablet{flex:none;width:0%}.column.is-offset-0,.column.is-offset-0-tablet{margin-left:0%}.column.is-1,.column.is-1-tablet{flex:none;width:8.33333337%}.column.is-offset-1,.column.is-offset-1-tablet{margin-left:8.33333337%}.column.is-2,.column.is-2-tablet{flex:none;width:16.66666674%}.column.is-offset-2,.column.is-offset-2-tablet{margin-left:16.66666674%}.column.is-3,.column.is-3-tablet{flex:none;width:25%}.column.is-offset-3,.column.is-offset-3-tablet{margin-left:25%}.column.is-4,.column.is-4-tablet{flex:none;width:33.33333337%}.column.is-offset-4,.column.is-offset-4-tablet{margin-left:33.33333337%}.column.is-5,.column.is-5-tablet{flex:none;width:41.66666674%}.column.is-offset-5,.column.is-offset-5-tablet{margin-left:41.66666674%}.column.is-6,.column.is-6-tablet{flex:none;width:50%}.column.is-offset-6,.column.is-offset-6-tablet{margin-left:50%}.column.is-7,.column.is-7-tablet{flex:none;width:58.33333337%}.column.is-offset-7,.column.is-offset-7-tablet{margin-left:58.33333337%}.column.is-8,.column.is-8-tablet{flex:none;width:66.66666674%}.column.is-offset-8,.column.is-offset-8-tablet{margin-left:66.66666674%}.column.is-9,.column.is-9-tablet{flex:none;width:75%}.column.is-offset-9,.column.is-offset-9-tablet{margin-left:75%}.column.is-10,.column.is-10-tablet{flex:none;width:83.33333337%}.column.is-offset-10,.column.is-offset-10-tablet{margin-left:83.33333337%}.column.is-11,.column.is-11-tablet{flex:none;width:91.66666674%}.column.is-offset-11,.column.is-offset-11-tablet{margin-left:91.66666674%}.column.is-12,.column.is-12-tablet{flex:none;width:100%}.column.is-offset-12,.column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){.column.is-narrow-touch{flex:none;width:unset}.column.is-full-touch{flex:none;width:100%}.column.is-three-quarters-touch{flex:none;width:75%}.column.is-two-thirds-touch{flex:none;width:66.6666%}.column.is-half-touch{flex:none;width:50%}.column.is-one-third-touch{flex:none;width:33.3333%}.column.is-one-quarter-touch{flex:none;width:25%}.column.is-one-fifth-touch{flex:none;width:20%}.column.is-two-fifths-touch{flex:none;width:40%}.column.is-three-fifths-touch{flex:none;width:60%}.column.is-four-fifths-touch{flex:none;width:80%}.column.is-offset-three-quarters-touch{margin-left:75%}.column.is-offset-two-thirds-touch{margin-left:66.6666%}.column.is-offset-half-touch{margin-left:50%}.column.is-offset-one-third-touch{margin-left:33.3333%}.column.is-offset-one-quarter-touch{margin-left:25%}.column.is-offset-one-fifth-touch{margin-left:20%}.column.is-offset-two-fifths-touch{margin-left:40%}.column.is-offset-three-fifths-touch{margin-left:60%}.column.is-offset-four-fifths-touch{margin-left:80%}.column.is-0-touch{flex:none;width:0%}.column.is-offset-0-touch{margin-left:0%}.column.is-1-touch{flex:none;width:8.33333337%}.column.is-offset-1-touch{margin-left:8.33333337%}.column.is-2-touch{flex:none;width:16.66666674%}.column.is-offset-2-touch{margin-left:16.66666674%}.column.is-3-touch{flex:none;width:25%}.column.is-offset-3-touch{margin-left:25%}.column.is-4-touch{flex:none;width:33.33333337%}.column.is-offset-4-touch{margin-left:33.33333337%}.column.is-5-touch{flex:none;width:41.66666674%}.column.is-offset-5-touch{margin-left:41.66666674%}.column.is-6-touch{flex:none;width:50%}.column.is-offset-6-touch{margin-left:50%}.column.is-7-touch{flex:none;width:58.33333337%}.column.is-offset-7-touch{margin-left:58.33333337%}.column.is-8-touch{flex:none;width:66.66666674%}.column.is-offset-8-touch{margin-left:66.66666674%}.column.is-9-touch{flex:none;width:75%}.column.is-offset-9-touch{margin-left:75%}.column.is-10-touch{flex:none;width:83.33333337%}.column.is-offset-10-touch{margin-left:83.33333337%}.column.is-11-touch{flex:none;width:91.66666674%}.column.is-offset-11-touch{margin-left:91.66666674%}.column.is-12-touch{flex:none;width:100%}.column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){.column.is-narrow-desktop{flex:none;width:unset}.column.is-full-desktop{flex:none;width:100%}.column.is-three-quarters-desktop{flex:none;width:75%}.column.is-two-thirds-desktop{flex:none;width:66.6666%}.column.is-half-desktop{flex:none;width:50%}.column.is-one-third-desktop{flex:none;width:33.3333%}.column.is-one-quarter-desktop{flex:none;width:25%}.column.is-one-fifth-desktop{flex:none;width:20%}.column.is-two-fifths-desktop{flex:none;width:40%}.column.is-three-fifths-desktop{flex:none;width:60%}.column.is-four-fifths-desktop{flex:none;width:80%}.column.is-offset-three-quarters-desktop{margin-left:75%}.column.is-offset-two-thirds-desktop{margin-left:66.6666%}.column.is-offset-half-desktop{margin-left:50%}.column.is-offset-one-third-desktop{margin-left:33.3333%}.column.is-offset-one-quarter-desktop{margin-left:25%}.column.is-offset-one-fifth-desktop{margin-left:20%}.column.is-offset-two-fifths-desktop{margin-left:40%}.column.is-offset-three-fifths-desktop{margin-left:60%}.column.is-offset-four-fifths-desktop{margin-left:80%}.column.is-0-desktop{flex:none;width:0%}.column.is-offset-0-desktop{margin-left:0%}.column.is-1-desktop{flex:none;width:8.33333337%}.column.is-offset-1-desktop{margin-left:8.33333337%}.column.is-2-desktop{flex:none;width:16.66666674%}.column.is-offset-2-desktop{margin-left:16.66666674%}.column.is-3-desktop{flex:none;width:25%}.column.is-offset-3-desktop{margin-left:25%}.column.is-4-desktop{flex:none;width:33.33333337%}.column.is-offset-4-desktop{margin-left:33.33333337%}.column.is-5-desktop{flex:none;width:41.66666674%}.column.is-offset-5-desktop{margin-left:41.66666674%}.column.is-6-desktop{flex:none;width:50%}.column.is-offset-6-desktop{margin-left:50%}.column.is-7-desktop{flex:none;width:58.33333337%}.column.is-offset-7-desktop{margin-left:58.33333337%}.column.is-8-desktop{flex:none;width:66.66666674%}.column.is-offset-8-desktop{margin-left:66.66666674%}.column.is-9-desktop{flex:none;width:75%}.column.is-offset-9-desktop{margin-left:75%}.column.is-10-desktop{flex:none;width:83.33333337%}.column.is-offset-10-desktop{margin-left:83.33333337%}.column.is-11-desktop{flex:none;width:91.66666674%}.column.is-offset-11-desktop{margin-left:91.66666674%}.column.is-12-desktop{flex:none;width:100%}.column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){.column.is-narrow-widescreen{flex:none;width:unset}.column.is-full-widescreen{flex:none;width:100%}.column.is-three-quarters-widescreen{flex:none;width:75%}.column.is-two-thirds-widescreen{flex:none;width:66.6666%}.column.is-half-widescreen{flex:none;width:50%}.column.is-one-third-widescreen{flex:none;width:33.3333%}.column.is-one-quarter-widescreen{flex:none;width:25%}.column.is-one-fifth-widescreen{flex:none;width:20%}.column.is-two-fifths-widescreen{flex:none;width:40%}.column.is-three-fifths-widescreen{flex:none;width:60%}.column.is-four-fifths-widescreen{flex:none;width:80%}.column.is-offset-three-quarters-widescreen{margin-left:75%}.column.is-offset-two-thirds-widescreen{margin-left:66.6666%}.column.is-offset-half-widescreen{margin-left:50%}.column.is-offset-one-third-widescreen{margin-left:33.3333%}.column.is-offset-one-quarter-widescreen{margin-left:25%}.column.is-offset-one-fifth-widescreen{margin-left:20%}.column.is-offset-two-fifths-widescreen{margin-left:40%}.column.is-offset-three-fifths-widescreen{margin-left:60%}.column.is-offset-four-fifths-widescreen{margin-left:80%}.column.is-0-widescreen{flex:none;width:0%}.column.is-offset-0-widescreen{margin-left:0%}.column.is-1-widescreen{flex:none;width:8.33333337%}.column.is-offset-1-widescreen{margin-left:8.33333337%}.column.is-2-widescreen{flex:none;width:16.66666674%}.column.is-offset-2-widescreen{margin-left:16.66666674%}.column.is-3-widescreen{flex:none;width:25%}.column.is-offset-3-widescreen{margin-left:25%}.column.is-4-widescreen{flex:none;width:33.33333337%}.column.is-offset-4-widescreen{margin-left:33.33333337%}.column.is-5-widescreen{flex:none;width:41.66666674%}.column.is-offset-5-widescreen{margin-left:41.66666674%}.column.is-6-widescreen{flex:none;width:50%}.column.is-offset-6-widescreen{margin-left:50%}.column.is-7-widescreen{flex:none;width:58.33333337%}.column.is-offset-7-widescreen{margin-left:58.33333337%}.column.is-8-widescreen{flex:none;width:66.66666674%}.column.is-offset-8-widescreen{margin-left:66.66666674%}.column.is-9-widescreen{flex:none;width:75%}.column.is-offset-9-widescreen{margin-left:75%}.column.is-10-widescreen{flex:none;width:83.33333337%}.column.is-offset-10-widescreen{margin-left:83.33333337%}.column.is-11-widescreen{flex:none;width:91.66666674%}.column.is-offset-11-widescreen{margin-left:91.66666674%}.column.is-12-widescreen{flex:none;width:100%}.column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){.column.is-narrow-fullhd{flex:none;width:unset}.column.is-full-fullhd{flex:none;width:100%}.column.is-three-quarters-fullhd{flex:none;width:75%}.column.is-two-thirds-fullhd{flex:none;width:66.6666%}.column.is-half-fullhd{flex:none;width:50%}.column.is-one-third-fullhd{flex:none;width:33.3333%}.column.is-one-quarter-fullhd{flex:none;width:25%}.column.is-one-fifth-fullhd{flex:none;width:20%}.column.is-two-fifths-fullhd{flex:none;width:40%}.column.is-three-fifths-fullhd{flex:none;width:60%}.column.is-four-fifths-fullhd{flex:none;width:80%}.column.is-offset-three-quarters-fullhd{margin-left:75%}.column.is-offset-two-thirds-fullhd{margin-left:66.6666%}.column.is-offset-half-fullhd{margin-left:50%}.column.is-offset-one-third-fullhd{margin-left:33.3333%}.column.is-offset-one-quarter-fullhd{margin-left:25%}.column.is-offset-one-fifth-fullhd{margin-left:20%}.column.is-offset-two-fifths-fullhd{margin-left:40%}.column.is-offset-three-fifths-fullhd{margin-left:60%}.column.is-offset-four-fifths-fullhd{margin-left:80%}.column.is-0-fullhd{flex:none;width:0%}.column.is-offset-0-fullhd{margin-left:0%}.column.is-1-fullhd{flex:none;width:8.33333337%}.column.is-offset-1-fullhd{margin-left:8.33333337%}.column.is-2-fullhd{flex:none;width:16.66666674%}.column.is-offset-2-fullhd{margin-left:16.66666674%}.column.is-3-fullhd{flex:none;width:25%}.column.is-offset-3-fullhd{margin-left:25%}.column.is-4-fullhd{flex:none;width:33.33333337%}.column.is-offset-4-fullhd{margin-left:33.33333337%}.column.is-5-fullhd{flex:none;width:41.66666674%}.column.is-offset-5-fullhd{margin-left:41.66666674%}.column.is-6-fullhd{flex:none;width:50%}.column.is-offset-6-fullhd{margin-left:50%}.column.is-7-fullhd{flex:none;width:58.33333337%}.column.is-offset-7-fullhd{margin-left:58.33333337%}.column.is-8-fullhd{flex:none;width:66.66666674%}.column.is-offset-8-fullhd{margin-left:66.66666674%}.column.is-9-fullhd{flex:none;width:75%}.column.is-offset-9-fullhd{margin-left:75%}.column.is-10-fullhd{flex:none;width:83.33333337%}.column.is-offset-10-fullhd{margin-left:83.33333337%}.column.is-11-fullhd{flex:none;width:91.66666674%}.column.is-offset-11-fullhd{margin-left:91.66666674%}.column.is-12-fullhd{flex:none;width:100%}.column.is-offset-12-fullhd{margin-left:100%}}.columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.columns:last-child{margin-bottom:-.75rem}.columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}.columns.is-centered{justify-content:center}.columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}.columns.is-gapless>.column{margin:0;padding:0 !important}.columns.is-gapless:not(:last-child){margin-bottom:1.5rem}.columns.is-gapless:last-child{margin-bottom:0}.columns.is-mobile{display:flex}.columns.is-multiline{flex-wrap:wrap}.columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{.columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){.columns.is-desktop{display:flex}}.columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}.columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}.columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){.columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-0-fullhd{--columnGap: 0rem}}.columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){.columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-1-fullhd{--columnGap: .25rem}}.columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){.columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-2-fullhd{--columnGap: .5rem}}.columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){.columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-3-fullhd{--columnGap: .75rem}}.columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){.columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-4-fullhd{--columnGap: 1rem}}.columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){.columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}.columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){.columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}.columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){.columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}.columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){.columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-8-fullhd{--columnGap: 2rem}}.tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}.tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.tile.is-ancestor:last-child{margin-bottom:-.75rem}.tile.is-ancestor:not(:last-child){margin-bottom:.75rem}.tile.is-child{margin:0 !important}.tile.is-parent{padding:.75rem}.tile.is-vertical{flex-direction:column}.tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{.tile:not(.is-child){display:flex}.tile.is-1{flex:none;width:8.33333337%}.tile.is-2{flex:none;width:16.66666674%}.tile.is-3{flex:none;width:25%}.tile.is-4{flex:none;width:33.33333337%}.tile.is-5{flex:none;width:41.66666674%}.tile.is-6{flex:none;width:50%}.tile.is-7{flex:none;width:58.33333337%}.tile.is-8{flex:none;width:66.66666674%}.tile.is-9{flex:none;width:75%}.tile.is-10{flex:none;width:83.33333337%}.tile.is-11{flex:none;width:91.66666674%}.tile.is-12{flex:none;width:100%}}.hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}.hero .navbar{background:none}.hero .tabs ul{border-bottom:none}.hero.is-white{background-color:#fff;color:#0a0a0a}.hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-white strong{color:inherit}.hero.is-white .title{color:#0a0a0a}.hero.is-white .subtitle{color:rgba(10,10,10,0.9)}.hero.is-white .subtitle a:not(.button),.hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){.hero.is-white .navbar-menu{background-color:#fff}}.hero.is-white .navbar-item,.hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}.hero.is-white a.navbar-item:hover,.hero.is-white a.navbar-item.is-active,.hero.is-white .navbar-link:hover,.hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}.hero.is-white .tabs a:hover{opacity:1}.hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}.hero.is-white .tabs.is-boxed a,.hero.is-white .tabs.is-toggle a{color:#0a0a0a}.hero.is-white .tabs.is-boxed a:hover,.hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-white .tabs.is-boxed li.is-active a,.hero.is-white .tabs.is-boxed li.is-active a:hover,.hero.is-white .tabs.is-toggle li.is-active a,.hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}.hero.is-black{background-color:#0a0a0a;color:#fff}.hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-black strong{color:inherit}.hero.is-black .title{color:#fff}.hero.is-black .subtitle{color:rgba(255,255,255,0.9)}.hero.is-black .subtitle a:not(.button),.hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-black .navbar-menu{background-color:#0a0a0a}}.hero.is-black .navbar-item,.hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-black a.navbar-item:hover,.hero.is-black a.navbar-item.is-active,.hero.is-black .navbar-link:hover,.hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}.hero.is-black .tabs a{color:#fff;opacity:0.9}.hero.is-black .tabs a:hover{opacity:1}.hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}.hero.is-black .tabs.is-boxed a,.hero.is-black .tabs.is-toggle a{color:#fff}.hero.is-black .tabs.is-boxed a:hover,.hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-black .tabs.is-boxed li.is-active a,.hero.is-black .tabs.is-boxed li.is-active a:hover,.hero.is-black .tabs.is-toggle li.is-active a,.hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}.hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){.hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}.hero.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-light strong{color:inherit}.hero.is-light .title{color:rgba(0,0,0,0.7)}.hero.is-light .subtitle{color:rgba(0,0,0,0.9)}.hero.is-light .subtitle a:not(.button),.hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-light .navbar-menu{background-color:#f5f5f5}}.hero.is-light .navbar-item,.hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-light a.navbar-item:hover,.hero.is-light a.navbar-item.is-active,.hero.is-light .navbar-link:hover,.hero.is-light .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-light .tabs a:hover{opacity:1}.hero.is-light .tabs li.is-active a{color:#f5f5f5 !important;opacity:1}.hero.is-light .tabs.is-boxed a,.hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-light .tabs.is-boxed a:hover,.hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-light .tabs.is-boxed li.is-active a,.hero.is-light .tabs.is-boxed li.is-active a:hover,.hero.is-light .tabs.is-toggle li.is-active a,.hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#f5f5f5}.hero.is-light.is-bold{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}}.hero.is-dark,.content kbd.hero{background-color:#363636;color:#fff}.hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-dark strong,.content kbd.hero strong{color:inherit}.hero.is-dark .title,.content kbd.hero .title{color:#fff}.hero.is-dark .subtitle,.content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}.hero.is-dark .subtitle a:not(.button),.content kbd.hero .subtitle a:not(.button),.hero.is-dark .subtitle strong,.content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-dark .navbar-menu,.content kbd.hero .navbar-menu{background-color:#363636}}.hero.is-dark .navbar-item,.content kbd.hero .navbar-item,.hero.is-dark .navbar-link,.content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-dark a.navbar-item:hover,.content kbd.hero a.navbar-item:hover,.hero.is-dark a.navbar-item.is-active,.content kbd.hero a.navbar-item.is-active,.hero.is-dark .navbar-link:hover,.content kbd.hero .navbar-link:hover,.hero.is-dark .navbar-link.is-active,.content kbd.hero .navbar-link.is-active{background-color:#292929;color:#fff}.hero.is-dark .tabs a,.content kbd.hero .tabs a{color:#fff;opacity:0.9}.hero.is-dark .tabs a:hover,.content kbd.hero .tabs a:hover{opacity:1}.hero.is-dark .tabs li.is-active a,.content kbd.hero .tabs li.is-active a{color:#363636 !important;opacity:1}.hero.is-dark .tabs.is-boxed a,.content kbd.hero .tabs.is-boxed a,.hero.is-dark .tabs.is-toggle a,.content kbd.hero .tabs.is-toggle a{color:#fff}.hero.is-dark .tabs.is-boxed a:hover,.content kbd.hero .tabs.is-boxed a:hover,.hero.is-dark .tabs.is-toggle a:hover,.content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-dark .tabs.is-boxed li.is-active a,.content kbd.hero .tabs.is-boxed li.is-active a,.hero.is-dark .tabs.is-boxed li.is-active a:hover,.hero.is-dark .tabs.is-toggle li.is-active a,.content kbd.hero .tabs.is-toggle li.is-active a,.hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#363636}.hero.is-dark.is-bold,.content kbd.hero.is-bold{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}@media screen and (max-width: 768px){.hero.is-dark.is-bold .navbar-menu,.content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}}.hero.is-primary,.docstring>section>a.hero.docs-sourcelink{background-color:#4eb5de;color:#fff}.hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-primary strong,.docstring>section>a.hero.docs-sourcelink strong{color:inherit}.hero.is-primary .title,.docstring>section>a.hero.docs-sourcelink .title{color:#fff}.hero.is-primary .subtitle,.docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}.hero.is-primary .subtitle a:not(.button),.docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),.hero.is-primary .subtitle strong,.docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-primary .navbar-menu,.docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#4eb5de}}.hero.is-primary .navbar-item,.docstring>section>a.hero.docs-sourcelink .navbar-item,.hero.is-primary .navbar-link,.docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-primary a.navbar-item:hover,.docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,.hero.is-primary a.navbar-item.is-active,.docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,.hero.is-primary .navbar-link:hover,.docstring>section>a.hero.docs-sourcelink .navbar-link:hover,.hero.is-primary .navbar-link.is-active,.docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#39acda;color:#fff}.hero.is-primary .tabs a,.docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}.hero.is-primary .tabs a:hover,.docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}.hero.is-primary .tabs li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#4eb5de !important;opacity:1}.hero.is-primary .tabs.is-boxed a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,.hero.is-primary .tabs.is-toggle a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}.hero.is-primary .tabs.is-boxed a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,.hero.is-primary .tabs.is-toggle a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-primary .tabs.is-boxed li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,.hero.is-primary .tabs.is-boxed li.is-active a:hover,.hero.is-primary .tabs.is-toggle li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,.hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#4eb5de}.hero.is-primary.is-bold,.docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}@media screen and (max-width: 768px){.hero.is-primary.is-bold .navbar-menu,.docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}}.hero.is-link{background-color:#2e63b8;color:#fff}.hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-link strong{color:inherit}.hero.is-link .title{color:#fff}.hero.is-link .subtitle{color:rgba(255,255,255,0.9)}.hero.is-link .subtitle a:not(.button),.hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-link .navbar-menu{background-color:#2e63b8}}.hero.is-link .navbar-item,.hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-link a.navbar-item:hover,.hero.is-link a.navbar-item.is-active,.hero.is-link .navbar-link:hover,.hero.is-link .navbar-link.is-active{background-color:#2958a4;color:#fff}.hero.is-link .tabs a{color:#fff;opacity:0.9}.hero.is-link .tabs a:hover{opacity:1}.hero.is-link .tabs li.is-active a{color:#2e63b8 !important;opacity:1}.hero.is-link .tabs.is-boxed a,.hero.is-link .tabs.is-toggle a{color:#fff}.hero.is-link .tabs.is-boxed a:hover,.hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-link .tabs.is-boxed li.is-active a,.hero.is-link .tabs.is-boxed li.is-active a:hover,.hero.is-link .tabs.is-toggle li.is-active a,.hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#2e63b8}.hero.is-link.is-bold{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}@media screen and (max-width: 768px){.hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}}.hero.is-info{background-color:#209cee;color:#fff}.hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-info strong{color:inherit}.hero.is-info .title{color:#fff}.hero.is-info .subtitle{color:rgba(255,255,255,0.9)}.hero.is-info .subtitle a:not(.button),.hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-info .navbar-menu{background-color:#209cee}}.hero.is-info .navbar-item,.hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-info a.navbar-item:hover,.hero.is-info a.navbar-item.is-active,.hero.is-info .navbar-link:hover,.hero.is-info .navbar-link.is-active{background-color:#1190e3;color:#fff}.hero.is-info .tabs a{color:#fff;opacity:0.9}.hero.is-info .tabs a:hover{opacity:1}.hero.is-info .tabs li.is-active a{color:#209cee !important;opacity:1}.hero.is-info .tabs.is-boxed a,.hero.is-info .tabs.is-toggle a{color:#fff}.hero.is-info .tabs.is-boxed a:hover,.hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-info .tabs.is-boxed li.is-active a,.hero.is-info .tabs.is-boxed li.is-active a:hover,.hero.is-info .tabs.is-toggle li.is-active a,.hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#209cee}.hero.is-info.is-bold{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}@media screen and (max-width: 768px){.hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}}.hero.is-success{background-color:#22c35b;color:#fff}.hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-success strong{color:inherit}.hero.is-success .title{color:#fff}.hero.is-success .subtitle{color:rgba(255,255,255,0.9)}.hero.is-success .subtitle a:not(.button),.hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-success .navbar-menu{background-color:#22c35b}}.hero.is-success .navbar-item,.hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-success a.navbar-item:hover,.hero.is-success a.navbar-item.is-active,.hero.is-success .navbar-link:hover,.hero.is-success .navbar-link.is-active{background-color:#1ead51;color:#fff}.hero.is-success .tabs a{color:#fff;opacity:0.9}.hero.is-success .tabs a:hover{opacity:1}.hero.is-success .tabs li.is-active a{color:#22c35b !important;opacity:1}.hero.is-success .tabs.is-boxed a,.hero.is-success .tabs.is-toggle a{color:#fff}.hero.is-success .tabs.is-boxed a:hover,.hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-success .tabs.is-boxed li.is-active a,.hero.is-success .tabs.is-boxed li.is-active a:hover,.hero.is-success .tabs.is-toggle li.is-active a,.hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#22c35b}.hero.is-success.is-bold{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}@media screen and (max-width: 768px){.hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}}.hero.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-warning strong{color:inherit}.hero.is-warning .title{color:rgba(0,0,0,0.7)}.hero.is-warning .subtitle{color:rgba(0,0,0,0.9)}.hero.is-warning .subtitle a:not(.button),.hero.is-warning .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-warning .navbar-menu{background-color:#ffdd57}}.hero.is-warning .navbar-item,.hero.is-warning .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-warning a.navbar-item:hover,.hero.is-warning a.navbar-item.is-active,.hero.is-warning .navbar-link:hover,.hero.is-warning .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.hero.is-warning .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-warning .tabs a:hover{opacity:1}.hero.is-warning .tabs li.is-active a{color:#ffdd57 !important;opacity:1}.hero.is-warning .tabs.is-boxed a,.hero.is-warning .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-warning .tabs.is-boxed a:hover,.hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-warning .tabs.is-boxed li.is-active a,.hero.is-warning .tabs.is-boxed li.is-active a:hover,.hero.is-warning .tabs.is-toggle li.is-active a,.hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ffdd57}.hero.is-warning.is-bold{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}@media screen and (max-width: 768px){.hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}}.hero.is-danger{background-color:#da0b00;color:#fff}.hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-danger strong{color:inherit}.hero.is-danger .title{color:#fff}.hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}.hero.is-danger .subtitle a:not(.button),.hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-danger .navbar-menu{background-color:#da0b00}}.hero.is-danger .navbar-item,.hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-danger a.navbar-item:hover,.hero.is-danger a.navbar-item.is-active,.hero.is-danger .navbar-link:hover,.hero.is-danger .navbar-link.is-active{background-color:#c10a00;color:#fff}.hero.is-danger .tabs a{color:#fff;opacity:0.9}.hero.is-danger .tabs a:hover{opacity:1}.hero.is-danger .tabs li.is-active a{color:#da0b00 !important;opacity:1}.hero.is-danger .tabs.is-boxed a,.hero.is-danger .tabs.is-toggle a{color:#fff}.hero.is-danger .tabs.is-boxed a:hover,.hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-danger .tabs.is-boxed li.is-active a,.hero.is-danger .tabs.is-boxed li.is-active a:hover,.hero.is-danger .tabs.is-toggle li.is-active a,.hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#da0b00}.hero.is-danger.is-bold{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}@media screen and (max-width: 768px){.hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}}.hero.is-small .hero-body,#documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{.hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{.hero.is-large .hero-body{padding:18rem 6rem}}.hero.is-halfheight .hero-body,.hero.is-fullheight .hero-body,.hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}.hero.is-halfheight .hero-body>.container,.hero.is-fullheight .hero-body>.container,.hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}.hero.is-halfheight{min-height:50vh}.hero.is-fullheight{min-height:100vh}.hero-video{overflow:hidden}.hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}.hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){.hero-video{display:none}}.hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){.hero-buttons .button{display:flex}.hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{.hero-buttons{display:flex;justify-content:center}.hero-buttons .button:not(:last-child){margin-right:1.5rem}}.hero-head,.hero-foot{flex-grow:0;flex-shrink:0}.hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{.hero-body{padding:3rem 3rem}}.section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){.section{padding:3rem 3rem}.section.is-medium{padding:9rem 4.5rem}.section.is-large{padding:18rem 6rem}}.footer{background-color:#fafafa;padding:3rem 1.5rem 6rem}h1 .docs-heading-anchor,h1 .docs-heading-anchor:hover,h1 .docs-heading-anchor:visited,h2 .docs-heading-anchor,h2 .docs-heading-anchor:hover,h2 .docs-heading-anchor:visited,h3 .docs-heading-anchor,h3 .docs-heading-anchor:hover,h3 .docs-heading-anchor:visited,h4 .docs-heading-anchor,h4 .docs-heading-anchor:hover,h4 .docs-heading-anchor:visited,h5 .docs-heading-anchor,h5 .docs-heading-anchor:hover,h5 .docs-heading-anchor:visited,h6 .docs-heading-anchor,h6 .docs-heading-anchor:hover,h6 .docs-heading-anchor:visited{color:#222}h1 .docs-heading-anchor-permalink,h2 .docs-heading-anchor-permalink,h3 .docs-heading-anchor-permalink,h4 .docs-heading-anchor-permalink,h5 .docs-heading-anchor-permalink,h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}h1 .docs-heading-anchor-permalink::before,h2 .docs-heading-anchor-permalink::before,h3 .docs-heading-anchor-permalink::before,h4 .docs-heading-anchor-permalink::before,h5 .docs-heading-anchor-permalink::before,h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}h1:hover .docs-heading-anchor-permalink,h2:hover .docs-heading-anchor-permalink,h3:hover .docs-heading-anchor-permalink,h4:hover .docs-heading-anchor-permalink,h5:hover .docs-heading-anchor-permalink,h6:hover .docs-heading-anchor-permalink{visibility:visible}.docs-dark-only{display:none !important}pre{position:relative;overflow:hidden}pre code,pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}pre code:first-of-type,pre code.hljs:first-of-type{padding-top:0.5rem !important}pre code:last-of-type,pre code.hljs:last-of-type{padding-bottom:0.5rem !important}pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#222;cursor:pointer;text-align:center}pre .copy-button:focus,pre .copy-button:hover{opacity:1;background:rgba(34,34,34,0.1);color:#2e63b8}pre .copy-button.success{color:#259a12;opacity:1}pre .copy-button.error{color:#cb3c33;opacity:1}pre:hover .copy-button{opacity:1}.admonition{background-color:#b5b5b5;border-style:solid;border-width:1px;border-color:#363636;border-radius:4px;font-size:1rem}.admonition strong{color:currentColor}.admonition.is-small,#documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}.admonition.is-medium{font-size:1.25rem}.admonition.is-large{font-size:1.5rem}.admonition.is-default{background-color:#b5b5b5;border-color:#363636}.admonition.is-default>.admonition-header{background-color:#363636;color:#fff}.admonition.is-default>.admonition-body{color:#fff}.admonition.is-info{background-color:#def0fc;border-color:#209cee}.admonition.is-info>.admonition-header{background-color:#209cee;color:#fff}.admonition.is-info>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-success{background-color:#bdf4d1;border-color:#22c35b}.admonition.is-success>.admonition-header{background-color:#22c35b;color:#fff}.admonition.is-success>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-warning{background-color:#fff3c5;border-color:#ffdd57}.admonition.is-warning>.admonition-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.admonition.is-warning>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-danger{background-color:#ffaba7;border-color:#da0b00}.admonition.is-danger>.admonition-header{background-color:#da0b00;color:#fff}.admonition.is-danger>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-compat{background-color:#bdeff5;border-color:#1db5c9}.admonition.is-compat>.admonition-header{background-color:#1db5c9;color:#fff}.admonition.is-compat>.admonition-body{color:rgba(0,0,0,0.7)}.admonition-header{color:#fff;background-color:#363636;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}details.admonition.is-details>.admonition-header{list-style:none}details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}.admonition-body{color:#222;padding:0.5rem .75rem}.admonition-body pre{background-color:#f5f5f5}.admonition-body code{background-color:rgba(0,0,0,0.05)}.docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #dbdbdb;box-shadow:2px 2px 3px rgba(10,10,10,0.1);max-width:100%}.docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#f5f5f5;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #dbdbdb;overflow:auto}.docstring>header code{background-color:transparent}.docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}.docstring>header .docstring-binding{margin-right:0.3em}.docstring>header .docstring-category{margin-left:0.3em}.docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #dbdbdb}.docstring>section:last-child{border-bottom:none}.docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}.docstring>section>a.docs-sourcelink:focus{opacity:1 !important}.docstring:hover>section>a.docs-sourcelink{opacity:0.2}.docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}.docstring>section:hover a.docs-sourcelink{opacity:1}.documenter-example-output{background-color:#fff}.outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#ffaba7;color:rgba(0,0,0,0.7);border-bottom:3px solid #da0b00;padding:10px 35px;text-align:center;font-size:15px}.outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}.outdated-warning-overlay a{color:#2e63b8}.outdated-warning-overlay a:hover{color:#363636}.content pre{border:1px solid #dbdbdb}.content code{font-weight:inherit}.content a code{color:#2e63b8}.content h1 code,.content h2 code,.content h3 code,.content h4 code,.content h5 code,.content h6 code{color:#222}.content table{display:block;width:initial;max-width:100%;overflow-x:auto}.content blockquote>ul:first-child,.content blockquote>ol:first-child,.content .admonition-body>ul:first-child,.content .admonition-body>ol:first-child{margin-top:0}pre,code{font-variant-ligatures:no-contextual}.breadcrumb a.is-disabled{cursor:default;pointer-events:none}.breadcrumb a.is-disabled,.breadcrumb a.is-disabled:hover{color:#222}.hljs{background:initial !important}.katex .katex-mathml{top:0;right:0}.katex-display,mjx-container,.MathJax_Display{margin:0.5em 0 !important}html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}li.no-marker{list-style:none}#documenter .docs-main>article{overflow-wrap:break-word}#documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){#documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){#documenter .docs-main{width:100%}#documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}#documenter .docs-main>header,#documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}#documenter .docs-main header.docs-navbar{background-color:#fff;border-bottom:1px solid #dbdbdb;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}#documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}#documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}#documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}#documenter .docs-main header.docs-navbar .docs-right .docs-icon,#documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}#documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}#documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}#documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #bbb;transition-duration:0.7s;-webkit-transition-duration:0.7s}#documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}#documenter .docs-main section.footnotes{border-top:1px solid #dbdbdb}#documenter .docs-main section.footnotes li .tag:first-child,#documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,#documenter .docs-main section.footnotes li .content kbd:first-child,.content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}#documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #dbdbdb;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){#documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}#documenter .docs-main .docs-footer .docs-footer-nextpage,#documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}#documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}#documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}#documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}#documenter .docs-sidebar{display:flex;flex-direction:column;color:#0a0a0a;background-color:#f5f5f5;border-right:1px solid #dbdbdb;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}#documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #bbb}@media screen and (min-width: 1056px){#documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){#documenter .docs-sidebar{left:0;top:0}}#documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}#documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}#documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}#documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}#documenter .docs-sidebar .docs-package-name a,#documenter .docs-sidebar .docs-package-name a:hover{color:#0a0a0a}#documenter .docs-sidebar .docs-version-selector{border-top:1px solid #dbdbdb;display:none;padding:0.5rem}#documenter .docs-sidebar .docs-version-selector.visible{display:flex}#documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #dbdbdb;padding-bottom:1.5rem}#documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}#documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}#documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}#documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}#documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}#documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}#documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}#documenter .docs-sidebar ul.docs-menu .tocitem,#documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#0a0a0a;background:#f5f5f5}#documenter .docs-sidebar ul.docs-menu a.tocitem:hover,#documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#0a0a0a;background-color:#ebebeb}#documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #dbdbdb;border-bottom:1px solid #dbdbdb;background-color:#fff}#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#fff;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#ebebeb;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}#documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}#documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}#documenter .docs-sidebar form.docs-search>input{width:14.4rem}#documenter .docs-sidebar #documenter-search-query{color:#707070;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){#documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#ccc}}@media screen and (max-width: 1055px){#documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#ccc}}kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(0,0,0,0.6);box-shadow:0 2px 0 1px rgba(0,0,0,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}.search-min-width-50{min-width:50%}.search-min-height-100{min-height:100%}.search-modal-card-body{max-height:calc(100vh - 15rem)}.search-result-link{border-radius:0.7em;transition:all 300ms}.search-result-link:hover,.search-result-link:focus{background-color:rgba(0,128,128,0.1)}.search-result-link .property-search-result-badge,.search-result-link .search-filter{transition:all 300ms}.property-search-result-badge,.search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}.search-result-link:hover .property-search-result-badge,.search-result-link:hover .search-filter,.search-result-link:focus .property-search-result-badge,.search-result-link:focus .search-filter{color:#f1f5f9;background-color:#333}.search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}.search-filter:hover,.search-filter:focus{color:#333}.search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}.search-filter-selected:hover,.search-filter-selected:focus{color:#f5f5f5}.search-result-highlight{background-color:#ffdd57;color:black}.search-divider{border-bottom:1px solid #dbdbdb}.search-result-title{width:85%;color:#333}.search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}#search-modal .modal-card-body::-webkit-scrollbar,#search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}#search-modal .modal-card-body::-webkit-scrollbar-thumb,#search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}#search-modal .modal-card-body::-webkit-scrollbar-track,#search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}.w-100{width:100%}.gap-2{gap:0.5rem}.gap-4{gap:1rem}.gap-8{gap:2rem}.ansi span.sgr1{font-weight:bolder}.ansi span.sgr2{font-weight:lighter}.ansi span.sgr3{font-style:italic}.ansi span.sgr4{text-decoration:underline}.ansi span.sgr7{color:#fff;background-color:#222}.ansi span.sgr8{color:transparent}.ansi span.sgr8 span{color:transparent}.ansi span.sgr9{text-decoration:line-through}.ansi span.sgr30{color:#242424}.ansi span.sgr31{color:#a7201f}.ansi span.sgr32{color:#066f00}.ansi span.sgr33{color:#856b00}.ansi span.sgr34{color:#2149b0}.ansi span.sgr35{color:#7d4498}.ansi span.sgr36{color:#007989}.ansi span.sgr37{color:gray}.ansi span.sgr40{background-color:#242424}.ansi span.sgr41{background-color:#a7201f}.ansi span.sgr42{background-color:#066f00}.ansi span.sgr43{background-color:#856b00}.ansi span.sgr44{background-color:#2149b0}.ansi span.sgr45{background-color:#7d4498}.ansi span.sgr46{background-color:#007989}.ansi span.sgr47{background-color:gray}.ansi span.sgr90{color:#616161}.ansi span.sgr91{color:#cb3c33}.ansi span.sgr92{color:#0e8300}.ansi span.sgr93{color:#a98800}.ansi span.sgr94{color:#3c5dcd}.ansi span.sgr95{color:#9256af}.ansi span.sgr96{color:#008fa3}.ansi span.sgr97{color:#f5f5f5}.ansi span.sgr100{background-color:#616161}.ansi span.sgr101{background-color:#cb3c33}.ansi span.sgr102{background-color:#0e8300}.ansi span.sgr103{background-color:#a98800}.ansi span.sgr104{background-color:#3c5dcd}.ansi span.sgr105{background-color:#9256af}.ansi span.sgr106{background-color:#008fa3}.ansi span.sgr107{background-color:#f5f5f5}code.language-julia-repl>span.hljs-meta{color:#066f00;font-weight:bolder}/*! + Theme: Default + Description: Original highlight.js style + Author: (c) Ivan Sagalaev + Maintainer: @highlightjs/core-team + Website: https://highlightjs.org/ + License: see project LICENSE + Touched: 2021 +*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{background:#F3F3F3;color:#444}.hljs-comment{color:#697070}.hljs-tag,.hljs-punctuation{color:#444a}.hljs-tag .hljs-name,.hljs-tag .hljs-attr{color:#444}.hljs-keyword,.hljs-attribute,.hljs-selector-tag,.hljs-meta .hljs-keyword,.hljs-doctag,.hljs-name{font-weight:bold}.hljs-type,.hljs-string,.hljs-number,.hljs-selector-id,.hljs-selector-class,.hljs-quote,.hljs-template-tag,.hljs-deletion{color:#880000}.hljs-title,.hljs-section{color:#880000;font-weight:bold}.hljs-regexp,.hljs-symbol,.hljs-variable,.hljs-template-variable,.hljs-link,.hljs-selector-attr,.hljs-operator,.hljs-selector-pseudo{color:#ab5656}.hljs-literal{color:#695}.hljs-built_in,.hljs-bullet,.hljs-code,.hljs-addition{color:#397300}.hljs-meta{color:#1f7199}.hljs-meta .hljs-string{color:#38a}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold}.gap-4{gap:1rem} diff --git a/v2.16.0/assets/themeswap.js b/v2.16.0/assets/themeswap.js new file mode 100644 index 000000000..9f5eebe6a --- /dev/null +++ b/v2.16.0/assets/themeswap.js @@ -0,0 +1,84 @@ +// Small function to quickly swap out themes. Gets put into the tag.. +function set_theme_from_local_storage() { + // Initialize the theme to null, which means default + var theme = null; + // If the browser supports the localstorage and is not disabled then try to get the + // documenter theme + if (window.localStorage != null) { + // Get the user-picked theme from localStorage. May be `null`, which means the default + // theme. + theme = window.localStorage.getItem("documenter-theme"); + } + // Check if the users preference is for dark color scheme + var darkPreference = + window.matchMedia("(prefers-color-scheme: dark)").matches === true; + // Initialize a few variables for the loop: + // + // - active: will contain the index of the theme that should be active. Note that there + // is no guarantee that localStorage contains sane values. If `active` stays `null` + // we either could not find the theme or it is the default (primary) theme anyway. + // Either way, we then need to stick to the primary theme. + // + // - disabled: style sheets that should be disabled (i.e. all the theme style sheets + // that are not the currently active theme) + var active = null; + var disabled = []; + var primaryLightTheme = null; + var primaryDarkTheme = null; + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // To distinguish the default (primary) theme, it needs to have the data-theme-primary + // attribute set. + if (ss.ownerNode.getAttribute("data-theme-primary") !== null) { + primaryLightTheme = themename; + } + // Check if the theme is primary dark theme so that we could store its name in darkTheme + if (ss.ownerNode.getAttribute("data-theme-primary-dark") !== null) { + primaryDarkTheme = themename; + } + // If we find a matching theme (and it's not the default), we'll set active to non-null + if (themename === theme) active = i; + // Store the style sheets of inactive themes so that we could disable them + if (themename !== theme) disabled.push(ss); + } + var activeTheme = null; + if (active !== null) { + // If we did find an active theme, we'll (1) add the theme--$(theme) class to + document.getElementsByTagName("html")[0].className = "theme--" + theme; + activeTheme = theme; + } else { + // If we did _not_ find an active theme, then we need to fall back to the primary theme + // which can either be dark or light, depending on the user's OS preference. + var activeTheme = darkPreference ? primaryDarkTheme : primaryLightTheme; + // In case it somehow happens that the relevant primary theme was not found in the + // preceding loop, we abort without doing anything. + if (activeTheme === null) { + console.error("Unable to determine primary theme."); + return; + } + // When switching to the primary light theme, then we must not have a class name + // for the tag. That's only for non-primary or the primary dark theme. + if (darkPreference) { + document.getElementsByTagName("html")[0].className = + "theme--" + activeTheme; + } else { + document.getElementsByTagName("html")[0].className = ""; + } + } + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // we'll disable all the stylesheets, except for the active one + ss.disabled = !(themename == activeTheme); + } +} +set_theme_from_local_storage(); diff --git a/v2.16.0/assets/warner.js b/v2.16.0/assets/warner.js new file mode 100644 index 000000000..3f6f5d008 --- /dev/null +++ b/v2.16.0/assets/warner.js @@ -0,0 +1,52 @@ +function maybeAddWarning() { + // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE + // in siteinfo.js. + // If either of these are undefined something went horribly wrong, so we abort. + if ( + window.DOCUMENTER_NEWEST === undefined || + window.DOCUMENTER_CURRENT_VERSION === undefined || + window.DOCUMENTER_STABLE === undefined + ) { + return; + } + + // Current version is not a version number, so we can't tell if it's the newest version. Abort. + if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) { + return; + } + + // Current version is newest version, so no need to add a warning. + if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) { + return; + } + + // Add a noindex meta tag (unless one exists) so that search engines don't index this version of the docs. + if (document.body.querySelector('meta[name="robots"]') === null) { + const meta = document.createElement("meta"); + meta.name = "robots"; + meta.content = "noindex"; + + document.getElementsByTagName("head")[0].appendChild(meta); + } + + const div = document.createElement("div"); + div.classList.add("outdated-warning-overlay"); + const closer = document.createElement("button"); + closer.classList.add("outdated-warning-closer", "delete"); + closer.addEventListener("click", function () { + document.body.removeChild(div); + }); + const href = window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE; + div.innerHTML = + 'This documentation is not for the latest stable release, but for either the development version or an older release.
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/v2.16.0/contributing/new-documentation/index.html b/v2.16.0/contributing/new-documentation/index.html new file mode 100644 index 000000000..fa6812c0e --- /dev/null +++ b/v2.16.0/contributing/new-documentation/index.html @@ -0,0 +1,2 @@ + +Contributing to the documentation · RxInfer.jl
GitHub

Contributing to the documentation

Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:

  1. Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.

  2. Identify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.

  3. Fork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.

  4. Make Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.

  5. Submit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.

  6. Review and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.

  7. Merging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!

By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.

Use LiveServer.jl

LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.

To use LiveServer.jl, simply follow these steps[1]

  • Make sure to import the required packages 
julia> using LiveServer, Documenter
  • After importing the required packages, you can start the live server with the following command:
julia> servedocs()
  • 1Make sure to install the LiveServer and Documenter in your current working environment.
diff --git a/v2.16.0/contributing/new-example/index.html b/v2.16.0/contributing/new-example/index.html new file mode 100644 index 000000000..1d8afbce2 --- /dev/null +++ b/v2.16.0/contributing/new-example/index.html @@ -0,0 +1,7 @@ + +Contributing to the examples · RxInfer.jl
GitHub

Contributing to the examples

We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.

In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/"subcategory" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.

After preparing the new example it is necessary to modify the examples/.meta.jl file.

  1. Make sure that the very first cell of the notebook contains ONLY # <title> in it and has the markdown cell type. This is important for generating links in our documentation.
  2. The path option must be set to a local path in a category sub-folder.
  3. The text in the description option will be used on the Examples page in the documentation.
  4. Set category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).
  5. Please do no use Overview as a name for the new example, the title Overview is reserved.
  6. Use the following template for equations, note that $$ and both \begin and \end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.
$$\begin{aligned}
+      <latex equations here>
+\end{aligned}$$
  1. When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.
  2. Notebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.
variable = 0
+for i in 1:10
+    global variable = variable + i
+end
  1. All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.
  2. All plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.
Note

Please avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.

Note

Use make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.

diff --git a/v2.16.0/contributing/new-package/index.html b/v2.16.0/contributing/new-package/index.html new file mode 100644 index 000000000..628166dfd --- /dev/null +++ b/v2.16.0/contributing/new-package/index.html @@ -0,0 +1,28 @@ + +Contributing to the dependencies · RxInfer.jl
GitHub

Contributing to the dependencies

Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.

The benefits of small packages for the ecosystem

In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:

  1. Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.

  2. Collaboration: Teams can work on different packages concurrently, speeding up development.

  3. Version Control: Precise versioning and fewer dependencies lead to leaner projects.

  4. Performance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.

  5. Flexibility: Developers can select and customize packages for their needs.

  6. Community: Smaller packages attract contributors, fostering collaboration and faster feedback.

In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.

Use PkgTemplates

PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:

julia> using PkgTemplates
+
+julia> USER = "your github user name" # Use `reactivebayes` if developing within the ReactiveBayes organisation
+
+julia> template = Template(
+    user = USER, 
+    plugins = [
+        CompatHelper(), 
+        ProjectFile(), 
+        SrcDir(), 
+        Git(), 
+        License(), 
+        Readme(), 
+        Tests(), 
+        GitHubActions(), 
+        Codecov(), 
+        Documenter{GitHubActions}(), 
+        Formatter(style="blue"), 
+        BlueStyleBadge(), 
+        PkgEvalBadge()
+])
+
+julia> template("MyNewCoolPackage")

This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.

  • Adjust the minimum supported version of Julia

After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:

[compat]
+julia = "1.9.2"

Try to be conservative and set as low version of Julia as possible.

  • Adjust the authors of the package

The authors field is present in the Project.toml, e.g 

authors = ["John Wick <john.wick@continental.com>", ...]

  • Add requires dependencies and their [compat] bounds

To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:

julia --project=.

or 

julia
julia> ] activate .

Then, add dependencies like this:

julia> ] add SomeCoolDependency, SomeOtherCoolDependency

For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:

[compat]
+julia = "1.9"
+SomeCoolDependency = "0.19.2"
+SomeOtherCoolDependency = "1.3.12"

For more details on compat bounds, check the official Julia documentation.

Adjust README.md

The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.

Note

Some badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.

Write code and tests

The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.

Simplify Testing with ReTestItems

You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.

Write code and the documentation

Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):

julia --project=docs docs/make.jl

For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.

Hosting Documentation with GitHub Actions

The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.

Enable GitHub Pages in Repository Settings

The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:

  1. Navigate to the GitHub Pages settings of your repository.
  2. Choose the Deploy from a branch option.
  3. Select the gh-pages branch.
diff --git a/v2.16.0/contributing/new-release/index.html b/v2.16.0/contributing/new-release/index.html new file mode 100644 index 000000000..dfc9bc819 --- /dev/null +++ b/v2.16.0/contributing/new-release/index.html @@ -0,0 +1,2 @@ + +Publishing a new release · RxInfer.jl
GitHub

Publishing a new release

Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.

Start the release process

In order to start the release process a person with the associated permissions should:

  • Open a commit page on GitHub
  • Write the @JuliaRegistrator register comment for the commit:

Release comment

The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.

diff --git a/v2.16.0/contributing/overview/index.html b/v2.16.0/contributing/overview/index.html new file mode 100644 index 000000000..2b8f931f6 --- /dev/null +++ b/v2.16.0/contributing/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Contributing

We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.

Reporting bugs

We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.

Nightly Julia status

The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.

PkgEval

Suggesting features

We welcome new feature proposals. However, before submitting a feature request, consider a few things:

  • Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.
  • If you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.

Contributing code

Installing RxInfer

We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:

] dev git@github.com:your_username/RxInfer.jl.git

The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.

Note

It is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.

Core dependencies

RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.

Committing code

We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.

Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well.

Note

Use make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.

Style conventions

We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:

  • Use 4 spaces for indentation
  • Type names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..
  • Function names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..
  • Variable names and function arguments use snake_case
  • The name of a method that modifies its argument(s) must end in !
Note

RxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.

Unit tests

We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.

All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.

The tests can be evaluated by running following command in the Julia REPL:

] test RxInfer

In addition tests can be evaluated by running following command in the RxInfer root directory:

make test
Note

Use make devtest to use local dev-ed versions of the core packages.

Makefile

RxInfer.jl uses Makefile for most common operations:

  • make help: Shows help snippet
  • make test: Run tests, supports extra arguments
    • make test test_args="distributions:normal_mean_variance" would run tests only from distributions/test_normal_mean_variance.jl
    • make test test_args="distributions:normal_mean_variance models:lgssm" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl
    • make test dev=true would run tests while using dev-ed versions of core packages
  • make devtest: Alias for the make test dev=true ...
  • make docs: Compile documentation
  • make devdocs: Same as make docs, but uses dev-ed versions of core packages
  • make examples: Run all examples and put them in the docs/ folder if successfull
  • make devexamples: Same as make examples, but uses dev-ed versions of core packages
  • make lint: Check codestyle
  • make format: Check and fix codestyle
Note

Core packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.

diff --git a/v2.16.0/examples/advanced_examples/Active Inference Mountain car/index.html b/v2.16.0/examples/advanced_examples/Active Inference Mountain car/index.html new file mode 100644 index 000000000..bba4b1eb3 --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Active Inference Mountain car/index.html @@ -0,0 +1,286 @@ + +Active Inference Mountain car · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Active Inference Mountain car

import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.

The environmental process of the mountain

Firstly, we specify the environmental process according to Ueltzhoeffer (2017) "Deep active inference". This process shows how the environment evolves after interacting with the agent.

Particularly, let's denote $z_t = (\phi_t, \,\,\dot{\phi_t})$ as the environmental state depending on the position $\phi_t$ and velocity $\dot{\phi_t}$ of the car; $a_t$ as the action of the environment on the car. Then the evolution of the state is described as follows

\[\begin{aligned} +\dot{\phi_t} &= \dot{\phi}_{t-1} + F_g(\phi_{t-1}) + F_f(\dot{\phi}_{t-1}) + F_a(a_t)\\ +\phi_t &= \phi_{t-1} + \dot{\phi_t} +\end{aligned}\]

where $F_g(\phi_{t-1})$ is the gravitational force of the hill landscape that depends on the car's position

\[F_g(\phi) = \begin{cases} + -0.05(2\phi + 1) , \, & \mathrm{if} \, \phi < 0 \\ + -0.05 \left[(1 + 5\phi^2)^{-\frac{1}{2}} + \phi^2 (1 + 5\phi^2)^{-\frac{3}{2}} + \frac{1}{16}\phi^4 \right], \, & \mathrm{otherwise} +\end{cases}\]

\[F_f(\dot{\phi})\]

is the friction on the car defined through the car's velocity $F_f(\dot{\phi}) = -0.1 \, \dot{\phi}\,$ and $F_a(a)$ is the engine force $F_a(a) = 0.04 \,\tanh(a).$ Since the car is on low battery, we use the $\tanh(\cdot)$ function to limit the engine force to the interval [-0.04, 0.04].

In the cell below, the create_physics function defines forces $F_g,\, F_f,\, F_a\,$; and the create_world function defines the environmental process of the mountain.

import HypergeometricFunctions: _₂F₁
+
+function create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)
+    # Engine force as function of action
+    Fa = (a::Real) -> engine_force_limit * tanh(a) 
+
+    # Friction force as function of velocity
+    Ff = (y_dot::Real) -> -friction_coefficient * y_dot 
+    
+    # Gravitational force (horizontal component) as function of position
+    Fg = (y::Real) -> begin
+        if y < 0
+            0.05*(-2*y - 1)
+        else
+            0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)
+        end
+    end
+    
+    # The height of the landscape as a function of the horizontal coordinate
+    height = (x::Float64) -> begin
+        if x < 0
+            h = x^2 + x
+        else
+            h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80
+        end
+        return 0.05*h
+    end
+
+    return (Fa, Ff, Fg,height)
+end;
+
+function create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)
+
+    y_t_min = initial_position
+    y_dot_t_min = initial_velocity
+    
+    y_t = y_t_min
+    y_dot_t = y_dot_t_min
+    
+    execute = (a_t::Float64) -> begin
+        # Compute next state
+        y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)
+        y_t = y_t_min + y_dot_t
+    
+        # Reset state for next step
+        y_t_min = y_t
+        y_dot_t_min = y_dot_t
+    end
+    
+    observe = () -> begin 
+        return [y_t, y_dot_t]
+    end
+        
+    return (execute, observe)
+end
create_world (generic function with 1 method)

Let's visualize the mountain landscape and the situation of the car. 

engine_force_limit   = 0.04
+friction_coefficient = 0.1
+
+Fa, Ff, Fg, height = create_physics(
+    engine_force_limit = engine_force_limit,
+    friction_coefficient = friction_coefficient
+);
+initial_position = -0.5
+initial_velocity = 0.0
+
+x_target = [0.5, 0.0] 
+
+valley_x = range(-2, 2, length=400)
+valley_y = [ height(xs) for xs in valley_x ]
+plot(valley_x, valley_y, title = "Mountain valley", label = "Landscape", color = "black")
+scatter!([ initial_position ], [ height(initial_position) ], label="initial car position")   
+scatter!([x_target[1]], [height(x_target[1])], label="camping site")

Naive approach

Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.

N_naive  = 100 # Total simulation time
+pi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only
+
+# Let there be a world
+(execute_naive, observe_naive) = create_world(; 
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+);
+
+y_naive = Vector{Vector{Float64}}(undef, N_naive)
+for t = 1:N_naive
+    execute_naive(pi_naive[t]) # Execute environmental process
+    y_naive[t] = observe_naive() # Observe external states
+end
+
+animation_naive = @animate for i in 1:N_naive
+    plot(valley_x, valley_y, title = "Naive policy", label = "Landscape", color = "black", size = (800, 400))
+    scatter!([y_naive[i][1]], [height(y_naive[i][1])], label="car")
+    scatter!([x_target[1]], [height(x_target[1])], label="goal")   
+end
+
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_naive, "../pics/ai-mountain-car-naive.gif", fps = 24, show_msg = false);

They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.

Active inference approach

Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.

We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows

\[\begin{aligned} +p_t(x,s,u) \propto p(s_{t-1}) \prod_{k=t}^{t+T} p(x_k \mid s_k) \, p(s_k \mid s_{k-1},u_k) \, p(u_k) \, p'(x_k) \nonumber +\end{aligned}\]

where the factors are defined as

\[p'(x_k) = \mathcal{N}(x_k \mid x_{goal},\,V_{goal}) , \quad (\mathrm{target})\]

\[p(s_k \mid s_{k-1},u_k) = \mathcal{N}(s_k \mid \tilde{g}(s_{k-1})+h(u_k),\,\gamma^{-1}) , \quad (\mathrm{state \,\, transition})\]

\[p(x_k \mid s_k) = \mathcal{N}(x_k \mid s_k,\,\theta), \quad (\mathrm{observation})\]

\[p(u_k) = \mathcal{N}(u_k \mid m_u,\,V_u), \quad (\mathrm{control})\]

\[p(s_{t-1}) = \mathcal{N}(s_{t-1} \mid m_{t-1},\,V_{t-1}), \quad (\mathrm{previous \,\, state})\]

where

  • \[x\]

    denotes observations of the agent after interacting with the environment;

  • \[s_t = (s_t,\dot{s_t})\]

    is the state of the car embodying its position and velocity;

  • \[u_t\]

    denotes the control state of the agent;

  • \[h(\cdot)\]

    is the $\tanh(\cdot)$ function modeling engine control;

  • \[\tilde{g}(\cdot)\]

    executes a linear approximation of equations (1) and (2):

\[\begin{aligned} +\dot{s_t} &= \dot{s}_{t-1} + F_g(s_{t-1}) + F_f(\dot{s}_{t-1})\\ +s_t &= s_{t-1} + \dot{s_t} +\end{aligned}\]

In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.

@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)
+    
+    # Transition function modeling transition due to gravity and friction
+    g = (s_t_min::AbstractVector) -> begin 
+        s_t = similar(s_t_min) # Next state
+        s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity
+        s_t[1] = s_t_min[1] + s_t[2] # Update position
+        return s_t
+    end
+    
+    # Function for modeling engine control
+    h = (u::AbstractVector) -> [0.0, Fa(u[1])] 
+    
+    # Inverse engine force, from change in state to corresponding engine force
+    h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] 
+    
+    # Internal model perameters
+    Gamma = 1e4*diageye(2) # Transition precision
+    Theta = 1e-4*diageye(2) # Observation variance
+    
+    m_s_t_min = datavar(Vector{Float64})
+    V_s_t_min = datavar(Matrix{Float64})
+
+    s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)
+    s_k_min = s_t_min
+    
+    m_u = datavar(Vector{Float64}, T)
+    V_u = datavar(Matrix{Float64}, T)
+    
+    m_x = datavar(Vector{Float64}, T)
+    V_x = datavar(Matrix{Float64}, T)
+    
+    u = randomvar(T)
+    s = randomvar(T)
+    x = randomvar(T)
+    
+    u_h_k = randomvar(T)
+    s_g_k = randomvar(T)
+    u_s_sum = randomvar(T)
+    
+    for k in 1:T
+        u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])
+        u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }
+        s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }
+        u_s_sum[k] ~ s_g_k[k] + u_h_k[k]
+        s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)
+        x[k] ~ MvNormal(mean = s[k], cov = Theta)
+        x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal
+        s_k_min = s[k]
+    end
+    
+    return (s, )
+end

After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.

  1. Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time $t$ and gets $T$ observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next $T$ time step.
  2. Infer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state $s_t$ and control $u_t$, i.e. $p(s_t\mid x_t)$ and $p(u_t\mid x_t)$.
  3. Slide: After updating its internal belief, the agent moves to the next time step and uses the inferred action $u_t$ in the previous time step to interact with the environment.

In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:

  • The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next $T$ positions based on the current action. These two function implement the Act-Execute-Observe phase.
  • The compute function infers the policy (which is a set of actions for the next $T$ time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.
  • The slide function implements the Slide phase, which moves the agent internal model to the next time step.
# We are going to use some private functionality from ReactiveMP, 
+# in the future we should expose a proper API for this
+import RxInfer.ReactiveMP: getrecent, messageout
+
+function create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)
+    Epsilon = fill(huge, 1, 1)                # Control prior variance
+    m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors
+    V_u = Matrix{Float64}[ Epsilon for k=1:T ]
+
+    Sigma    = 1e-4*diageye(2) # Goal prior variance
+    m_x      = [zeros(2) for k=1:T]
+    V_x      = [huge*diageye(2) for k=1:T]
+    V_x[end] = Sigma # Set prior to reach goal at t=T
+
+    # Set initial brain state prior
+    m_s_t_min = [initial_position, initial_velocity] 
+    V_s_t_min = tiny * diageye(2)
+    
+    # Set current inference results
+    result = nothing
+
+    # The `infer` function is the heart of the agent
+    # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing
+    compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin
+        m_u[1] = [ upsilon_t ] # Register action with the generative model
+        V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action
+
+        m_x[1] = y_hat_t # Register observation with the generative model
+        V_x[1] = tiny*diageye(2) # Clamp goal prior to observation
+
+        data = Dict(:m_u       => m_u, 
+                    :V_u       => V_u, 
+                    :m_x       => m_x, 
+                    :V_x       => V_x,
+                    :m_s_t_min => m_s_t_min,
+                    :V_s_t_min => V_s_t_min)
+        
+        model  = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) 
+        result = infer(model = model, data = data)
+    end
+    
+    # The `act` function returns the inferred best possible action
+    act = () -> begin
+        if result !== nothing
+            return mode(result.posteriors[:u][2])[1]
+        else
+            return 0.0 # Without inference result we return some 'random' action
+        end
+    end
+    
+    # The `future` function returns the inferred future states
+    future = () -> begin 
+        if result !== nothing 
+            return getindex.(mode.(result.posteriors[:s]), 1)
+        else
+            return zeros(T)
+        end
+    end
+
+    # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step
+    # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`
+    slide = () -> begin
+        (s, ) = result.returnval
+        
+        slide_msg_idx = 3 # This index is model dependend
+        (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))
+
+        m_u = circshift(m_u, -1)
+        m_u[end] = [0.0]
+        V_u = circshift(V_u, -1)
+        V_u[end] = Epsilon
+
+        m_x = circshift(m_x, -1)
+        m_x[end] = x_target
+        V_x = circshift(V_x, -1)
+        V_x[end] = Sigma
+    end
+
+    return (compute, act, slide, future)    
+end
create_agent (generic function with 1 method)

Now it's time to see if we can help our friends arrive at the camping site by midnight?

(execute_ai, observe_ai) = create_world(
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+) # Let there be a world
+
+T_ai = 50
+
+(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent
+    T  = T_ai, 
+    Fa = Fa,
+    Fg = Fg, 
+    Ff = Ff, 
+    engine_force_limit = engine_force_limit,
+    x_target = x_target,
+    initial_position = initial_position,
+    initial_velocity = initial_velocity
+) 
+
+N_ai = 100
+
+# Step through experimental protocol
+agent_a = Vector{Float64}(undef, N_ai) # Actions
+agent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future
+agent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations
+
+for t=1:N_ai
+    agent_a[t] = act_ai()               # Invoke an action from the agent
+    agent_f[t] = future_ai()            # Fetch the predicted future states
+    execute_ai(agent_a[t])              # The action influences hidden external states
+    agent_x[t] = observe_ai()           # Observe the current environmental outcome (update p)
+    compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)
+    slide_ai()                          # Prepare for next iteration
+end
+
+animation_ai = @animate for i in 1:N_ai
+    # pls - plot landscape
+    pls = plot(valley_x, valley_y, title = "Active inference results", label = "Landscape", color = "black")
+    pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label="car")
+    pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label="goal")   
+    pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = "Predicted future", alpha = map(i -> 0.5 / i, 1:T_ai))
+    
+    # pef - plot engine force
+    pef = plot(Fa.(agent_a[1:i]), title = "Engine force (agents actions)", xlim = (0, N_ai), ylim = (-0.05, 0.05))
+    
+    plot(pls, pef, size = (800, 400))
+end
+    
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_ai, "../pics/ai-mountain-car-ai.gif", fps = 24, show_msg = false);

Voila! The car now is able to reach the camping site with a smart strategy.

The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.

Now our friends can enjoy their trip at the camping site!.

Reference

We refer reader to the Thijs van de Laar (2019) "Simulating active inference processes by message passing" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) "Deep active inference".

diff --git a/v2.16.0/examples/advanced_examples/Advanced Tutorial/index.html b/v2.16.0/examples/advanced_examples/Advanced Tutorial/index.html new file mode 100644 index 000000000..0be26e621 --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Advanced Tutorial/index.html @@ -0,0 +1,416 @@ + +Advanced Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Advanced Tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.

This tutorial is also available in the documentation.

General model specification syntax

We use the @model macro from the RxInfer.jl package to create a probabilistic model $p(s, y)$ and we also specify extra constraints on the variational family of distributions $\mathcal{Q}$, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.

# the `@model` macro accepts a regular Julia function
+@model function test_model1(s_mean, s_precision)
+    
+    # We use the `randomvar` function to create 
+    # a random variable in our model
+    s = randomvar()
+    
+    # the `tilde` operator creates a functional dependency
+    # between variables in our model and can be read as 
+    # `sampled from` or `is modeled by`
+    s ~ Normal(mean = s_mean, precision = s_precision)
+    
+    # We use the `datavar` function to create 
+    # observed data variables in our models
+    # We also need to specify the type of our data 
+    # In this example it is `Float64`
+    y = datavar(Float64)
+    
+    y ~ Normal(mean = s, precision = 1.0)
+    
+    # It is possible to return something from the model specification (including variables and nodes)
+    return "Hello world"
+end

The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.

modelgenerator = test_model1(0.0, 1.0)
+
+model, returnval = create_model(modelgenerator)
(FactorGraphModel(), "Hello world")

The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.

RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as:

  • getnodes(): returns an array of factor nodes in a corresponding factor graph
  • getrandom(): returns an array of random variables in the model
  • getdata(): returns an array of data inputs in the model
  • getconstant(): returns an array of constant values in the model
getnodes(model)
FactorNodesCollection(nodes: 2)
getrandom(model) .|> name
1-element Vector{Symbol}:
+ :s
getdata(model) .|> name
1-element Vector{Symbol}:
+ :y
getconstant(model) .|> getconst
3-element Vector{Float64}:
+ 0.0
+ 1.0
+ 1.0

It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:

@model function test_model2(n)
+    
+    if n <= 1
+        error("`n` argument must be greater than one.")
+    end
+    
+    # `randomvar(n)` creates a dense sequence of 
+    # random variables
+    s = randomvar(n)
+    
+    # `datavar(Float64, n)` creates a dense sequence of 
+    # observed data variables of type `Float64`
+    y = datavar(Float64, n)
+    
+    s[1] ~ Normal(mean = 0.0, precision = 0.1)
+    y[1] ~ Normal(mean = s[1], precision = 1.0)
+    
+    for i in 2:n
+        s[i] ~ Normal(mean = s[i - 1], precision = 1.0)
+        y[i] ~ Normal(mean = s[i], precision = 1.0)
+    end
+    
+end
model, _ = create_model(test_model2(10));
# An amount of factor nodes in generated Factor Graph
+getnodes(model) |> length
20
# An amount of random variables
+getrandom(model) |> length
10
# An amount of data inputs
+getdata(model) |> length
10
# An amount of constant values
+getconstant(model) |> length
21

It is also possible to use complex expressions inside the functional dependency expressions

y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)

The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists

# s = randomvar() here is optional
+# `~` creates random variables automatically
+s ~ NormalMeanPrecision(0.0, 1.0)

An example model which will throw an error:

@model function error_model1()
+    s = 1.0
+    s ~ NormalMeanPrecision(0.0, 1.0)
+end

By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as

# Creates constant reference in a model with a prespecified value
+c = constvar(0.0)

An example:

@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)
+    
+    s = randomvar(n)
+    
+    y = datavar(Vector{Float64}, n)
+    
+    # Here we create constant references
+    # for constant matrices in our model 
+    # to make inference more memory efficient
+    cA = constvar(A)
+    cP = constvar(P)
+    cQ = constvar(Q)
+    
+    s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)
+    y[1] ~ MvNormal(mean = s[1], covariance = cQ)
+    
+    for i in 2:n
+        s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)
+        y[i] ~ MvNormal(mean = s[i], covariance = cQ)
+    end
+    
+end

The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:

@model function test_model()
+
+    # In this example `ynode` refers to the corresponding 
+    # `GaussianMeanVariance` node created in the factor graph
+    ynode, y ~ GaussianMeanVariance(0.0, 1.0)
+    
+    return ynode, y
+end

Probabilistic inference in RxInfer.jl

RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.

Observables

Observables are lazy push-based collections and they deliver their values over time.

# Timer that emits a new value every second and has an initial one second delay 
+observable = timer(300, 300)
TimerObservable(300, 300)

A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:

actor = (value) -> println(value)
+subscription1 = subscribe!(observable, actor)
TimerSubscription()
# We always need to unsubscribe from some observables
+unsubscribe!(subscription1)
# We can modify our observables
+modified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)
ProxyObservable(Int64, MapProxy(Int64))
subscription2 = subscribe!(modified, (value) -> println(value))
TimerSubscription()
unsubscribe!(subscription2)
@model function coin_toss_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+    
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    
+    # We assume that the outcome of each coin flip 
+    # is modeled by a Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+    
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during the inference step
+    return y, θ
+end

We can call the inference function to run inference in such model:

p = 0.75 # Bias of a coin
+
+dataset = float.(rand(Bernoulli(p), 500));
+
+result = infer(
+    model = coin_toss_model(length(dataset)),
+    data  = (y = dataset, )
+)
+
+println("Inferred bias: ", mean_var(result.posteriors[:θ]))
Inferred bias: (0.7662082514734774, 0.00035124150362241923)

We can see that the inferred bias is quite close to the actual value we used in the dataset generation.

The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions:

  • getmarginal(x): for a single random variable x
  • getmarginals(xs): for a dense sequence of random variables sx

Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.

_, (y, θ) = create_model(coin_toss_model(length(dataset)));
# As soon as we have a new value for the marginal posterior over the `θ` variable
+# we simply print the first two statistics of it
+θ_subscription = subscribe!(getmarginal(θ), (marginal) -> println("New update: mean(θ) = ", mean(marginal), ", std(θ) = ", std(marginal)));

To pass data to our model we use update! function

update!(y, dataset)
New update: mean(θ) = 0.7662082514734774, std(θ) = 0.01874143814178675
# It is necessary to always unsubscribe from running observables
+unsubscribe!(θ_subscription)
# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them
+# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing
+update!(y, dataset)

Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.

# the `keep` actor simply keeps all incoming updates in an internal storage, ordered
+θvalues = keep(Marginal)
KeepActor{Marginal}(Marginal[])
# `getmarginal` always emits last cached value as its first value
+subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=390.0, β=119.0))
subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
2-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=390.0, β=119.0))
+ Marginal(Beta{Float64}(α=390.0, β=119.0))
# the `buffer` actor keeps very last incoming update in an internal storage and can also store 
+# an array of updates for a sequence of random variables
+θbuffer = buffer(Marginal, 1)
BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=390.0, β=119.0))
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=390.0, β=119.0))

Reactive Online Inference

RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.

@model function online_coin_toss_model()
+    
+    # We create datavars for the prior 
+    # over `θ` variable
+    θ_a = datavar(Float64)
+    θ_b = datavar(Float64)
+    
+    θ ~ Beta(θ_a, θ_b)
+    
+    y = datavar(Float64)
+    y ~ Bernoulli(θ)
+
+end
autoupdates = @autoupdates begin 
+    θ_a, θ_b = params(q(θ))
+end
(θ_a,θ_b = params(q(θ)),)
rxresult = infer(
+    model = online_coin_toss_model(),
+    data  = (y = dataset, ),
+    autoupdates = autoupdates,
+    historyvars = (θ = KeepLast(), ),
+    keephistory = length(dataset),
+    initmarginals = (
+        θ = vague(Beta),
+    ),
+    autostart = true
+);
animation = @animate for i in 1:length(dataset)
+    plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = "Online coin bias inference", label = "Inferred bias", legend = :bottomright)
+    hline!([ p ], label = "Real bias", size = (600, 200))
+end
+
+gif(animation, "../pics/online-coin-bias-inference.gif", fps = 24, show_msg = false);

In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.

That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.

Variational inference

On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions $q \in \mathcal{Q}$. Often this involves assuming some factorization over $q$. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.

@model function test_model6_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+
+end

In this example we specified an extra constraints for $q_a$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

There are several options to specify the mean-field factorisation constraint. 

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name

It is also possible to use local structured factorisation:

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification

RxInfer.jl constraints macro

RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:

constraints6 = @constraints begin
+     q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

Note: where blocks have higher priority over constraints specification

@model function test_model6(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end

Inference

To run inference in this model we again need to create a synthetic dataset:

dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);

inference function

In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:

Use ?inference to quickly check the documentation for the inference function.

result = infer(
+    model         = test_model6(length(dataset)),
+    data          = (y = dataset, ),
+    constraints   = constraints6, 
+    initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),
+    returnvars    = (μ = KeepLast(), τ = KeepLast()),
+    iterations    = 10,
+    free_energy   = true,
+    showprogress  = true
+)
Inference results:
+  Posteriors       | available for (μ, τ)
+  Free Energy:     | Real[14763.3, 3276.03, 684.158, 646.181, 646.181, 646.
+181, 646.181, 646.181, 646.181, 646.181]
println("μ: mean = ", mean(result.posteriors[:μ]), ", std = ", std(result.posteriors[:μ]))
μ: mean = -3.0056908466725094, std = 0.014489267624899296
println("τ: mean = ", mean(result.posteriors[:τ]), ", std = ", std(result.posteriors[:τ]))
τ: mean = 4.763281190254187, std = 0.2128077093353377

Manual inference

For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);

For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:

setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values)
10-element Vector{Marginal}:
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.011708551085051e-9, w=
+0.010000001002000566))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.568551355196337, w=9.
+182098823340285))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9439.094316526523, w=314
+0.4109865644887))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14309.600684674531, w=47
+60.835837794097))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.97336150061, w=476
+3.288738549474))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980723228184, w=47
+63.291187807456))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730575227, w=47
+63.29119025181))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730582567, w=47
+63.291190254112))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730582556, w=47
+63.291190254099))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730582549, w=47
+63.291190254099))
getvalues(τ_values)
10-element Vector{Marginal}:
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=5.0000000000462156e14))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=54622.176412349254))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=159.5337672301783))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.23384325945597))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17965197908343))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959789617599))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784220113))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784214716))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784214723))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784214727))
println("μ: mean = ", mean(last(μ_values)), ", std = ", std(last(μ_values)))
μ: mean = -3.0056908466725094, std = 0.014489267624899296
println("τ: mean = ", mean(last(τ_values)), ", std = ", std(last(τ_values)))
τ: mean = 4.763281190254187, std = 0.2128077093353377

Form constraints

In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.

<img style="display: block; margin-left: auto; margin-right: auto; width: 50%;" src="./pics/posterior.png" />

@model function test_model7_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+    
+    return μ, τ, y
+end

As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:

constraints7 = @constraints begin 
+    q(μ) :: PointMass
+    
+    q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+    q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

In this example we specified an extra constraints for $q_i$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

@model function test_model7(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar()
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end
model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);
setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, PointMass(1.0))
+
+μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values) |> last
Marginal(PointMass{Float64}(-3.0056908529699893))
getvalues(τ_values) |> last
Marginal(GammaShapeRate{Float64}(a=501.0, b=105.07462840395456))

By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.

μ = randomvar() where { 
+    prod_constraint = ProdGeneric(),
+    form_constraint = SampleListFormConstraint() 
+}

Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:

μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }

Note: @constraints macro specifies required prod_constraint automatically.

Free Energy

During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);
bfe_observable = score(model, Float64, BetheFreeEnergy())
ProxyObservable(Float64, ErrorIfProxy())
bfe_subscription = subscribe!(bfe_observable, (fe) -> println("Current BFE value: ", fe));
# Reset the model with vague marginals
+setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
+
+for i in 1:10
+    update!(y, dataset)
+end
Current BFE value: 658.7153120621533
+Current BFE value: 646.1805207523544
+Current BFE value: 646.1805205034352
+Current BFE value: 646.1805205034316
+Current BFE value: 646.1805205034375
+Current BFE value: 646.1805205034352
+Current BFE value: 646.1805205034343
+Current BFE value: 646.1805205034334
+Current BFE value: 646.1805205034334
+Current BFE value: 646.1805205034334
# It always necessary to unsubscribe and release computer resources
+unsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])

Meta data specification

During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:

# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of 
+# the autoregressive process and its order. In addition it specifies that the message computation rules should
+# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations
+# by cost of possible numerical instabilities during an inference procedure
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }
+...
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }

Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:

# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` 
+# method with `21` sigma points for approximation of non-lineariety between hierarchy layers
+xt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }

The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.

RxInfer.jl @meta macro

Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:

@meta begin 
+     AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())
+end
Meta specification:
+  AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())
+Options:
+  warn = true

Creating custom nodes and message computation rules

Custom nodes

To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:

# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification
+@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]
+
+# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error
+struct NormalMeanVariance end 
+
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# It is also possible to use function objects as a node functional form
+function dot end
+
+# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them 
+# out = dot(x, a)
+@node typeof(dot) Deterministic [ out, x, a ]

Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.

After that it is possible to use the newly created node during model specification:

@model function test_model()
+    ...
+    y ~ dot(x, a)
+    ...
+end

Custom messages computation rules

RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:

\[\begin{aligned} +\mu_z = \mu_x + \mu_y\\ +V_z = V_x + V_y +\end{aligned}\]

To specify this in RxInfer.jl we use the @node and @rule macros:

@node typeof(+) Deterministic  [ z, x, y ]
+
+@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin
+    x_mean, x_var = mean_var(m_x)
+    y_mean, y_var = mean_var(m_y)
+    return NormalMeanVariance(x_mean + y_mean, x_var + y_var)
+end

In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:

\[\begin{aligned} +q(z) = \int q(z, x, y) \mathrm{d}x\mathrm{d}y +\end{aligned}\]

If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:

\[\begin{aligned} +\mu(z) = \int f(x, y, z)\mu(x)\mu(y)\mathrm{d}x\mathrm{d}y +\end{aligned}\]

\[\begin{aligned} +\nu(z) = \exp{ \int \log f(x, y, z)q(x)q(y)\mathrm{d}x\mathrm{d}y } +\end{aligned}\]

The @rule macro supports both cases with special prefixes during rule specification:

  • m_ prefix corresponds to the incoming message on a specific edge
  • q_ prefix corresponds to the posterior marginal of a specific edge

Example of a Sum-Product rule with m_ messages used:

@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin 
+    m_out_mean, m_out_cov = mean_cov(m_out)
+    return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))
+end

Example of a Variational rule with Mean-Field assumption with q_ posteriors used:

@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin 
+    return NormalMeanPrecision(mean(q_out), mean(q_τ))
+end

RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:

@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin
+    m, V = mean_cov(q_out_μ)
+    θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))
+    α = convert(typeof(θ), 1.5)
+    return Gamma(α, θ)
+end

NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:

# Inference backend expects arguments in `@rule` macro to be in the same order
+@node NormalMeanPrecision Stochastic [ out, μ, τ ]

Any rule always has access to the meta information with hidden the meta::Any variable:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin 
+    ...
+    println(meta)
+    ...
+end

It is also possible to dispatch on a specific type of a meta object:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin 
+    ...
+end

or

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin 
+    ...
+end

Customizing messages computational pipeline

In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.

<img style="display: block; margin-left: auto; margin-right: auto; width: 30%;" src="./pics/pipeline.png" width="20%" />

# Logs all outbound messages
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }
+# Initialise messages to be vague
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }
+# In principle, it is possible to approximate outbound messages with Laplace Approximation
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }

Let us return to the coin toss model, but this time we want to print flowing messages:

@model function coin_toss_model_log(n)
+
+    y = datavar(Float64, n)
+
+    θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage("θ") }
+
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)  where { pipeline = LoggerPipelineStage("y[$i]") }
+    end
+    
+    return y, θ
+end
_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));
θ_subscription = subscribe!(getmarginal(θ), (value) -> println("New posterior marginal for θ: ", value));
[θ][Beta][out]: VariationalMessage()
coinflips = float.(rand(Bernoulli(0.5), 5));
update!(y, coinflips)
[y[1]][Bernoulli][p]: VariationalMessage()
+[y[2]][Bernoulli][p]: VariationalMessage()
+[y[3]][Bernoulli][p]: VariationalMessage()
+[y[4]][Bernoulli][p]: VariationalMessage()
+[y[5]][Bernoulli][p]: VariationalMessage()
+New posterior marginal for θ: Marginal(Beta{Float64}(α=4.0, β=10.0))
unsubscribe!(θ_subscription)
# Inference is lazy and does not send messages if no one is listening for them
+update!(y, coinflips)
diff --git a/v2.16.0/examples/advanced_examples/Assessing People Skills/index.html b/v2.16.0/examples/advanced_examples/Assessing People Skills/index.html new file mode 100644 index 000000000..6ebba4a79 --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Assessing People Skills/index.html @@ -0,0 +1,49 @@ + +Assessing People’s Skills · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Assessing People’s Skills

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of "Model-Based Machine Learning" by Winn et al.

Problem Statement

We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?

We model the result for question $i$ as a continuous variable $r_i\in[0,1]$, and skill/attitude as a binary variable $s_i \in \{0, 1\}$, where $s_1$ represents whether the student has partied, and $s_2$ and $s_3$ represent whether the student has studied the chapters for the corresponding questions.

We assume the following logic:

  • If the student is alert (has not partied), then they will score on the first question;
  • If the student is alert or has studied chapter two, then they will score on question two;
  • If the student can answer question two and has studied chapter three, then they will score on question three.

Generative Model Definition

To model the probability for correct answers, we assume a latent state variable $t_i \in \{0,1\}$. The dependencies between the variables can then be modeled by the following Bayesian network:

(s_1)   (s_2)   (s_3)
+  |       |       |
+  v       v       v
+(t_1)-->(t_2)-->(t_3)
+  |       |       |
+  v       v       v
+(r_1)   (r_2)   (r_3)

As prior beliefs, we assume that a student is equally likely to study/party or not: $s_i \sim Ber(0.5)\,,$ for all $i$. Next, we model the domain logic as $\begin{aligned} t_1 &= ¬s_1\\ + t_2 &= t_1 ∨ s_2\\ + t_3 &= t_2 ∧ s_3\,. \end{aligned}$ For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as $t_i \sim Ber(s_i)\,,$ for all $i$.

Custom Nodes and Rules

The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.

In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.

using RxInfer, Random
+
+# Create Score node
+struct Score end
+
+@node Score Stochastic [out, in]

We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.

# Adding update rule for the Score node
+@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin     
+    return Bernoulli(mean(q_out))
+end

Generative Model Specification

We can now build the full generative model.

# GraphPPL.jl exports the `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function skill_model()
+    s = randomvar(3)
+    t = randomvar(3)
+    r = datavar(Float64, 3)
+
+    # Priors
+    for i=1:3
+        s[i] ~ Bernoulli(0.5)
+    end
+
+    # Domain logic
+    t[1] ~ ¬s[1]
+    t[2] ~ t[1] || s[2]
+    t[3] ~ t[2] && s[3]
+    
+    # Results
+    for i=1:3
+        r[i] ~ Score(t[i])
+    end
+end

Inference Specification

Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.

test_results = [0.1, 0.1, 0.1]
+inference_result = infer(
+    model = skill_model(),
+    data  = (r = test_results, )
+)
Inference results:
+  Posteriors       | available for (s, t)

Results

# Inspect the results
+map(params, inference_result.posteriors[:s])
3-element Vector{Tuple{Float64}}:
+ (0.9872448979591837,)
+ (0.06377551020408162,)
+ (0.4719387755102041,)

These results suggest that this particular student was very likely out on the town last night.

diff --git a/v2.16.0/examples/advanced_examples/Chance Constraints/index.html b/v2.16.0/examples/advanced_examples/Chance Constraints/index.html new file mode 100644 index 000000000..c6bce2b73 --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Chance Constraints/index.html @@ -0,0 +1,166 @@ + +Chance-Constrained Active Inference · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Chance-Constrained Active Inference

This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, "Chance-constrained active inference") and discussion with John Boik.

We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. 

using Pkg; Pkg.activate(".."); Pkg.instantiate();
using Plots, Distributions, StatsFuns, RxInfer

Chance-Constraint Node Definition

A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not "overflow" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.

In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.

struct ChanceConstraint end  
+
+# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol
+@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]
# Function to compute normalizing constant and central moments of a truncated Gaussian distribution
+function truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)
+    V = clamp(V, tiny, huge)
+    StdG = Distributions.Normal(m, sqrt(V))
+    TrG = Distributions.Truncated(StdG, a, b)
+    
+    Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a)  # safe mass for standard Gaussian
+    
+    if Z < tiny
+        # Invalid region; return undefined mean and variance of truncated distribution
+        Z    = 0.0
+        m_tr = 0.0
+        V_tr = 0.0
+    else
+        m_tr = Distributions.mean(TrG)
+        V_tr = Distributions.var(TrG)
+    end
+    
+    return (Z, m_tr, V_tr)
+end;
@rule ChanceConstraint(:out, Marginalisation) (
+    m_out::UnivariateNormalDistributionsFamily, # Require inbound message
+    q_lo::PointMass, 
+    q_hi::PointMass, 
+    q_epsilon::PointMass, 
+    q_atol::PointMass) = begin 
+
+    # Extract parameters
+    lo = mean(q_lo)
+    hi = mean(q_hi)
+    epsilon = mean(q_epsilon)
+    atol = mean(q_atol)
+    
+    (m_bw, V_bw) = mean_var(m_out)
+    (xi_bw, W_bw) = (m_bw, 1. /V_bw)  # check division by  zero
+    (m_tilde, V_tilde) = (m_bw, V_bw)
+    
+    # Compute statistics (and normalizing constant) of q in safe region G
+    # Phi_G is called the "safe mass" 
+    (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)
+
+    xi_fw = xi_bw
+    W_fw  = W_bw
+    if epsilon <= 1.0 - Phi_G # If constraint is active
+        # Initialize statistics of uncorrected belief
+        m_tilde = m_bw
+        V_tilde = V_bw
+        for i = 1:100 # Iterate at most this many times
+            (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G
+            (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G
+
+            # Compute moments of non-G region as a mixture of left and right truncations
+            Phi_nG = Phi_lG + Phi_rG
+            m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG
+            V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2
+
+            # Compute moments of corrected belief as a mixture of G and non-G regions
+            m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG
+            V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2
+            # Re-compute statistics (and normalizing constant) of corrected belief
+            (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)
+            if (1.0 - Phi_G) < (1.0 + atol)*epsilon
+                break # Break the loop if the belief is sufficiently corrected
+            end
+        end
+        
+        # Convert moments of corrected belief to canonical form
+        W_tilde = inv(V_tilde)
+        xi_tilde = W_tilde * m_tilde
+
+        # Compute canonical parameters of forward message
+        xi_fw = xi_tilde - xi_bw
+        W_fw  = W_tilde - W_bw
+    end
+
+    return NormalWeightedMeanPrecision(xi_fw, W_fw)
+end

Definition of the Environment

We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.

wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile
+
+function initializeWorld()
+    x_0 = 0.0 # Initial elevation
+    
+    x_t_last = x_0
+    function execute(t::Int64, a_t::Float64)
+        x_t = x_t_last + a_t + wind(t) # Update elevation
+    
+        x_t_last = x_t # Reset state
+                
+        return x_t
+    end
+
+    x_t = x_0 # Predefine outcome variable
+    observe() = x_t # State is fully observed
+
+    return (execute, observe)
+end;

Generative Model for Regulator

We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.

@model function regulator_model(; T, lo, hi, epsilon, atol)
+    # Fully observed state
+    x_t = datavar(Float64)
+
+    # Control prior statistics
+    m_u = datavar(Float64, T)
+    v_u = datavar(Float64, T)    
+        
+    # Random variables
+    u = randomvar(T) # Control
+    x = randomvar(T) # Elevation
+    
+    # Loop over horizon
+    x_k_last = x_t
+    for k = 1:T
+        u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior
+        x[k] ~ x_k_last + u[k] # Transition model
+        x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state
+            pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency
+        x_k_last = x[k]
+    end
+    
+    return (u, x)
+end

Reactive Agent Definition

function initializeAgent()
+    # Set control prior statistics
+    m_u = zeros(T)
+    v_u = lambda^(-1)*ones(T)
+    
+    function compute(x_t::Float64)
+        model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)
+        data_t = (m_u = m_u, v_u = v_u, x_t = x_t)
+        
+        result = infer(
+            model = model_t, 
+            data = data_t,
+            iterations = n_its)
+
+        # Extract policy from inference results
+        pol = mode.(result.posteriors[:u][end])
+
+        return pol
+    end
+
+    pol = zeros(T) # Predefine policy variable
+    act() = pol[1]
+
+    return (compute, act)
+end;

Action-Perception Cycle

Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. 

# Simulation parameters
+N = 160 # Total simulation time
+T = 1 # Lookahead time horizon
+lambda = 1.0 # Control prior precision
+lo = 1.0 # Chance region lower bound
+hi = Inf # Chance region upper bound
+epsilon = 0.01 # Allowed chance violation
+atol = 0.01 # Convergence tolerance for chance constraints
+n_its = 10;  # Number of inference iterations
(execute, observe) = initializeWorld() # Let there be a world
+(compute, act) = initializeAgent() # Let there be an agent
+
+a = Vector{Float64}(undef, N) # Actions
+x = Vector{Float64}(undef, N) # States
+for t = 1:N
+    a[t] = act()
+           execute(t, a[t])
+    x[t] = observe()
+           compute(x[t])
+end

Results

Results show that the agent does not allow the wind to push it all the way to the ground.

p1 = plot(1:N, wind.(1:N), color="blue", label="Wind", ylabel="Velocity", lw=2)
+plot!(p1, 1:N, a, color="red", label="Control", lw=2)
+p2 = plot(1:N, x, color="black", lw=2, label="Agent", ylabel="Elevation")
+plot(p1, p2, layout=(2,1))

diff --git a/v2.16.0/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html b/v2.16.0/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html new file mode 100644 index 000000000..74e53dedb --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html @@ -0,0 +1,143 @@ + +Conjugate-Computational Variational Message Passing (CVI) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Conjugate-Computational Variational Message Passing (CVI)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions

In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.

This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.

An example: nonlinear dynamical system

A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position $z_t$ at time $t$. Instead they have access to the observed squared distance $y_t$ between the object and some reference point $s$. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:

# data generating process
+nr_observations = 50
+reference_point = 53
+hidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)
+measurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);
# plot hidden location and reference frame
+p1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label="hidden location")
+hline!([reference_point], linewidth=3, label="reference point")
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot measurements
+p2 = scatter(1:nr_observations, measurements, linewidth=3, label="measurements")
+xlabel!("time [sec]"), ylabel!("squared distance [cm2]")
+
+plot(p1, p2, size=(1200, 500))

The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model

\[\begin{aligned} + p(\tau) & = \Gamma(\tau \mid \alpha_{\tau}, \beta_{\tau}),\\ + p(\gamma) & = \Gamma(\gamma \mid \alpha_{\gamma}, \beta_{\gamma}),\\ + p(z_t \mid z_{t - 1}, \tau) & = \mathcal{N}(z_t \mid z_{t - 1} + 1, \tau^{-1}),\\ + p(y_t \mid z_t, \gamma) & = \mathcal{N}(y_t \mid (z_t - s)^2, \gamma^{-1}), +\end{aligned}\]

where the researchers put priors on the process and measurement noise parameters, $\tau$ and $\gamma$, respectively. They do this, because they do not know the accuracy of their devices.

The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:

function compute_squared_distance(z)
+    (z - reference_point)^2
+end;
@model function measurement_model(nr_observations)
+
+    # allocate random variables and observations
+    z = randomvar(nr_observations)
+    y = datavar(Float64, nr_observations)
+
+    # set priors on precision parameters
+    τ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    γ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    
+    # specify estimate of initial location
+    z[1] ~ Normal(mean = 0, precision = τ)
+    y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)
+
+    # loop over observations
+    for t in 2:nr_observations
+
+        # specify state transition model
+        z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)
+
+        # specify non-linear observation model
+        y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)
+        
+    end
+
+end

But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).

The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:

@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)
+    compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)
+end;

In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:

@meta function model_meta(...)
+    f() -> CVI(args...)
+end

See ?CVI for more information about the args....

In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.

In the above example, we will assume the following posterior factorization:

@constraints function measurement_constraints()
+    q(z, τ, γ) = q(z)q(τ)q(γ)
+end;

This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as 

@constraints function posterior_constraints() begin
+    q(z, γ) = q(z)q(γ) # CVI
+    q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node
+end

Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.

results = infer(
+    model = measurement_model(nr_observations),
+    data = (y = measurements,),
+    iterations = 5,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = measurement_constraints(),
+    meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),
+    initmessages = (z = NormalMeanVariance(0, 5),),
+    initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),
+)
Inference results:
+  Posteriors       | available for (z)
+  Free Energy:     | Real[1241.91, 429.933, 376.869, 365.774, 362.879]
# plot estimates for location
+p1 = plot(collect(1:nr_observations), hidden_location, label = "hidden location", legend=:topleft, linewidth=3, color = :red)
+plot!(map(mean, results.posteriors[:z]), label = "estimated location (±2σ)", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot Bethe free energy
+p2 = plot(results.free_energy, linewidth=3, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size = (1200, 500))

Requirements

There are several main requirements for the CVI procedure to satisfy:

  1. The out interface of the non-linearity must be independently factorized with respect to other variables in the model.
  2. The messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.

In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as

@model function model(...)
+    ...
+    y ~ f(x1, x2, ..., xN)
+    ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity
+    ... 
+end
+
+@constraints function constraints_meta() begin
+    q(y, z1, ..., zn) = q(y)q(z1,...,zM)
+    ...
+end;
+
+@meta function model_meta(...)
+    f() -> CVI(rng, nr_samples, nr_iterations, optimizer))
+end

Note that not all exponential family distributions are implemented.

Extensions

Using a custom optimizer

CVI only supports Optimisers optimizers out of the box.

Below an explanation on how to extend to it to a custom optimizer.

Suppose we have CustomDescent structure which we want to use inside CVI for optimization.

To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).

ReactiveMP.cvi_update! incapsulates the gradient step:

  1. opt is used to select your optimizer structure
  2. λ is the current value
  3. ∇ is a gradient value computed inside CVI.
struct CustomDescent 
+    learning_rate::Float64
+end
+
+# Must return an optimizer and its initial state
+function ReactiveMP.cvi_setup(opt::CustomDescent, q)
+     return (opt, nothing)
+end
+
+# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)
+function ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)
+    opt, _ = opt_and_state
+    λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))
+    copyto!(new_λ, λ̂)
+    return opt_and_state, new_λ
+end

Let's try to apply it to a model: $\begin{aligned} p(x) & = \mathcal{N}(0, 1),\\ + p(y_{i}\mid x) & = \mathcal{N}(y_i \mid x^2, 1),\\ +\end{aligned}$

Let's generate some synthetic data for the model

# generate data
+y = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)
+histogram(y)

Again we can create the corresponding model as:

# specify non-linearity
+f(x) = x ^ 2
+
+# specify model
+@model function normal_square_model(nr_observations)
+
+    # allocate observations
+    y = datavar(Float64, nr_observations)
+
+    # describe prior on latent state
+    x ~ NormalMeanPrecision(0, 100)
+
+    # transform latent state
+    mean ~ f(x)
+
+    # observation model
+    y .~ NormalMeanVariance(mean, 1)
+
+end
+
+# specify meta
+@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)
+    f() ->  CVI(rng, nr_samples, nr_iterations, optimizer)
+end
normal_square_meta (generic function with 1 method)

We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:

Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.

res = infer(
+    model = normal_square_model(1000),
+    data = (y = y,),
+    iterations = 10,
+    free_energy = true,
+    initmessages = (x = NormalMeanVariance(0, 100),),
+    meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))
+)
+
+mean(res.posteriors[:x][end])
-18.998075156688632

The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working!

Note: $x^2$ can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.

diff --git a/v2.16.0/examples/advanced_examples/GP Regression by SSM/index.html b/v2.16.0/examples/advanced_examples/GP Regression by SSM/index.html new file mode 100644 index 000000000..92d93894a --- /dev/null +++ b/v2.16.0/examples/advanced_examples/GP Regression by SSM/index.html @@ -0,0 +1,99 @@ + +Solve GP regression by SDE · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Solve GP regression by SDE

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this notebook, we solve a GP regression problem by using "Stochastic Differential Equation" (SDE). This method is well described in the dissertation "Stochastic differential equation methods for spatio-temporal Gaussian process regression." by Arno Solin and "Sequential Inference for Latent Temporal Gaussian Process Models" by Jouni Hartikainen. The idea of the method is as follows.

Suppose a function $f(x)$ follows a zero-mean Gaussian Process $\begin{aligned} f(x) \sim \mathcal{GP}(0, k(x,x')). \end{aligned}$

When the dimensionality of $x$ is 1, we can consider $f(x)$ as a stochastic process over time, i.e. $f(t)$. For a certain classses of covariance functions, $f(t)$ is a solution to an $m$-th order linear stochastic differential equation (SDE) $\begin{aligned} a_0 f(t) + a_1 \frac{d f(t)}{dt} + \dots + a_m \frac{d^m f(t)}{dt^m} = w(t) \end{aligned}$

where $w(t)$ is a zero-mean white noise process with spectral density $Q_c$. If we define a vector-valued function $\mathbf{f}(t) = (f(t),\, d/dt f(t),\dots,\, d^{m-1}/dt^{m-1}f(t))$, then we can rewrite the above SDE under the companion form

\[\begin{aligned} +\frac{d \mathbf{f}(t)}{dt} = \mathbf{F}\, \mathbf{f}(t) + \mathbf{L} w(t) \quad (1) +\end{aligned}\]

where $\mathbf{F}$ and $\mathbf{L}$ are defined based on the choice of covariance functions. From (1), we have the following state-space model: $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \quad(2a) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}) \quad(2b). \\ +\end{aligned}$

where $\mathbf{A}_k = \exp{(\mathbf{F}\,\Delta t_k)}$, with $\Delta t_k = t_{k+1} - t_k$, is called the discrete-time state transition matrix, and $\mathbf{Q}_k$ the process noise covariance matrix. For the computation of $\mathbf{Q}_k$, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state $f_0 \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_0)$. For stationary covariance function, the SDE has a stationary state $f_\infty \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_\infty)$, where $\mathbf{P}_\infty$ is the solution to $\begin{aligned} \frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0 \quad (\mathrm{Lyapunov \, equation}). \end{aligned}$

With this stationary condition, the process noise covariance $\mathbf{Q}_k$ is computed as follows $\begin{aligned} \mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T \end{aligned}$

For one-dimensional problem the SDE representation of the GP is defined by the matrices $\mathbf{F}, \, \mathbf{L}, \, \mathbf{Q}_c, \, \mathbf{P}_0$ and $\mathbf{H}$. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.

using RxInfer, Random, Distributions, LinearAlgebra, Plots

Create state space model for GP regression

Here we create a state-space model $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}), \\ +\end{aligned}$ where $y_k$ is the noisy observation of the function $f$ at time $t_k$, and $\sigma^2_{noise}$ is the noise variance and assumed to be known.

@model function gp_regression(n, P∞, A, Q, H, σ²_noise)
+    f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)
+    f = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+    
+    f_prev = f_0
+
+    for i=1:n
+        f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])
+        y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)
+        f_prev = f[i]
+    end
+    return f, y
+end

Generate data

Random.seed!(10)
+n = 100
+σ²_noise = 0.04;
+t = collect(range(-2, 2, length=n)); #timeline
+f_true = sinc.(t); # true process
+f_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process
+
+pos = sort(randperm(75)[1:2:75]); 
+t_obser = t[pos]; # time where we observe data
+
+y_data = Array{Union{Float64,Missing}}(missing, n)
+for i in pos 
+    y_data[i] = f_noisy[i]
+end
+
+θ = [1., 1.]; # store [l, σ²]
+Δt = [t[1]]; # time difference
+append!(Δt, t[2:end] - t[1:end-1]);

Let's visualize our data

plot(t, f_true, label="True process f(t)")
+scatter!(t_obser, y_data[pos], label = "Noisy observations")
+xlabel!("t")
+ylabel!("f(t)")

Covariance function: Matern-3/2

The Matern is a stationary covariance function and defined as follows $\begin{aligned} k(\tau) = \sigma^2 \frac{2^{1-\nu}}{\Gamma(\nu)} \left(\frac{\sqrt{2\nu}\tau}{l} \right)^\nu K_\nu\left(\frac{\sqrt{2\nu}\tau}{l} \right) \end{aligned}$ where $\begin{aligned} \sigma^2: \text{the magnitude scale hyperparameter}\\ +l: \text{the characteristic length-scale}\\ +\nu: \text{the smoothness hyperparameter}\\ +K_\nu(.): \text{the modified Bessel function of the second kind}. \end{aligned}$ When we say the Matern-3/2, we mean $\nu=3/2$. The matrices for the state space model are computed as follows $\begin{aligned} \mathbf{F} = \begin{pmatrix} 0 & 1\\ +-\lambda^2 & -2\lambda \end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} 0 \\ 1 \end{pmatrix}, \quad \quad \mathbf{P}_\infty = \begin{pmatrix} \sigma^2 & 0 \\ 0 & \lambda^2\sigma^2 \end{pmatrix} ,\quad \quad \mathbf{H} = \begin{pmatrix} 1 & 0 \end{pmatrix}, \quad \quad Q_c = 4\lambda^3\sigma^2 \end{aligned}$ where $\lambda = \frac{\sqrt{3}}{l} $. From these matrices, we can define $\mathbf{A}_k$ and $\mathbf{Q}_k$.

λ = sqrt(3)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 1.];
+H = [1., 0.];
+F = [0. 1.; -λ^2 -2λ]
+P∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_32 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Covariance function: Matern-5/2

Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:

\[\begin{aligned} +\mathbf{F} = \begin{pmatrix} +0 & 1 & 0\\ +0 & 0 & 1 \\ +-\lambda^3 & -3\lambda^2 & -3\lambda +\end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} +0 \\ 0 \\ 1 +\end{pmatrix}, \quad \quad \mathbf{H} = \begin{pmatrix} +1 & 0 & 0 +\end{pmatrix}, \quad \quad Q_c = \frac{16}{3} \sigma^2 \lambda^5, +\end{aligned}\]

where $\lambda = \sqrt{5} / l$. To find $\mathbf{P}_\infty$, we solve the Lyapunov equation

\[\begin{aligned} +\frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0, +\end{aligned}\]

of which the solution is

\[\begin{aligned} +vec(\mathbf{P}_\infty) = (\mathbf{I} \otimes \mathbf{F} + \mathbf{F}\otimes\mathbf{I})^{-1}\, vec(-\mathbf{L}Q_c\mathbf{L}^T) +\end{aligned}\]

where $vec(.)$ is the vectorization operator and $\otimes$ denotes the Kronecker product. Now we can find $\mathbf{A}_k$ and $\mathbf{Q}_k$

\[\begin{aligned} +\mathbf{A}_k = \exp{(\mathbf{F}\Delta t_k)} +\end{aligned}\]

\[\begin{aligned} +\mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T +\end{aligned}\]

λ = sqrt(5)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 0., 1.];
+H = [1., 0., 0.];
+F = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]
+Qc = 16/3 * θ[2] * λ^5;
+
+I = diageye(3) ; 
+vec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); 
+P∞ = reshape(vec_P,3,3);
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_52 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Result

slicedim(dim) = (a) -> map(e -> e[dim], a)
+
+plot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M32", title = "Matern-3/2", legend =false, lw = 2)
+plot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M52",legend = :bottomleft, title = "GPRegression by SSM", lw = 2)
+plot!(t, f_true,label="true process", lw = 2)
+scatter!(t_obser, f_noisy[pos], label="Observations")
+xlabel!("t")
+ylabel!("f(t)")

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.

diff --git a/v2.16.0/examples/advanced_examples/Global Parameter Optimisation/index.html b/v2.16.0/examples/advanced_examples/Global Parameter Optimisation/index.html new file mode 100644 index 000000000..ac2b6e5fd --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Global Parameter Optimisation/index.html @@ -0,0 +1,497 @@ + +Global Parameter Optimisation · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Global Parameter Optimisation

This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.

By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Univariate State Space Model

Let us try use the following simple state space model:

\[\begin{aligned} + {x}_t &= {x}_{t-1} + c \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, p \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Our goal is to optimize parameters $c$ and ${m_{{x}_0}}$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)
+    
+    x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n)
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ x_prev + c
+        y[i] ~ NormalMeanVariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+
+    return x, y
+end
rng = MersenneTwister(42)
+
+P      = 1.0
+n      = 250
+c_real = -5.0
+data   = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);
# c[1] is C
+# c[2] is μ0
+function f(c)
+    x0_prior = NormalMeanVariance(c[2], 100.0)
+    result = infer(
+        model = smoothing(n, x0_prior, c[1], P), 
+        data  = (y = data,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
using Optim
res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     3.651509e+02     1.001412e+03
+ * time: 0.023398876190185547
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     3.645772e+02
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.18e-06 ≰ 0.0e+00
+    |x - x'|/|x'|          = 2.30e-07 ≰ 0.0e+00
+    |f(x) - f(x')|         = 9.13e-07 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00
+    |g(x)|                 = 2.56e-06 ≤ 1.0e-03
+
+ * Work counters
+    Seconds run:   6  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    67
+    ∇f(x) calls:   67
res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)
2-element Vector{Float64}:
+  1.0007749243942134
+ -5.14368311177876
println("Real value vs Optimized")
+println("Real:      ", [ 1.0, c_real ])
+println("Optimized: ", res.minimizer)
Real value vs Optimized
+Real:      [1.0, -5.0]
+Optimized: [1.0007749243942134, -5.14368311177876]

Multivariate state space model

Let us consider the multivariate state space model:

\[\begin{aligned} + \mathbf{x}_t &\sim \mathcal{N}\left(\mathbf{Ax}_{t-1}, \mathbf{Q} \right) \\ + \mathbf{y}_t &\sim \mathcal{N}\left(\mathbf{x}_{t}, \mathbf{P} \right) +\end{aligned}\]

with prior

\[\begin{aligned} +\mathbf{x}_0 \sim \mathcal{N}(\mathbf{m_{{x}_0}}, \mathbf{V_{{x}_0}})\ +\end{aligned}\]

and transition matrix

\[\begin{aligned} +\mathbf{A} = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} +\end{aligned}\]

Covariance matrices $\mathbf{V_{{x}_0}}$, $\mathbf{P}$ and $\mathbf{Q}$ are known. Our goal is to optimize parameters $\mathbf{m_{{x}_0}}$ and $\theta$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)
+    
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    
+    x_prev = x_prior
+    
+    A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)
+        y[i] ~ MvNormalMeanCovariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+    
+end
# Generate data
+function generate_rotate_ssm_data()
+    rng = MersenneTwister(1234)
+
+    θ = π / 8
+    A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+    Q = Matrix(Diagonal(1.0 * ones(2)))
+    P = Matrix(Diagonal(1.0 * ones(2)))
+
+    n = 300
+
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(x[i], Q))
+        
+        x_prev = x[i]
+    end
+
+    return θ, A, Q, P, n, x, y
+end
generate_rotate_ssm_data (generic function with 1 method)
θ, A, Q, P, n, x, y = generate_rotate_ssm_data();
px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+
+plot(px, size = (1200, 450))

function f(θ)
+    x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))
+    result = infer(
+        model = rotate_ssm(n, θ[1], x0, Q, P), 
+        data  = (y = y,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     2.192003e+04     9.032537e+04
+ * time: 7.009506225585938e-5
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.161372e+03
+
+ * Found with
+    Algorithm:     L-BFGS
+
+ * Convergence measures
+    |x - x'|               = 5.09e-09 ≰ 0.0e+00
+    |x - x'|/|x'|          = 4.48e-10 ≰ 0.0e+00
+    |f(x) - f(x')|         = 0.00e+00 ≤ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14
+    |g(x)|                 = 5.63e-07 ≰ 1.0e-12
+
+ * Work counters
+    Seconds run:   18  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    58
+    ∇f(x) calls:   58
println("Real value vs Optimized")
+println("Real:      ", θ)
+println("Optimized: ", res.minimizer[1])
+
+@show sin(θ), sin(res.minimizer[1])
+@show cos(θ), cos(res.minimizer[1])
Real value vs Optimized
+Real:      0.39269908169872414
+Optimized: 0.3929332481380117
+(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)
+(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)
+(0.9238795325112867, 0.9237898955654058)
x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))
+
+result = infer(
+    model = rotate_ssm(n, res.minimizer[1], x0, Q, P), 
+    data  = (y = y,), 
+    free_energy = true
+)
+
+xmarginals = result.posteriors[:x]
+
+px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "inf₁")
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "inf₂")
+
+plot(px, size = (1200, 450))

Learning Kalman filter with LSTM driven dynamic

In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example.

Our objective is to compute the marginal posterior distribution of the latent (hidden) state $x_k$ at each time step $k$, considering the history of measurements up to that time step:

\[ +p(x_k | y_{1:k}). +$$ + +The above expression represents the probability distribution of the latent state $x_k$ given the measurements $y_{1:k}$ up to time step $k$. + +```julia +using RxInfer, BenchmarkTools, Flux, ReverseDiff, Random, Plots, LinearAlgebra, ProgressMeter, JLD, StableRNGs +``` + + + +### Generate data + +```julia +# Lorenz system equations to be used to generate dataset +Base.@kwdef mutable struct Lorenz + dt::Float64 + σ::Float64 + ρ::Float64 + β::Float64 + x::Float64 + y::Float64 + z::Float64 +end + +function step!(l::Lorenz) + dx = l.σ * (l.y - l.x); l.x += l.dt * dx + dy = l.x * (l.ρ - l.z) - l.y; l.y += l.dt * dy + dz = l.x * l.y - l.β * l.z; l.z += l.dt * dz +end +; +``` + + +```julia +# Dataset +rng = StableRNG(999) + +ordered_dataset = [] +ordered_parameters = [] +for σ = 11:15 + for ρ = 23:27 + for β_nom = 6:9 + attractor = Lorenz(0.02, σ, ρ, β_nom/3.0, 1, 1, 1) + noise_free_data = [[1.0, 1.0, 1.0]] + for i=1:99 + step!(attractor) + push!(noise_free_data, [attractor.x, attractor.y, attractor.z]) + end + push!(ordered_dataset, noise_free_data) + push!(ordered_parameters, [σ, ρ, β_nom/3.0]) + end + end +end + +new_order = collect(1:100) +shuffle!(rng,new_order) + +dataset = [] # noisy dataset +noise_free_dataset = [] # noise free dataset +lorenz_parameters = [] + +for i in new_order + local data = [] + push!(noise_free_dataset, ordered_dataset[i]) + push!(lorenz_parameters, ordered_parameters[i]) + for nfd in ordered_dataset[i] + push!(data,nfd+randn(rng,3)) + end + push!(dataset, data) +end + +trainset = dataset[1:60] +validset = dataset[61:80] +testset = dataset[81:end] + +noise_free_trainset = noise_free_dataset[1:60] +noise_free_validset = noise_free_dataset[61:80] +noise_free_testset = noise_free_dataset[81:end] +; +``` + + + +### Data visualization + +```julia +one_nonoise=noise_free_trainset[1] +one=trainset[1] +gx, gy, gz = zeros(100), zeros(100), zeros(100) +rx, ry, rz = zeros(100), zeros(100), zeros(100) +for i=1:100 + rx[i], ry[i], rz[i] = one[i][1], one[i][2], one[i][3] + gx[i], gy[i], gz[i] = one_nonoise[i][1], one_nonoise[i][2], one_nonoise[i][3] +end +p1=plot(rx,ry,label="Noise observations") +p1=plot!(gx,gy,label="True state") +xlabel!("x") +ylabel!("y") +p2=plot(rx,rz,label="Noise observations") +p2=plot!(gx,gz,label="True state") +xlabel!("x") +ylabel!("z") +p3=plot(ry,rz,label="Noise observations") +p3=plot!(gy,gz,label="True state") +xlabel!("y") +ylabel!("z") +plot(p1, p2, p3, size = (800, 200),layout=(1,3)) +``` + +![](../../assets/examples/Global Parameter Optimisation_22_1.png) + + +### Inference + + +We use the following state-space model representation: + +$$\begin{aligned} +x_k \sim p(x_k | x_{k-1}) \\ +y_k \sim p(y_k | x_k). +\end{aligned}\]

where $x_k \sim p(x_k | x_{k-1})$ represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system.

\[\begin{aligned} +A_{k-1}=NN(y_{k-1}) \\ +p(x_k | x_{k-1})=\mathcal{N}(x_k | A_{k-1}x_{k-1}, Q) \\ +p(y_k | x_k)=\mathcal{N}(y_k | Bx_k, R) +\end{aligned}\]

where $NN$ is the neural network. The input is the observation $y_{k-1}$, and output is the trasition matrix $A_{k-1}$. $B$ denote distortion or measurment matrix. $Q$ and $R$ are covariance matrices. Note that the hidden state $x_k$ comprises three coordinates, i.e. $x_k = (rx_k, ry_k, rz_k)$

By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.

# Neural Network model
+mutable struct NN
+    InputLayer
+    OutputLater
+    g
+    params
+    function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+        InputLayer = Dense(W1, b1, relu)
+        Lstm = LSTM(W2_1,W2_2,b2,s2_1)
+        OutputLayer = Dense(W3, b3)
+        g = Chain(InputLayer, OutputLayer);
+        new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))
+    end
+end

Model specification

Note that we treat the trasition matrix $A_{k-1}$ as time-varying.

#State Space Model
+@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior_mean = zeros(3)
+    x_prior_cov  = Matrix(Diagonal(ones(3)))
+    
+    x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)
+    y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }
+    
+    for i in 2:n
+        x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }
+        y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }
+    end
+    
+    return x, y
+end

We set distortion matrix $B$ and the covariance matrices $Q$ and $R$ as identity matrix.

Q = Matrix(Diagonal(ones(3)))*2
+B = Matrix(Diagonal(ones(3)))
+R = Matrix(Diagonal(ones(3)))
+;

We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix $A$ output by the neural network. And the $A$ is treated as a datavar in the inference function.

function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    n = length(data)
+    neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])
+    return As
+end
get_matrix_AS (generic function with 1 method)

The weights of neural network $NN$ are initialized as follows:

# Initial model parameters
+W1, b1 = randn(5, 3)./100, randn(5)./100
+W2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)
+W3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100
+;

Before network training, we show the inference results for the hidden states:

# Performance on an instance from the testset before training
+index = 1
+data=testset[index]
+n=length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300))

Training network

In this part, we use the Free Energy as the objective function to optimize the weights of network.

# free energy objective to be optimized during training
+function fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    fe_ = 0
+    for train_instance in trainset
+        result = infer(
+            model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+            data  = (y = train_instance, ), 
+            returnvars = (x = KeepLast(), ),
+            free_energy = true
+        )
+        fe_ += result.free_energy[end]
+    end
+    return fe_
+end
fe_tot_est (generic function with 1 method)

Training

# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights
+# Uncomment the following code to train the network manually
+# opt = Flux.Optimise.RMSProp(0.006, 0.95)
+# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+# @showprogress for epoch in 1:800
+#     grads = ReverseDiff.gradient(fe_tot_est, params);
+#     for i=1:length(params)
+#         Flux.Optimise.update!(opt,params[i],grads[i])
+#     end
+# end

Test

Import the weights of neural network that we have trained.

W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load("../data/nn_prediction/weights.jld")["data"];
# Performance on an instance from the testset after training
+index = 1
+data = testset[index]
+n = length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+
+gx, gy, gz = zeros(100), zeros(100), zeros(100)
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+plot(p1, p2, p3, size = (1000, 300))

Prediction

In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill $k$ and estimate the future state at time $k+1$, $k+2$, $\dots$,$k+T$.

We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.

\[\begin{aligned} +A_{k}=NN(x_{k}) \\ +p(x_{k+1} | x_{k})=\mathcal{N}(x_{k+1} | A_{k}x_{k}, Q) \\ +\end{aligned}\]

#Define the prediction function
+multiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))
+sumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)
+
+function runForward(A,B,Q,R,mh_old,Vh_old)
+    mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)
+    mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)
+end
+
+function g_predict(mh_old,Vh_old,Q)
+    neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)
+    # Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])
+    As = As[1]
+    return runForward(As,B,Q,R,mh_old,Vh_old), As
+end
g_predict (generic function with 1 method)

After $k=75$, the observations are not available, and we predict the future state from $k=76$ to the end

tt = 75
+mh = mean(x_est[tt])
+Vh = cov(x_est[tt])
+mo_list, Vo_list, A_list = [], [], [] 
+inv_Q = inv(Q)
+for t=1:100-tt
+    (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)
+    push!(mo_list, mo)
+    push!(Vo_list, Vh)
+    push!(A_list, A_t)
+    global mh = mo
+    global Vh = Vo
+end
# Prediction visualization
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+for i=1:tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+for i=tt+1:100
+    ii=i-tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]
+end
+p1 = plot(rx,label="Ground truth rx")
+p1 = plot!(rx_est_m,label="Inffered state rx",ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Ground truth ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index][1:tt], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Ground truth rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)

diff --git a/v2.16.0/examples/advanced_examples/Infinite Data Stream/index.html b/v2.16.0/examples/advanced_examples/Infinite Data Stream/index.html new file mode 100644 index 000000000..183b90b67 --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Infinite Data Stream/index.html @@ -0,0 +1,169 @@ + +Infinite Data Stream · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Infinite Data Stream

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:

using RxInfer, Plots, Random, StableRNGs

For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:

mutable struct Environment
+    rng                   :: AbstractRNG
+    current_state         :: Float64
+    observation_precision :: Float64
+    history               :: Vector{Float64}
+    observations          :: Vector{Float64}
+    
+    Environment(current_state, observation_precision; seed = 123) = begin 
+         return new(StableRNG(seed), current_state, observation_precision, [], [])
+    end
+end
+
+function getnext!(environment::Environment)
+    environment.current_state = environment.current_state + 1.0
+    nextstate  = 10sin(0.1 * environment.current_state)
+    observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))
+    push!(environment.history, nextstate)
+    push!(environment.observations, observation)
+    return observation
+end
+
+function gethistory(environment::Environment)
+    return environment.history
+end
+
+function getobservations(environment::Environment)
+    return environment.observations
+end
getobservations (generic function with 1 method)

Model specification

We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:

@model function kalman_filter()
+    
+    # Prior for the previous state
+    x_prev_mean = datavar(Float64)
+    x_prev_var  = datavar(Float64)
+    
+    x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)
+    
+    # Prior for the observation noise
+    τ_shape = datavar(Float64)
+    τ_rate  = datavar(Float64)
+    
+    τ ~ Gamma(shape = τ_shape, rate = τ_rate)
+    
+    # Random walk with fixed precision
+    x_current ~ Normal(mean = x_prev, precision = 1.0)
+    
+    # Noisy observation
+    y = datavar(Float64)
+    y ~ Normal(mean = x_current, precision = τ)
+    
+end
+
+# We assume the following factorisation between variables 
+# in the variational distribution
+@constraints function filter_constraints()
+    q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)
+end
filter_constraints (generic function with 1 method)

Prepare environment

initial_state         = 0.0
+observation_precision = 0.1
0.1

After we have created the environment we can observe how our signal behaves:

testenvironment = Environment(initial_state, observation_precision);
+
+animation = @animate for i in 1:100
+    getnext!(testenvironment)
+    
+    history = gethistory(testenvironment)
+    observations = getobservations(testenvironment)
+    
+    p = plot(size = (1000, 300))
+    
+    p = plot!(p, 1:i, history[1:i], label = "Hidden signal")
+    p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = "Observation")
+end
+
+gif(animation, "../pics/infinite-data-stream.gif", fps = 24, show_msg = false);

Filtering on static dataset

RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:

n                  = 300
+static_environment = Environment(initial_state, observation_precision);
+
+for i in 1:n
+    getnext!(static_environment)
+end
+
+static_history      = gethistory(static_environment)
+static_observations = getobservations(static_environment);
+static_datastream   = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
function run_static(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        keephistory   = 10_000,
+        historyvars   = (x_current = KeepLast(), τ = KeepLast()),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        free_energy   = true,
+        autostart     = true,
+    )
+    
+    return engine
+end
run_static (generic function with 1 method)
result = run_static(static_environment, static_datastream);
static_inference = @animate for i in 1:n
+    estimated = result.history[:x_current]
+    p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = "Estimation")
+    p = plot!(static_history[1:i], label = "Real states")    
+    p = scatter!(static_observations[1:i], ms = 2, label = "Observations")
+    p = plot(p, size = (1000, 300), legend = :bottomright)
+end
+
+gif(static_inference, "../pics/infinite-data-stream-inference.gif", fps = 24, show_msg = false);

plot(result.free_energy_history, label = "Bethe Free Energy (averaged)")

Filtering on realtime dataset

Next lets create a "real" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:

function run_and_plot(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    posteriors = []
+    
+    plotfn = (q_current) -> begin 
+        IJulia.clear_output(true)
+        
+        push!(posteriors, q_current)
+
+        p = plot(mean.(posteriors), ribbon = var.(posteriors), label = "Estimation")
+        p = plot!(gethistory(environment), label = "Real states")    
+        p = scatter!(getobservations(environment), ms = 2, label = "Observations")
+        p = plot(p, size = (1000, 300), legend = :bottomright)
+
+        display(p)
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        autostart     = false,
+    )
+    
+    qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)
+    
+    RxInfer.start(engine)
+    
+    return engine
+end
run_and_plot (generic function with 1 method)
# This example runs in our documentation pipeline, which does not support "real-time" execution context
+# We skip this code if run not in Jupyter notebook (see below an example with gif)
+engine = nothing 
+if isdefined(Main, :IJulia)
+    timegen      = 41 # 41 ms
+    environment  = Environment(initial_state, observation_precision);
+    observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations
+    datastream   = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
+    engine = run_and_plot(environment, datastream)
+end;

The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:

if !isnothing(engine) && isdefined(Main, :IJulia)
+    RxInfer.stop(engine)
+    IJulia.clear_output(true)
+end;
diff --git a/v2.16.0/examples/advanced_examples/Nonlinear Sensor Fusion/index.html b/v2.16.0/examples/advanced_examples/Nonlinear Sensor Fusion/index.html new file mode 100644 index 000000000..2b34c9368 --- /dev/null +++ b/v2.16.0/examples/advanced_examples/Nonlinear Sensor Fusion/index.html @@ -0,0 +1,140 @@ + +Nonlinear Sensor Fusion · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Nonlinear Sensor Fusion

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers
+using DataFrames, DelimitedFiles, StableRNGs

In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.

A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.

To illustrate these noisy measurements, the engineers decided to plot them:

# fetch measurements
+beacon_locations = readdlm("../data/sensor_fusion/beacons.txt")
+distances = readdlm("../data/sensor_fusion/distances.txt")
+position = readdlm("../data/sensor_fusion/position.txt")
+nr_observations = size(distances, 1);
# plot beacon and actual location of WALL-E
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+xlabel!("longitude [m]"), ylabel!("latitude [m]")
+
+# plot noisy distance measurements
+p2 = plot(distances, legend=:topleft, linewidth=3, label=["distance to beacon 1" "distance to beacon 2" "distance to beacon 3"])
+xlabel!("time [sec]"), ylabel!("distance [m]")
+
+plot(p1, p2, size=(1200, 500))

In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time $t$, denoted by $z_t$, follows a 2-dimensional normal random walk:

\[\begin{aligned} + & p(z_t \mid z_{t - 1}) = \mathcal{N}(z_t \mid z_{t-1},~\mathrm{I}_{2}),\\ +\end{aligned}\]

where $\mathrm{I}_2$ denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements $y_t$ as a noisy set of the distances between WALL-E and the beacons, specified by $s_i$:

\[\begin{aligned} + & p(y_t \mid z_t) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~\mathrm{I}_{3}\! \right . \right)\!. +\end{aligned}\]

The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:

# function to compute distance to beacons
+function compute_distances(z)    
+    distance1 = norm(z - beacon_locations[1,:])
+    distance2 = norm(z - beacon_locations[2,:])
+    distance3 = norm(z - beacon_locations[3,:])
+    distances = [distance1, distance2, distance3]
+end;
@model function random_walk_model(nr_observations)
+    
+    # specify precision matrices
+    W = diageye(2)
+    R = diageye(3)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], W)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;

Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.

Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:

    compute_distances(z) -> CVI(..., Val(false), ...)

This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.

@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)
+    compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)
+end;

NOTE: You can try out different meta for approximating the nonlinearity, e.g.

@meta function random_walk_linear_meta()
+    compute_distances(z) -> Linearization()
+end;
@meta function random_walk_unscented_meta()
+    compute_distances(z) -> Unscented()
+end;
results_fast = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),
+);
results_accuracy = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1000, 100, StableRNG(42)),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),
+);

After running this fast inference procedure, the engineers plot the results and evaluate the performance:

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_fast.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Fast (1 sample, 3 iterations)"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot beacon and actual and estimated location of WALL-E (accurate inference)
+p2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_accuracy.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Accurate (1000 samples, 100 iterations)"); p2.series_list[end][:label] = "estimated location ±2σ"
+
+plot(p1, p2, size=(1200, 500))

The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, $Q$ and $R$ respectively. They did this by adding Wishart priors to those matrices:

\[\begin{aligned} + & p(Q) = \mathcal{W}(Q \mid 3, \mathrm{I}_2), \\ + & p(R) = \mathcal{W}(R \mid 4, \mathrm{I}_3), \\ + & p(z_t \mid z_{t - 1}, Q) = \mathcal{N}(z_t \mid z_{t-1}, Q^{-1}),\\ + & p(y_t \mid z_t, R) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~R^{-1}\! \right . \right)\!. +\end{aligned}\]

@model function random_walk_model_wishart(nr_observations)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # set priors on precision matrices
+    Q ~ Wishart(3, diageye(2))
+    R ~ Wishart(4, diageye(3))
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], Q)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;
meta = @meta begin 
+    compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)
+end;

Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:

constraints = @constraints begin
+    q(z, Q, R) = q(z)q(Q)q(R)
+end;

The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.

results_wishart = infer(
+    model = random_walk_model_wishart(nr_observations),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = constraints,
+    meta = meta,
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),
+    initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))
+);

They plot the new estimates and the performance over time, and luckily WALL-E is found!

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_wishart.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot bethe free energy performance
+p2 = plot(results_wishart.free_energy, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size=(1200, 500))

diff --git a/v2.16.0/examples/advanced_examples/overview/index.html b/v2.16.0/examples/advanced_examples/overview/index.html new file mode 100644 index 000000000..ce03ea0de --- /dev/null +++ b/v2.16.0/examples/advanced_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Advanced examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Advanced examples contain more complex inference problems.

  • Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.
  • Advanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.
  • Assessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.
  • Chance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.
  • Conjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.
  • Global Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.
  • Solve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.
  • Infinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.
  • Nonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors
diff --git a/v2.16.0/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html b/v2.16.0/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html new file mode 100644 index 000000000..44046c6f3 --- /dev/null +++ b/v2.16.0/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html @@ -0,0 +1,550 @@ + +Bayesian Linear Regression Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Bayesian Linear Regression Tutorial

This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM

Part 1. Bayesian Linear Regression

John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

He records the speed and fuel consumption for the urban road which is the xdata and ydata.

function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = infer(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (a, b)
+  Free Energy:     | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184
+.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821
+, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]

He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a\mid y)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0,Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b)", c=1, legend = :topleft)
+prb = vline!(prb, [ 25 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b\mid y)", c=2, legend = :topleft)
+psb = vline!(psb, [ 25 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

a = results.posteriors[:a]
+b = results.posteriors[:b]
+
+println("Real a: ", 0.5, " | Estimated a: ", mean_var(a), " | Error: ", abs(mean(a) - 0.5))
+println("Real b: ", 25.0, " | Estimated b: ", mean_var(b), " | Error: ", abs(mean(b) - 25.0))
Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err
+or: 0.001490188462705988
+Real b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error
+: 0.18735789804394898

Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:

# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Univariate regression with unknown noise

Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. $\begin{aligned} p(y_n \mid a, b, s) &= \mathcal{N}(y_n \mid ax_n + b, s)\\ +p(s) &= \mathcal{IG}(s\mid\alpha, \theta)\\ +p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ +p(b) &= \mathcal{N}(b \mid m_b, v_b) \end{aligned}$

@model function linear_regression_unknown_noise(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    s ~ InverseGamma(1.0, 1.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = s)
+end
x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)
+
+scatter(x_data_un, y_data_un, title = "Dateset with unknown noise (mountain road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results_unknown_noise = infer(
+    model           = linear_regression_unknown_noise(length(x_data_un)), 
+    data            = (y = y_data_un, x = x_data_un), 
+    initmessages    = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars      = (a = KeepLast(), b = KeepLast(), s = KeepLast()), 
+    iterations      = 20,
+    constraints     = MeanField(),
+    initmarginals   = (s = vague(InverseGamma), ),
+    free_energy     = true
+)
Inference results:
+  Posteriors       | available for (a, b, s)
+  Free Energy:     | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125
+.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56
+, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]

Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:

plot(results_unknown_noise.free_energy, title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Below he visualizes the obtained posterior distributions for parameters:

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(a)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0, Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(b)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 25.0 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(b)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 25.0 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L"Prior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(s)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 200 ], label=L"True $s$", c = 3)
+psb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L"Posterior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(s)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 200 ], label=L"True $s$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$s$", ylabel=L"$p(s)$", ylims=[0, Inf])

He sees that in the presence of more noise the inference result is more uncertain about the actual values for $a$ and $b$ parameters.

John samples $a$ and $b$ and plot many possible regression lines on the same plot:

as = rand(results_unknown_noise.posteriors[:a], 100)
+bs = rand(results_unknown_noise.posteriors[:b], 100)
+p = scatter(x_data_un, y_data_un, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)
+end
+
+plot(p, size = (900, 400))

From this plot John can see that many lines do fit the data well and there is no definite "best" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.

Multivariate linear regression

In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.

@model function linear_regression_multivariate(dim, nr_samples)
+    a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))
+    b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))
+    W ~ InverseWishart(dim + 2, 100 * diageye(dim))
+
+    # Here is a small trick to make the example work
+    # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`
+    x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)
+    y = datavar(Vector{Float64}, nr_samples)
+    z = randomvar(nr_samples)
+
+    z .~ x .* a .+ b
+    y .~ MvNormal(mean = z, covariance = W)
+
+end

After received all the measurement records, he plots the measurements and performance index:

dim_mv = 6
+nr_samples_mv = 50
+rng_mv = StableRNG(42)
+a_mv = randn(rng_mv, dim_mv)
+b_mv = 10 * randn(rng_mv, dim_mv)
+v_mv = 100 * rand(rng_mv, dim_mv)
+
+x_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));
p = plot(title = "Multivariate linear regression", legend = :topleft)
+
+plt = palette(:tab10)
+
+data_set_label = [""]
+
+for k in 1:dim_mv
+    global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = "Measurement #$k", ms = 2, color = plt[k])
+end
+xlabel!(L"$x$")
+ylabel!(L"$y$")
+p

Before this data can be used to perform inference, John needs to change its format slightly.

x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)
+y_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);
results_mv = infer(
+    model           = linear_regression_multivariate(dim_mv, nr_samples_mv),
+    data            = (y = y_data_mv_processed, x = x_data_mv_processed),
+    initmarginals   = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),
+    initmessages    = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),
+    returnvars      = (a = KeepLast(), b = KeepLast(), W = KeepLast()),
+    free_energy     = true,
+    iterations      = 50,
+    constraints     = MeanField()
+)
Inference results:
+  Posteriors       | available for (a, b, W)
+  Free Energy:     | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7
+22, 712.341, 700.865, 690.782, 682.505  …  664.434, 664.434, 664.434, 664.4
+34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]

Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.

p = plot(title = "Multivariate linear regression", legend = :topleft, xlabel=L"$x$", ylabel=L"$y$")
+
+# how many lines to plot
+r = 50
+
+i_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))
+i_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))
+
+plt = palette(:tab10)
+
+for k in 1:dim_mv
+    x_mv_k = x_data_mv[k]
+    y_mv_k = y_data_mv[k]
+
+    for i in 1:r
+        global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])
+    end
+
+    global p = scatter!(p, x_mv_k, y_mv_k, label = "Measurement #$k", ms = 2, color = plt[k])
+end
+
+# truncate the init step
+f = plot(results_mv.free_energy[2:end], title ="Bethe free energy convergence", label = nothing, xlabel = "Iteration", ylabel = "Bethe free energy [nats]") 
+
+plot(p, f, size = (1000, 400))

He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.

i_a_mv = results_mv.posteriors[:a]
+
+ps_a = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $a_{%$k}$", xlabel=L"$a_{%$k}$", ylabel=L"$p(a_{%$k})$", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])
+
+    local m_a_mv_k = mean(i_a_mv)[k]
+    local v_a_mv_k = std(i_a_mv)[k, k]
+    
+    _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(a_{%$k})$", c=2,)
+    _p = vline!(_p, [ a_mv[k] ], label=L"True $a_{%$k}$", c = 3)
+           
+    push!(ps_a, _p)
+end
+
+plot(ps_a...)

i_b_mv = results_mv.posteriors[:b]
+
+ps_b = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $b_{%$k}$", xlabel=L"$b_{%$k}$", ylabel=L"$p(b_{%$k})$", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])
+    local m_b_mv_k = mean(i_b_mv)[k]
+    local v_b_mv_k = std(i_b_mv)[k, k]
+
+    _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(b_{%$k})$", c=2,)
+    _p = vline!(_p, [ b_mv[k] ], label=L"Real $b_{%$k}$", c = 3)
+           
+    push!(ps_b, _p)
+end
+
+plot(ps_b...)

He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.

scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L"True $s_d$")
+scatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L"$\mathrm{E}[s_d] \pm \sigma$")
+plot!(; xlabel=L"Dimension $d$", ylabel="Variance", title="Estimated variance of the noise")

Part 2. Hierarchical Bayesian Linear Regression

Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro.

The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.

Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].

The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.

# https://www.machinelearningplus.com/linear-regression-in-julia/
+# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb

Understanding the Task

Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.

In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).

Now, let's explore the data and delve deeper into the problem involved.

dataset = CSV.read("../data/hbr/osic_pulmonary_fibrosis.csv", DataFrame);
describe(dataset)
7×7 DataFrame
+ Row │ variable       mean     min                        median   max     
+    ⋯
+     │ Symbol         Union…   Any                        Union…   Any     
+    ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ Patient                 ID00007637202177411956430           ID004266
+372 ⋯
+   2 │ Weeks          31.8618  -5                         28.0     133
+   3 │ FVC            2690.48  827                        2641.0   6399
+   4 │ Percent        77.6727  28.8776                    75.6769  153.145
+   5 │ Age            67.1885  49                         68.0     88      
+    ⋯
+   6 │ Sex                     Female                              Male
+   7 │ SmokingStatus           Currently smokes                    Never sm
+oke
+                                                               3 columns om
+itted
first(dataset, 5)
5×7 DataFrame
+ Row │ Patient                    Weeks  FVC    Percent  Age    Sex      Sm
+oki ⋯
+     │ String31                   Int64  Int64  Float64  Int64  String7  St
+rin ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ ID00007637202177411956430     -4   2315  58.2536     79  Male     Ex
+-sm ⋯
+   2 │ ID00007637202177411956430      5   2214  55.7121     79  Male     Ex
+-sm
+   3 │ ID00007637202177411956430      7   2061  51.8621     79  Male     Ex
+-sm
+   4 │ ID00007637202177411956430      9   2144  53.9507     79  Male     Ex
+-sm
+   5 │ ID00007637202177411956430     11   2069  52.0634     79  Male     Ex
+-sm ⋯
+                                                                1 column om
+itted

The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.

Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:

patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)
patientinfo (generic function with 1 method)
function patientchart(dataset, patient_id; line_kws = true)
+    info = patientinfo(dataset, patient_id)
+    x = info[!, "Weeks"]
+    y = info[!, "FVC"]
+
+    p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)
+    p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = "Weeks", ylabel = "FVC")
+    
+    if line_kws
+        # Use the `GLM.jl` package to estimate linear regression
+        linearFormulae = @formula(FVC ~ Weeks)
+        linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))
+        linearPredicted = predict(linearRegressor)
+        p = plot!(p, x, linearPredicted, color = :red, lw = 3)
+    end
+
+    return p
+end
patientchart (generic function with 1 method)
p1 = patientchart(dataset, "ID00007637202177411956430")
+p2 = patientchart(dataset, "ID00009637202177434476278")
+p3 = patientchart(dataset, "ID00010637202177584971671")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.

Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:

The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].

Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling

In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the "pooled model." On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the "unpooled model," where each patient has completely separate regression lines.

In this analysis, we will adopt a middle ground approach known as "Partial pooling." Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:

Mathematically, the model is described by the following equations:

\[\begin{equation} + \begin{aligned} + \mu_\alpha &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 250000.0) \\ + \sigma_\alpha &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mu_\beta &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 9.0) \\ + \sigma_\beta &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 1.36) \\ + \alpha_i &\sim \mathcal{N}(\mathrm{mean} = \mu_\alpha, \mathrm{precision} = \sigma_\alpha) \\ + \beta &\sim \mathcal{N}(\mathrm{mean} = \mu_\beta, \mathrm{precision} = \sigma_\beta) \\ + \sigma &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mathrm{FVC}_{ij} &\sim \mathcal{N}(\mathrm{mean} = \alpha_i + t \beta_i, \mathrm{precision} = \sigma) + \end{aligned} +\end{equation}\]

where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!

Implementing this model in RxInfer is pretty straightforward:

@model function partially_pooled(patient_codes, weeks)
+    μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β ~ Normal(mean = 0.0, var = 9.0)      # Prior for the mean of β (slope)
+    σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)
+    σ_β ~ Gamma(shape = 1.75, scale = 1.36)  # Prior for the precision of β (slope)
+
+    n_codes = length(patient_codes)            # Total number of data points
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    α = randomvar(n_patients)                # Individual intercepts for each patient
+    β = randomvar(n_patients)                # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution
+        β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54)   # Prior for the standard deviation of the error term
+    
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes) # Observed FVC measurements
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+end

Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.

@constraints function partially_pooled_constraints()
+    # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent
+    q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)
+    # Assume that `μ_α`, `σ_α`, `α` are jointly independent
+    q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)
+    # Assume that `μ_β`, `σ_β`, `β` are jointly independent
+    q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)
+    # Assume that `FVC_est`, `σ` are jointly independent
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_constraints (generic function with 1 method)

These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!

Inference in the model

A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.

Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.

patient_ids          = dataset[!, "Patient"] # get the column of all patients
+patient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));
+patient_code_column  = map(patient -> patient_code_encoder[patient], patient_ids)
+
+dataset[!, :PatientCode] = patient_code_column
+
+first(patient_code_encoder, 5)
5-element Vector{Pair{InlineStrings.String31, Int64}}:
+ "ID00197637202246865691526" => 85
+ "ID00388637202301028491611" => 160
+ "ID00341637202287410878488" => 142
+ "ID00020637202178344345685" => 9
+ "ID00305637202281772703145" => 127
function partially_pooled_inference(dataset)
+
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+
+    results = infer(
+        model = partially_pooled(patient_codes, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+            σ = vague(Gamma),
+            σ_α = vague(Gamma),
+            σ_β = vague(Gamma),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100
+    )
+    
+end
partially_pooled_inference (generic function with 1 method)

We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.

In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. 

partially_pooled_inference_results = partially_pooled_inference(dataset)
Inference results:
+  Posteriors       | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)

Checking the model

Inspecting the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)
+    local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))
+end

Looks like our model learned personalized alphas and betas for each patient!

Visualizing FVC decline curves for some patients

Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.

function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)
+    info            = patientinfo(dataset, patient_id)
+    patient_code_id = encoder[patient_id]
+
+    patient_α = results.posteriors[:α][patient_code_id]
+    patient_β = results.posteriors[:β][patient_code_id]
+
+    estimated_σ = inv(mean(results.posteriors[:σ]))
+    
+    predict_weeks = range(-12, 134)
+
+    predicted = map(predict_weeks) do week
+        pm = mean(patient_α) + mean(patient_β) * week
+        pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ
+        return pm, sqrt(pv)
+    end
+    
+    p = patientchart(dataset, patient_id; kwargs...)
+    
+    return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)
+end
patientchart_bayesian (generic function with 1 method)
p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430")
+p2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278")
+p3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

The results match our expectations perfectly! Let's highlight the observations:

  • The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.

  • The model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.

  • Additionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.

Computing the modified Laplace Log Likelihood and RMSE

As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.

To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:

\[\begin{equation} + \begin{aligned} + \sigma_{\mathrm{clipped}} &= \max(\sigma, 70) \\ + \delta &= \min(\vert \mathrm{FVC}_{\mathrm{true}} - \mathrm{FVC}_{\mathrm{pred}}\vert, 1000) \\ + \mathrm{metric} &= -\frac{\sqrt{2}\delta}{\sigma_{\mathrm{clipped}}} - \mathrm{ln}(\sqrt{2}\sigma_{\mathrm{clipped}}) \\ + \end{aligned} +\end{equation}\]

To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.

function FVC_predict(results)
+    return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s
+        return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)
+    end
+end
FVC_predict (generic function with 1 method)
function compute_rmse(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    return mean((dataset[!, "FVC"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)
+end
+
+function compute_laplace_log_likelihood(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    sigma_c = std.(FVC_predicted)
+    sigma_c[sigma_c .< 70] .= 70
+    delta = abs.(mean.(FVC_predicted) .- dataset[!, "FVC"])
+    delta[delta .> 1000] .= 1000
+    return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))
+end
compute_laplace_log_likelihood (generic function with 1 method)
println("RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))")
RMSE: 124.0313266260767
+Laplace Log Likelihood: -6.15689374755478

What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!

Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.

Add layer to model hierarchy: Smoking Status

We can enhance the model by incorporating the column "SmokingStatus" as a pooling level, where model parameters will be partially pooled within the groups "Never smoked," "Ex-smoker," and "Currently smokes." To achieve this, we need to:

Encode the "SmokingStatus" column. Map the patient encoding to the corresponding "SmokingStatus" encodings. Refine and retrain the model with the additional hierarchical structure.

combine(groupby(dataset, "SmokingStatus"), nrow)
3×2 DataFrame
+ Row │ SmokingStatus     nrow
+     │ String31          Int64
+─────┼─────────────────────────
+   1 │ Ex-smoker          1038
+   2 │ Never smoked        429
+   3 │ Currently smokes     82
smoking_id_mapping   = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, "SmokingStatus"]))))
+smoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id
+    smoking_status = first(unique(patientinfo(dataset, patient_id)[!, "SmokingStatus"]))
+    return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]
+end)
+
+smoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));
@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)
+    μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)
+    σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+    σ_β_global ~ Gamma(shape = 1.75, scale = 1.36)  # Corresponds to half-normal with scale 3.0
+
+    n_codes = length(patient_codes) # Total number of data points
+    n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern
+    μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern
+    
+    for i in 1:n_smoking_statuses
+        μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)
+        μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)
+    end
+    
+    α = randomvar(n_patients) # Individual intercepts for each patient
+    β = randomvar(n_patients) # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)
+        β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes)
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+    
+end
+
+@constraints function partially_pooled_with_smooking_constraints()
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)
+    q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)
+    q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)
+    q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_with_smooking_constraints (generic function with 1 method)
function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+    
+    return infer(
+        model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_with_smooking_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            σ = Gamma(1.75, 45.54),
+            σ_α_global = Gamma(1.75, 45.54),
+            σ_β_global = Gamma(1.75, 1.36),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100,
+    )
+end
partially_pooled_with_smoking (generic function with 2 methods)
partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);

Inspect the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)
+    local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)
+    local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])
+    local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α_global)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β_global)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    local p5 = plot(title = "q(μ_α_smoking_status)...", legend = false)
+    local p6 = plot(title = "q(μ_β_smoking_status)...", legend = false)
+    
+    foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) 
+    foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)
+    
+    plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))
+end

Interpret smoking status model parameters

The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.

smoking_id_mapping
Dict{InlineStrings.String31, Int64} with 3 entries:
+  "Currently smokes" => 3
+  "Ex-smoker"        => 1
+  "Never smoked"     => 2
posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]
+
+println("Trend for")
+foreach(pairs(smoking_id_mapping)) do (key, id)
+    println("  $key: $(mean(posteriors_μ_β_smoking_status[id]))")
+end
Trend for
+  Currently smokes: 1.8157457671008241
+  Ex-smoker: -4.56516461765951
+  Never smoked: -4.446729680170274

Let's look at these curves for individual patients to help interpret these model results.

# Never smoked
+p1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430") 
+# Ex-smoker
+p2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278") 
+# Currently smokes
+p3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184") 
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

Review patients that currently smoke

When plotting each patient with the smoking status "Currently smokes," we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.

Depending on the purpose of the model, we can proceed in different ways:

  • If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.

  • However, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the "Currently smokes" group's parameters closer to the global parameters, or even consider merging the group with "Ex-smokers." Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.

let 
+    local plots = []
+
+    for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==("Currently smokes"), dataset)[!, "Patient"]))
+        push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))
+    end
+
+    plot(plots..., size = (1200, 1200))
+end

Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level

We calculate the metrics for the updated model and compare to the original model.

println("RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))")
RMSE: 124.7845980866563
+Laplace Log Likelihood: -6.165346437287973

Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.

References

[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541

[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.

diff --git a/v2.16.0/examples/basic_examples/Coin Toss Model/index.html b/v2.16.0/examples/basic_examples/Coin Toss Model/index.html new file mode 100644 index 000000000..f310b4487 --- /dev/null +++ b/v2.16.0/examples/basic_examples/Coin Toss Model/index.html @@ -0,0 +1,42 @@ + +Coin toss model (Beta-Bernoulli) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Coin toss model (Beta-Bernoulli)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example, we are going to perform an exact inference for a coin toss model that can be represented as:

\[\begin{aligned} +p(\theta) &= \mathrm{Beta}(\theta|a, b),\\ +p(y_i|\theta) &= \mathrm{Ber}(y_i|\theta),\\ +\end{aligned}\]

where $y_i \in \{0, 1\}$ is a binary observation induced by Bernoulli likelihood while $\theta$ is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of $\theta$.

We start with importing all needed packages:

using RxInfer, Random

Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:

rng = MersenneTwister(42)
+n = 500
+θ_real = 0.75
+distribution = Bernoulli(θ_real)
+
+dataset = float.(rand(rng, Bernoulli(θ_real), n));
# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(4.0, 8.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+end
result = infer(
+    model = coin_model(length(dataset)), 
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
θestimated = result.posteriors[:θ]
Beta{Float64}(α=365.0, β=147.0)
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+plot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+vline!([θ_real], label="Real θ")

diff --git a/v2.16.0/examples/basic_examples/Hidden Markov Model/index.html b/v2.16.0/examples/basic_examples/Hidden Markov Model/index.html new file mode 100644 index 000000000..591fd7409 --- /dev/null +++ b/v2.16.0/examples/basic_examples/Hidden Markov Model/index.html @@ -0,0 +1,132 @@ + +How to train your Hidden Markov Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

How to train your Hidden Markov Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate()
+;

In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment.

First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time $t$, let's call the estimate of the Roomba's position $s_t$.

However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call $A$.

Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.

At time $t$, we will call our observations $x_t$ and encode the mapping from the Roomba's position to the observations in a matrix we call $B$. $B$ also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:

\[\begin{aligned} + s_t & \sim \mathcal{C}at(A s_{t-1}),\\ + x_t & \sim \mathcal{C}at(B s_t).\\ +\end{aligned}\]

This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices $A$ and $B$ so we can use them to track the whereabouts of our little cleaning agent.

using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots

In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).

To generate our observation data, we'll follow these steps:

  1. Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.
  2. Determine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.
  3. Determine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.
  4. Repeat steps 2-3 for as many samples as we want.

The following code implements this process and generates our observation data:

"""
+    rand_vec(rng, distribution::Categorical)
+
+This function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.
+"""
+function rand_vec(rng, distribution::Categorical) 
+    k = ncategories(distribution)
+    s = zeros(k)
+    drawn_category = rand(rng, distribution)
+    s[drawn_category] = 1.0
+    return s
+end
+
+function generate_data(n_samples; seed = 42)
+    
+    rng = MersenneTwister(seed)
+    
+    # Transition probabilities 
+    state_transition_matrix = [0.9 0.0 0.1;
+                                                        0.0 0.9 0.1; 
+                                                        0.05 0.05 0.9] 
+    # Observation noise
+    observation_distribution_matrix = [0.9 0.05 0.05;
+                                                                         0.05 0.9 0.05;
+                                                                         0.05 0.05 0.9] 
+    # Initial state
+    s_initial = [1.0, 0.0, 0.0] 
+    
+    states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states
+    observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations
+    
+    s_prev = s_initial
+    
+    for t = 1:n_samples
+        s_probvec = state_transition_matrix * s_prev
+        states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))
+        obs_probvec = observation_distribution_matrix * states[t]
+        observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))
+        s_prev = states[t]
+    end
+    
+    return observations, states
+end
generate_data (generic function with 1 method)

We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.

# Test data
+N = 100
+x_data, s_data = generate_data(N);
+
+scatter(argmax.(s_data), leg=false, xlabel="Time",yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]))

Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the $A$ and $B$ matrices we can use MatrixDirichlet priors. For the $A$-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on $A$ with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on $B$. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.

Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!

# Model specification
+@model function hidden_markov_model(n)
+    
+    A ~ MatrixDirichlet(ones(3,3))
+    B ~ MatrixDirichlet([ 10.0 1.0 1.0; 
+                                            1.0 10.0 1.0; 
+                                            1.0 1.0 10.0 ])
+    
+    s_0 ~ Categorical(fill(1.0 / 3.0, 3))
+    
+    s = randomvar(n)
+    x = datavar(Vector{Float64}, n)
+    
+    s_prev = s_0
+    
+    for t in 1:n
+        s[t] ~ Transition(s_prev, A) 
+        x[t] ~ Transition(s[t], B)
+        s_prev = s[t]
+    end
+    
+end
+
+# Constraints specification
+@constraints function hidden_markov_model_constraints()
+    q(s_0, s, A, B) = q(s_0, s)q(A)q(B)
+end
hidden_markov_model_constraints (generic function with 1 method)

Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?

We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.

Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!

imodel = hidden_markov_model(N)
+idata = (x = x_data,)
+
+imarginals = (
+    A = vague(MatrixDirichlet, 3, 3), 
+    B = vague(MatrixDirichlet, 3, 3), 
+    s = vague(Categorical, 3)
+)
+
+ireturnvars = (
+    A = KeepLast(),
+    B = KeepLast(),
+    s = KeepLast()
+)
+
+result = infer(
+    model         = imodel, 
+    data          = idata,
+    constraints   = hidden_markov_model_constraints(),
+    initmarginals = imarginals, 
+    returnvars    = ireturnvars, 
+    iterations    = 20, 
+    free_energy   = true
+);

That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over $A$) and about the uncertainty in the roombas observations (A good posterior over $B$). Let's see if it worked

println("Posterior Marginal for A:")
+mean(result.posteriors[:A])
Posterior Marginal for A:
+3×3 Matrix{Float64}:
+ 0.871955   0.0290008  0.0572283
+ 0.0349989  0.817591   0.135675
+ 0.0930457  0.153408   0.807097
println("Posterior Marginal for B:")
+mean(result.posteriors[:B])
Posterior Marginal for B:
+3×3 Matrix{Float64}:
+ 0.949636   0.0974741  0.0518997
+ 0.0244903  0.833632   0.0277884
+ 0.0258734  0.0688939  0.920312

Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. 

p1 = scatter(argmax.(s_data), 
+                        title="Inference results", 
+                        label = "Real", 
+                        ms = 6, 
+                        legend=:right,
+                        xlabel="Time" ,
+                        yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]),
+                        size=(900,550)
+                        )
+
+p1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),
+                        label = "Inferred",
+                        ms = 3
+                        )
+
+p2 = plot(result.free_energy, 
+                    label="Free energy",
+                    xlabel="Iteration Number"
+                    )
+
+plot(p1, p2, layout = @layout([ a; b ]))

Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.

diff --git a/v2.16.0/examples/basic_examples/Kalman filtering and smoothing/index.html b/v2.16.0/examples/basic_examples/Kalman filtering and smoothing/index.html new file mode 100644 index 000000000..05ddef8d1 --- /dev/null +++ b/v2.16.0/examples/basic_examples/Kalman filtering and smoothing/index.html @@ -0,0 +1,410 @@ + +Kalman filtering and smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Kalman filtering and smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.

We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.

We then solve an identification problem which does not have an analytical solution.

Utimately, we show how RxInfer.jl can deal with missing observations.

Gaussian Linear Dynamical System

LGSSM can be described with the following equations:

\[\begin{aligned} + p(x_i|x_{i - 1}) & = \mathcal{N}(x_i|A * x_{i - 1}, \mathcal{P}),\\ + p(y_i|x_i) & = \mathcal{N}(y_i|B * x_i, \mathcal{Q}), +\end{aligned}\]

where $x_i$ are hidden states, $y_i$ are noisy observations, $A$, $B$ are state transition and observational matrices, $\mathcal{P}$ and $\mathcal{Q}$ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, A, B, Q, P)
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(B * x[i], P))
+        x_prev = x[i]
+    end
+    
+    return x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 1234
+
+rng = MersenneTwister(1234)
+
+# We will model 2-dimensional observations with rotation matrix `A`
+# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`
+# are known and fixed for all time-steps
+θ = π / 35
+A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+B = diageye(2)
+Q = diageye(2)
+P = 25.0 .* diageye(2)
+
+# Number of observations
+n = 300;
x, y = generate_data(rng, A, B, Q, P);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.

px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+px = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)
+
+plot(px)

To create a model we use GraphPPL package and @model macro:

@model function rotate_ssm(n, x0, A, B, Q, P)
+    
+    # We create constvar references for better efficiency
+    cA = constvar(A)
+    cB = constvar(B)
+    cQ = constvar(Q)
+    cP = constvar(P)
+    
+    # `x` is a sequence of hidden states
+    x = randomvar(n)
+    # `y` is a sequence of "clamped" observations
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    x_prev = x_prior
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)
+        y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)
+        x_prev = x[i]
+    end
+
+end

To run inference we also specify prior for out first hidden state:

x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));
# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. 
+# infer(..., options = (limit_stack_depth = 500, ))`
+result = infer(
+    model = rotate_ssm(length(y), x0, A, B, Q, P), 
+    data = (y = y,),
+    free_energy = true
+);
+
+xmarginals  = result.posteriors[:x]
+logevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence
px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :teal)
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :violet)
+
+plot(px)

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:

logevidence
1-element Vector{Float64}:
+ -1882.2434870099778

We may be also interested in performance of our resulting Belief Propagation algorithm:

@benchmark infer(
+    model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), 
+    data = (y = $y,)
+)
BenchmarkTools.Trial: 140 samples with 1 evaluation.
+ Range (min … max):  27.308 ms … 79.422 ms  ┊ GC (min … max): 0.00% … 9.37%
+ Time  (median):     33.728 ms              ┊ GC (median):    0.00%
+ Time  (mean ± σ):   35.935 ms ±  7.598 ms  ┊ GC (mean ± σ):  5.40% ± 9.31%
+
+       ▄█▂▇▇                                                   
+  ▃▃▃▃███████▄▃▃▃▁▃▁▃▅▃▃▄▃▃▃▃▅▁▁▁▁▃▁▁▁▁▁▁▁▁▁▁▃▁▁▁▁▁▁▁▃▁▁▁▁▁▁▃ ▃
+  27.3 ms         Histogram: frequency by time          71 ms <
+
+ Memory estimate: 9.73 MiB, allocs estimate: 226250.

System Identification Problem

In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:

using RxInfer, Distributions, StableRNGs, Plots
function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)
+
+    rng = StableRNG(seed)
+
+    real_x = Vector{Float64}(undef, n)
+    real_w = Vector{Float64}(undef, n)
+    real_y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))
+        real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))
+        real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))
+
+        x_i_min = real_x[i]
+        w_i_min = real_w[i]
+    end
+    
+    return real_x, real_w, real_y
+end
generate_data (generic function with 2 methods)

The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.

Combination 1: y = x + w

In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:

n = 250
+real_x, real_w, real_y = generate_data(+, n);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, real_x, label = "x")
+pl = plot!(pl, real_w, label = "w")
+
+pr = plot(title = "Combined y = x + w")
+pr = scatter!(pr, real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:

@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x = randomvar(n)
+    w = randomvar(n)
+    s = randomvar(n)
+    y = datavar(Float64, n)
+    
+    x_i_min = x0
+    w_i_min = w0
+    
+    for i in 1:n
+        x[i] ~ Normal(mean = x_i_min, precision = τ_x)
+        w[i] ~ Normal(mean = w_i_min, precision = τ_w)
+        s[i] ~ f(x[i], w[i])
+        y[i] ~ Normal(mean = s[i], precision = τ_y)
+        
+        x_i_min = x[i]
+        w_i_min = w[i]
+    end
+    
+end

RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:

constraints = @constraints begin 
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y
+)
+Options:
+  warn = true

The next step is to assign priors, initialise needed messages and marginals and call the inference function:

m_x_0, τ_x_0 = -20.0, 1.0
+m_w_0, τ_w_0 = 20.0, 1.0
+
+# We set relatively strong priors for random walk noise components
+# and sort of vague prior for the noise of the observations
+a_x, b_x = 0.01, 0.01var(real_x)
+a_w, b_w = 0.01, 0.01var(real_w)
+a_y, b_y = 1.0, 1.0
+
+# We set relatively strong priors for messages
+xinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))
+winit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))
+
+imessages = (x = xinit, w = winit)
+imarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))
+
+result = infer(
+    model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),
+    data  = (y = real_y,), 
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = imessages, 
+    initmarginals = imarginals, 
+    iterations = 50
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)

Let's examine our inference results:

τ_x_marginals = result.posteriors[:τ_x]
+τ_w_marginals = result.posteriors[:τ_w]
+τ_y_marginals = result.posteriors[:τ_y]
+
+smarginals = result.posteriors[:s]
+xmarginals = result.posteriors[:x]
+wmarginals = result.posteriors[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.

Combination 2: y = min(x, w)

In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:

# Smoothed version of `min` without zero-ed derivatives
+function smooth_min(x, y)    
+    if x < y
+        return x + 1e-4 * y
+    else
+        return y + 1e-4 * x
+    end
+end
smooth_min (generic function with 1 method)

RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:

min_meta = @meta begin 
+    # In this example we are going to use a simple `Linearization` method
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true
n = 200
+min_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, min_real_x, label = "x")
+pl = plot!(pl, min_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, min_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

min_m_x_0, min_τ_x_0 = -1.0, 1.0
+min_m_w_0, min_τ_w_0 = 1.0, 1.0
+
+min_a_x, min_b_x = 1.0, 1.0
+min_a_w, min_b_w = 1.0, 1.0
+min_a_y, min_b_y = 1.0, 1.0
+
+min_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))
+min_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))
+
+min_result = infer(
+    model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),
+    data  = (y = min_real_y,), 
+    meta = min_meta,
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = min_imessages, 
+    initmarginals = min_imarginals, 
+    iterations = 100
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)
min_τ_x_marginals = min_result.posteriors[:τ_x]
+min_τ_w_marginals = min_result.posteriors[:τ_w]
+min_τ_y_marginals = min_result.posteriors[:τ_y]
+
+min_smarginals = min_result.posteriors[:s]
+min_xmarginals = min_result.posteriors[:x]
+min_wmarginals = min_result.posteriors[:w]
+
+px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, min_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, min_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, min_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks).

Online (filtering) identification: y = min(x, w)

Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:

@model function rx_identification(f)
+    
+    # We are going to continuosly update our priors
+    # based on new posteriors
+    m_x_0 = datavar(Float64) 
+    τ_x_0 = datavar(Float64)
+    m_w_0 = datavar(Float64) 
+    τ_w_0 = datavar(Float64)
+    a_x   = datavar(Float64) 
+    b_x   = datavar(Float64)
+    a_y   = datavar(Float64) 
+    b_y   = datavar(Float64)
+    a_w   =  datavar(Float64) 
+    b_w   = datavar(Float64)
+    s     = randomvar()
+    y     = datavar(Float64)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x ~ Normal(mean = x0, precision = τ_x)
+    w ~ Normal(mean = w0, precision = τ_w)
+
+    s ~ f(x, w)
+    y ~ Normal(mean = s, precision = τ_y)
+    
+end

We impose structured mean-field assumption for this model as well:

rx_constraints = @constraints begin 
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ
+_y)
+Options:
+  warn = true

Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:

autoupdates = @autoupdates begin 
+    m_x_0, τ_x_0 = mean_precision(q(x))
+    m_w_0, τ_w_0 = mean_precision(q(w))
+    a_x = shape(q(τ_x)) 
+    b_x = rate(q(τ_x))
+    a_y = shape(q(τ_y))
+    b_y = rate(q(τ_y))
+    a_w = shape(q(τ_w)) 
+    b_w = rate(q(τ_w))
+end
(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_
+x = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_
+y)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))

As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):

rx_meta = @meta begin 
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true

Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:

n = 300
+rx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, rx_real_x, label = "x")
+pl = plot!(pl, rx_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

engine = infer(
+    model         = rx_identification(smooth_min),
+    constraints   = rx_constraints,
+    data          = (y = rx_real_y,),
+    autoupdates   = autoupdates,
+    meta          = rx_meta,
+    returnvars    = (:x, :w, :τ_x, :τ_w, :τ_y, :s),
+    keephistory   = 1000,
+    historyvars   =  KeepLast(),
+    initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),
+    iterations    = 10,
+    free_energy = true, 
+    free_energy_diagnostics = nothing,
+    autostart     = true,
+)
RxInferenceEngine:
+  Posteriors stream    | enabled for (w, s, τ_x, τ_w, τ_y, x)
+  Free Energy stream   | enabled
+  Posteriors history   | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)
+  Free Energy history  | available
+  Enabled events       | [  ]
rx_smarginals = engine.history[:s]
+rx_xmarginals = engine.history[:x]
+rx_wmarginals = engine.history[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, rx_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = "Estimated X")
+
+px1 = plot!(px1, rx_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = "Estimated W")
+
+px2 = scatter!(px2, rx_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the "disabled" state, does not infer anything and simply increases its variance (which is expected for the random walk).

Handling Missing Data

An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.

Let us assume that the following model generates the data

\[\begin{aligned} + {x}_t &\sim \mathcal{N}\left({x}_{t-1}, 1.0\right) \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, P \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation $\hat{y}_t \in \mathrm{R}$ we sometimes will catch missing observations.

using RxInfer, Plots
@model function smoothing(n, x0)
+    
+    P ~ Gamma(shape = 0.001, scale = 0.001)
+    x_prior ~ Normal(mean = mean(x0), var = var(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ Normal(mean = x_prev, precision = 1.0)
+        y[i] ~ Normal(mean = x[i], precision = P)
+        
+        x_prev = x[i]
+    end
+
+end

We need to manually extend the set of rules to support ::Missing values

P = 1.0
+n = 250
+
+real_signal     = map(e -> sin(0.05 * e), collect(1:n))
+noisy_data      = real_signal + rand(Normal(0.0, sqrt(P)), n);
+missing_indices = 100:125
+missing_data    = similar(noisy_data, Union{Float64, Missing}, )
+
+copyto!(missing_data, noisy_data)
+
+for index in missing_indices
+    missing_data[index] = missing
+end
constraints = @constraints begin
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+Options:
+  warn = true
x0_prior = NormalMeanVariance(0.0, 1000.0)
+
+result = infer(
+    model = smoothing(n, x0_prior), 
+    data  = (y = missing_data,), 
+    constraints = constraints,
+    initmarginals = (P = Gamma(0.001, 0.001), ),
+    returnvars = (x = KeepLast(),),
+    iterations = 20
+);
plot(real_signal, label = "Noisy signal", legend = :bottomright)
+scatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = "Missing region")
+plot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = "Estimated hidden state")

diff --git a/v2.16.0/examples/basic_examples/Predicting Bike Rental Demand/index.html b/v2.16.0/examples/basic_examples/Predicting Bike Rental Demand/index.html new file mode 100644 index 000000000..4b5583872 --- /dev/null +++ b/v2.16.0/examples/basic_examples/Predicting Bike Rental Demand/index.html @@ -0,0 +1,193 @@ + +Predicting Bike Rental Demand · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Predicting Bike Rental Demand

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer

Preamble: Enabling Predictions

RxInfer.jl facilitates predictions in two primary ways.

  1. Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.
  2. Explicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.

Example

Consider the following model:

@model function example_model()
+    y = datavar(Float64) where {allow_missing = true}
+
+    h ~ NormalMeanPrecision(0, 1.0)
+    x ~ NormalMeanPrecision(h, 1.0)
+    y ~ NormalMeanPrecision(x, 10.0)
+end
# Implicit Prediction
+result = infer(model = example_model(), data = (y = missing,))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)
# Explicit Prediction
+result = infer(model = example_model(), predictvars = (y = KeepLast(),))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)

Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.

using CSV, DataFrames, Plots

Objective

This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.

Dataset Source

Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.

# Load the data
+df = CSV.read("../data/bike_count/modified_bicycle.csv", DataFrame)
+df[1:10, :]
10×6 DataFrame
+ Row │ datetime            temp     atemp    humidity  windspeed  count
+     │ String31            Float64  Float64  Float64   Float64    Int64
+─────┼──────────────────────────────────────────────────────────────────
+   1 │ 2011-01-01 0:00:00     9.84   14.395      81.0     0.0        16
+   2 │ 2011-01-01 1:00:00     9.02   13.635      80.0     0.0        40
+   3 │ 2011-01-01 2:00:00     9.02   13.635      80.0     0.0        32
+   4 │ 2011-01-01 3:00:00     9.84   14.395      75.0     0.0        13
+   5 │ 2011-01-01 4:00:00     9.84   14.395      75.0     0.0         1
+   6 │ 2011-01-01 5:00:00     9.84   12.88       75.0     6.0032      1
+   7 │ 2011-01-01 6:00:00     9.02   13.635      80.0     0.0         2
+   8 │ 2011-01-01 7:00:00     8.2    12.88       86.0     0.0         3
+   9 │ 2011-01-01 8:00:00     9.84   14.395      75.0     0.0         8
+  10 │ 2011-01-01 9:00:00    13.12   17.425      76.0     0.0        14
# we reserve few samples for prediction
+n_future = 24
+
+X = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]
+y = Union{Float64, Missing}[df[:, "count"]...][1:end-n_future]
+
+state_dim = length(X[1]); # dimensionality of feature space

Generative Model with Priors

We present a generative model that delineates the latent dynamics of feature evolution, represented by $\mathbf{h}_t$, and their link to the bike rental counts, $\mathbf{y}_t$.

Equations and Priors

  1. Feature Dynamics with Prior:

    • Prior: $\mathbf{a} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Dynamics: $\mathbf{h}_t \sim \mathcal{N}(\mathbf{A h}_{t-1}, \mathbf{Q})$

    • \[\mathbf{A}\]

      is the transition matrix, reshaped from the prior vector $\mathbf{a}$, and $\mathbf{Q}$ represents process noise.

  2. Noisy Observations:

    • \[\mathbf{x}_t \sim \mathcal{N}(\mathbf{h}_t, \mathbf{P})\]

    • Represents the observed noisy state of the features.

  3. Count Prediction with Prior:

    • Prior: $\boldsymbol{\theta} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Prediction: $y_t \sim \mathcal{N}(\text{softplus}(\boldsymbol{\theta}^\top\mathbf{h}_t), \sigma^2)$
    • Models the bike rental count as influenced by a non-linear transformation of the hidden state.

Interpretation

  • This framework aims to simultaneously infer the transition matrix $\mathbf{A}$ and the regression parameters $\boldsymbol{\theta}$, providing a comprehensive view of the feature space dynamics and the count prediction.
  • By employing Gaussian priors on both $\mathbf{a}$ and $\boldsymbol{\theta}$, we incorporate beliefs about their distributions.
  • The inference process aims to discover these underlying dynamics, enabling predictions of both features $\mathbf{x}_t$ and counts $y_t$.
# We augument the dataset with missing entries for 24 hours ahead
+append!(X, repeat([missing], n_future))
+append!(y, repeat([missing], n_future));
# Function to perform the state transition in the model.
+# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.
+function transition(a, x)
+    nm, n = length(a), length(x)
+    m = nm ÷ n  # Calculate the number of rows for reshaping 'a' into a matrix
+    A = reshape(a, (m, n))  
+    return A * x
+end
transition (generic function with 1 method)
# The dotsoftplus function combines a dot product and softplus transformation.
+# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,
+# especially if the data suggests other forms of relationships or distributions.
+function dotsoftplus(a, x)
+    log(1 + exp(dot(a, x)))
+end
dotsoftplus (generic function with 1 method)
# model definction
+@model function bicycle_ssm(n, h0, θ0, a0, Q, P)
+
+    # `h` is a sequence of hidden states
+    h = randomvar(n)
+
+    # `x` is a sequence of observed states (features)
+    x = datavar(Vector{Float64}, n) where {allow_missing = true}
+    # `y` is a sequence of "count" bicycles
+    y = datavar(Float64, n) where {allow_missing = true}
+
+    a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))
+
+    θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))
+
+    h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))
+    h_prev = h_prior
+    
+    for i in 1:n
+        
+        h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)
+        
+        x[i] ~ MvNormal(μ=h[i], Σ=P)
+        
+        y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)
+        
+        h_prev = h[i]
+    end
+
+end
# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.
+# However, alternative methods like Unscented or CVI approximations can also be considered.
+transition_meta = @meta begin 
+    transition() -> Linearization()
+    dotsoftplus() -> Linearization()
+end
Meta specification:
+  transition() -> Linearization()
+  dotsoftplus() -> Linearization()
+Options:
+  warn = true
# We define rather uninformative priors 
+prior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))
+prior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))
+prior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))
MvNormalMeanCovariance(
+μ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0
+.0, 0.0]
+Σ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … 
+0.0 1.0]
+)
# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages
+imessages = ( h = prior_h, a = prior_a, θ = prior_θ,)
+
+bicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))
+
+result = infer(
+    model = bicycle_model,
+    data  = (y = y, x=X), 
+    options = (limit_stack_depth = 500, ), 
+    returnvars = KeepLast(),
+    initmessages = imessages,
+    meta = transition_meta,
+    iterations = 20,
+    showprogress=true,
+)
Inference results:
+  Posteriors       | available for (a, h, h_prior, θ)
+  Predictions      | available for (y, x)
# For a sake of this example, we extract only predictions
+mean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])
+mean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])
+
+mean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)
+mean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)
+mean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)
+mean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);
slice = (300, length(y))
+data = df[:, "count"][length(y)-n_future:length(y)]
+
+p = scatter(y, 
+            color=:darkblue, 
+            markerstrokewidth=0,
+            label="Observed Count", 
+            alpha=0.6)
+
+# Plotting the mean prediction with variance ribbon
+plot!(mean_y, ribbon=sqrt.(cov_y), 
+      color=:orange, 
+      fillalpha=0.3,
+      label="Predicted Mean ± Std Dev")
+
+# Adding a vertical line to indicate the start of the future prediction
+vline!([length(y)-n_future], 
+       label="Prediction Start", 
+       linestyle=:dash, 
+       linecolor=:green)
+
+# Future (unobserved) data
+plot!(length(y)-n_future:length(y), data, label="Future Count")
+
+# Adjusting the limits
+xlims!(slice)
+
+# Enhancing the plot with titles and labels
+title!("Bike Rental Demand Prediction")
+xlabel!("Time")
+ylabel!("Bike Count")
+
+# Adjust the legend
+legend=:topright
+
+# Show the final plot
+display(p)

using Plots
+
+# Define a color palette
+palette = cgrad(:viridis)
+
+# Plot the hidden states with observations
+p1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label="Hidden State 1", legend=:topleft)
+plot!(df[!, :temp], color=:grey, label="Temperature")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Temperature vs Hidden State 1")
+
+p2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label="Hidden State 2", legend=:topleft)
+plot!(df[!, :atemp], color=:grey, label="Feels-Like Temp")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="")
+xlabel!("Time")
+ylabel!("Value")
+title!("Feels-Like Temp vs Hidden State 2")
+
+p3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label="Hidden State 3", legend=:topleft)
+plot!(df[!, :humidity], color=:grey, label="Humidity")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Humidity vs Hidden State 3")
+
+p4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label="Hidden State 4", legend=:topleft)
+plot!(df[!, :windspeed], color=:grey, label="Windspeed")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Windspeed vs Hidden State 4")
+
+for p in [p1, p2, p3, p4]
+    xlims!(p, first(slice), last(slice))
+end
+
+plot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))

Conclusion

While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.

The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.

diff --git a/v2.16.0/examples/basic_examples/overview/index.html b/v2.16.0/examples/basic_examples/overview/index.html new file mode 100644 index 000000000..0ad84e66f --- /dev/null +++ b/v2.16.0/examples/basic_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Basic examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Basic examples contain "Hello World!" of Bayesian inference in RxInfer.

  • Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.
  • Bayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.
  • Kalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations
  • Predicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.
  • How to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.
diff --git a/v2.16.0/examples/overview/index.html b/v2.16.0/examples/overview/index.html new file mode 100644 index 000000000..5729dd4d5 --- /dev/null +++ b/v2.16.0/examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Examples overview

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

  • Basic examples: Basic examples contain "Hello World!" of Bayesian inference in RxInfer.
  • Advanced examples: Advanced examples contain more complex inference problems.
  • Problem specific: Problem specific examples contain specialized models and inference for various domains.
diff --git a/v2.16.0/examples/problem_specific/Autoregressive Models/index.html b/v2.16.0/examples/problem_specific/Autoregressive Models/index.html new file mode 100644 index 000000000..33265beff --- /dev/null +++ b/v2.16.0/examples/problem_specific/Autoregressive Models/index.html @@ -0,0 +1,311 @@ + +Autoregressive Models · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Autoregressive Models

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:

\[\begin{aligned} +p(\gamma) &= \mathrm{Gamma}(\gamma|a, b),\\ +p(\mathbf{\theta}) &= \mathcal{N}(\mathbf{\theta}|\mathbf{\mu}, \Sigma),\\ +p(x_t|\mathbf{x}_{t-1:t-k}) &= \mathcal{N}(x_t|\mathbf{\theta}^{T}\mathbf{x}_{t-1:t-k}, \gamma^{-1}),\\ +p(y_t|x_t) &= \mathcal{N}(y_t|x_t, \tau^{-1}), +\end{aligned}\]

where $x_t$ is a current state of our system, $\mathbf{x}_{t-1:t-k}$ is a sequence of $k$ previous states, $k$ is an order of autoregression process, $\mathbf{\theta}$ is a vector of transition coefficients, $\gamma$ is a precision of state transition process, $y_k$ is a noisy observation of $x_k$ with precision $\tau$.

For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.

We start with importing all needed packages:

using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters

Let's generate some synthetic dataset, we use a predefined sets of coeffcients for $k$ = 1, 3 and 5 respectively:

# The following coefficients correspond to stable poles
+coefs_ar_1 = [-0.27002517200218096]
+coefs_ar_2 = [0.4511170798064709, -0.05740081602446657]
+coefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];
function generate_ar_data(rng, n, θ, γ, τ)
+    order        = length(θ)
+    states       = Vector{Vector{Float64}}(undef, n + 3order)
+    observations = Vector{Float64}(undef, n + 3order)
+    
+    γ_std = sqrt(inv(γ))
+    τ_std = sqrt(inv(τ))
+    
+    states[1] = randn(rng, order)
+    
+    for i in 2:(n + 3order)
+        states[i]       = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])
+        observations[i] = rand(rng, Normal(states[i][1], τ_std))
+    end
+    
+    return states[1+3order:end], observations[1+3order:end]
+end
generate_ar_data (generic function with 1 method)
# Seed for reproducibility
+seed = 123
+rng  = MersenneTwister(seed)
+
+# Number of observations in synthetic dataset
+n = 500
+
+# AR process parameters
+real_γ = 1.0
+real_τ = 0.5
+real_θ = coefs_ar_5
+
+states, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);

Let's plot our synthetic dataset:

plot(first.(states), label = "Hidden states")
+scatter!(observations, label = "Observations")

Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order $k$ > 1 and for Univariate AR (reduces to simple State-Space-Model) with order $k$ = 1.

@model function lar_model(T::Type, n, order, c, τ)
+    
+     
+    # We create a sequence of random variables for hidden states
+    x = randomvar(n)
+    # As well a sequence of observartions
+    y = datavar(Float64, n)
+    
+    ct = constvar(c)
+    # We assume observation noise to be known
+    cτ = constvar(τ)
+    
+    γ  = randomvar()
+    θ  = randomvar()
+    x0 = randomvar()
+    
+    # Prior for first state
+    if T === Multivariate
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+        x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+    else
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ Normal(μ = 0.0, γ = 1.0)
+        x0 ~ Normal(μ = 0.0, γ = 1.0)
+    end
+    
+    x_prev = x0
+    
+    for i in 1:n
+        
+        x[i] ~ AR(x_prev, θ, γ) 
+        
+        if T === Multivariate
+            y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)
+        else
+            y[i] ~ Normal(μ = ct * x[i], γ = cτ)
+        end
+        
+        x_prev = x[i]
+    end
+
+end
@constraints function ar_constraints() 
+    q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)
+end
ar_constraints (generic function with 1 method)
@meta function ar_meta(artype, order, stype)
+    AR() -> ARMeta(artype, order, stype)
+end
ar_meta (generic function with 1 method)
morder  = 5
+martype = Multivariate
+mc      = ReactiveMP.ar_unit(martype, morder)
+mconstraints = ar_constraints()
+mmeta        = ar_meta(martype, morder, ARsafe())
+
+moptions = (limit_stack_depth = 100, )
+
+mmodel         = lar_model(martype, length(observations), morder, mc, real_τ)
+mdata          = (y = observations, )
+minitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))
+mreturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+# First execution is slow due to Julia's initial compilation 
+# Subsequent runs will be faster (benchmarks are below)
+mresult = infer(
+    model = mmodel, 
+    data  = mdata,
+    constraints   = mconstraints,
+    meta          = mmeta,
+    options       = moptions,
+    initmarginals = minitmarginals,
+    returnvars    = mreturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
@unpack x, γ, θ = mresult.posteriors
Dict{Symbol, Vector} with 3 entries:
+  :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)
+, Ga…
+  :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…
+  :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…

We will use different initial marginals depending on type of our AR process

p1 = plot(first.(states), label="Hidden state")
+p1 = scatter!(p1, observations, label="Observations")
+p1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label="Inferred states", legend = :bottomright)
+
+p2 = plot(mean.(γ), ribbon = std.(γ), label = "Inferred transition precision", legend = :topright)
+p2 = plot!([ real_γ ], seriestype = :hline, label = "Real transition precision")
+
+p3 = plot(mresult.free_energy, label = "Bethe Free Energy")
+
+plot(p1, p2, p3, layout = @layout([ a; b c ]))

Let's also plot a subrange of our results:

subrange = div(n,5):(div(n, 5) + div(n, 5))
+
+plot(subrange, first.(states)[subrange], label="Hidden state")
+scatter!(subrange, observations[subrange], label="Observations")
+plot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label="Inferred states", legend = :bottomright)

It is also interesting to see where our AR coefficients converge to:

let
+    pθ = plot()
+
+    θms = mean.(θ)
+    θvs = var.(θ)
+    
+    l = length(θms)
+
+    edim(e) = (a) -> map(r -> r[e], a)
+
+    for i in 1:length(first(θms))
+        pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = "Estimated θ[$i]")
+    end
+    
+    for i in 1:length(real_θ)
+        pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = "Real θ[$i]")
+    end
+    
+    plot(pθ, legend = :outertopright, size = (800, 300))
+end

println("$(length(real_θ))-order AR inference Bethe Free Energy: ", last(mresult.free_energy))
5-order AR inference Bethe Free Energy: 1024.0775661298358

We can also run a 1-order AR inference on 5-order AR data:

uorder  = 1
+uartype = Univariate
+uc      = ReactiveMP.ar_unit(uartype, uorder)
+uconstraints = ar_constraints()
+umeta        = ar_meta(uartype, uorder, ARsafe())
+
+uoptions = (limit_stack_depth = 100, )
+
+umodel         = lar_model(uartype, length(observations), uorder, uc, real_τ)
+udata          = (y = observations, )
+uinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))
+ureturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+uresult = infer(
+    model = umodel, 
+    data  = udata,
+    meta  = umeta,
+    constraints   = uconstraints,
+    initmarginals = uinitmarginals,
+    returnvars    = ureturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
println("1-order AR inference Bethe Free Energy: ", last(uresult.free_energy))
1-order AR inference Bethe Free Energy: 1025.8792949319954
if uresult.free_energy[end] > mresult.free_energy[end]
+    println("We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.")
+else
+    error("AR-1 performs better than AR-5...") 
+end
We can see that, according to final Bethe Free Energy value, in this exampl
+e 5-order AR process can describe data better than 1-order AR.

Autoregressive Moving Average Model

Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:

\[\begin{aligned} +e_t \sim \mathcal{N}(0, \gamma^{-1}) \quad +\theta &\sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \quad +\eta \sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \\ +\mathbf{h}_0 &\sim \mathcal{MN}\left(\begin{bmatrix} +e_{-1} \\ +e_{-2} +\end{bmatrix}, \mathbf{I}\right) \\ +\mathbf{h}_t &= \mathbf{S}\mathbf{h}_{t-1} + \mathbf{c} e_{t-1} \\ +\mathbf{x}_t &= \boldsymbol{\theta}^\top\mathbf{x}_{t-1} + \boldsymbol{\eta}^\top\mathbf{h}_{t} + e_t +\end{aligned}\]

where shift matrix $\mathbf{S}$ is

\[\begin{aligned} +\mathbf{S} = \begin{pmatrix} +0 & 0 \\ +1 & 0 +\end{pmatrix} +\end{aligned}\]

and unit vector $\mathbf{c}$:

\[\begin{aligned} +\mathbf{c}=[1, 0] +\end{aligned}\]

when MA order is $2$

In this way, $\mathbf{h}_t$ containing errors $e_t$ can be viewed as hidden state.

In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., $\boldsymbol{\eta}^\top\mathbf{h}_{t}$, (2) induced by errors $e_t$ that prevents analytical update of precision parameter $\gamma$ (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.

# Load packages
+using RxInfer, LinearAlgebra, CSV, DataFrames, Plots
# Define shift function
+function shift(dim)
+    S = Matrix{Float64}(I, dim, dim)
+    for i in dim:-1:2
+           S[i,:] = S[i-1, :]
+    end
+    S[1, :] = zeros(dim)
+    return S
+end
shift (generic function with 1 method)
@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)
+        
+    c = zeros(p); c[1] = 1.0; # AR
+    b = zeros(q); b[1] = 1.0; # MA
+    S = shift(q); # MA
+    
+    # initialize variables
+    h  = randomvar(n-1)
+    e  = randomvar(n)
+    z  = randomvar(n)
+    
+    x  = datavar(Float64, n) where { allow_missing = true }
+    
+    # priors
+    γ  ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))
+    η  ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))
+    θ  ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))
+    τ  ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))
+    
+    # initial
+    h_0  ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))
+    z[1] ~ AR(h_0, η, τ)
+    e[1] ~ Normal(mean = 0.0, precision = γ)
+
+    x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]
+    
+    h_prev = h_0
+    for t in 1:n-1
+        
+        e[t+1] ~ Normal(mean = 0.0, precision = γ)
+        h[t]   ~ S*h_prev + b*e[t]
+        z[t+1] ~ AR(h[t], η, τ)
+        x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]
+        h_prev = h[t]
+    end
+end

To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle

x_df = CSV.read("../data/arma/aal_stock.csv", DataFrame)
1259×7 DataFrame
+  Row │ date        open     high     low      close    volume    Name
+      │ Date        Float64  Float64  Float64  Float64  Int64     String3
+──────┼───────────────────────────────────────────────────────────────────
+    1 │ 2013-02-08    15.07    15.12   14.63     14.75   8407500  AAL
+    2 │ 2013-02-11    14.89    15.01   14.26     14.46   8882000  AAL
+    3 │ 2013-02-12    14.45    14.51   14.1      14.27   8126000  AAL
+    4 │ 2013-02-13    14.3     14.94   14.25     14.66  10259500  AAL
+    5 │ 2013-02-14    14.94    14.96   13.16     13.99  31879900  AAL
+    6 │ 2013-02-15    13.93    14.61   13.93     14.5   15628000  AAL
+    7 │ 2013-02-19    14.33    14.56   14.08     14.26  11354400  AAL
+    8 │ 2013-02-20    14.17    14.26   13.15     13.33  14725200  AAL
+  ⋮   │     ⋮          ⋮        ⋮        ⋮        ⋮        ⋮         ⋮
+ 1253 │ 2018-01-30    52.45    53.05   52.36     52.59   4741808  AAL
+ 1254 │ 2018-01-31    53.08    54.71   53.0      54.32   5962937  AAL
+ 1255 │ 2018-02-01    54.0     54.64   53.59     53.88   3623078  AAL
+ 1256 │ 2018-02-02    53.49    53.99   52.03     52.1    5109361  AAL
+ 1257 │ 2018-02-05    51.99    52.39   49.75     49.76   6878284  AAL
+ 1258 │ 2018-02-06    49.32    51.5    48.79     51.18   6782480  AAL
+ 1259 │ 2018-02-07    50.91    51.98   50.89     51.4    4845831  AAL
+                                                         1244 rows omitted
# we will use "close" column
+x_data = filter(!ismissing, x_df[:, 5]);
# Plot data
+plot(x_data, xlabel="day", ylabel="price", label=false)

p_order = 10 # AR
+q_order = 4 # MA
4
# Training set
+train_size = 1000
+x_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]
+x_train = Float64.(x_data[p_order+1:end])[1:train_size];
# Test set
+x_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]
+x_test = Float64.(x_data[p_order+1:end])[train_size+1:end];

Inference

# Constraints are needed for performing VMP
+arma_constraints = @constraints begin
+    q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)
+end;
# This cell defines prior knowledge for model parameters
+h_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+γ_prior = GammaShapeRate(1e4, 1.0)
+τ_prior = GammaShapeRate(1e2, 1.0)
+η_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+θ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));
# Model's graph has structural loops, hence, it requires pre-initialisation
+arma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);
+arma_imessages  = (h_0 = h_prior, h = h_prior);
+arma_meta       = ar_meta(Multivariate, q_order, ARsafe());
result = infer(
+    model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), 
+    data  = (x = x_train, ),
+    initmarginals = arma_imarginals,
+    initmessages  = arma_imessages,
+    constraints   = arma_constraints,
+    meta          = arma_meta,
+    iterations    = 50,
+    options       = (limit_stack_depth = 400, ),
+);
plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = "eₜ")

# extract posteriors
+h_posterior = result.posteriors[:h][end][end]
+γ_posterior = result.posteriors[:γ][end]
+τ_posterior = result.posteriors[:τ][end]
+η_posterior = result.posteriors[:η][end]
+θ_posterior = result.posteriors[:θ][end];

Prediction

Here we are going to use our inference results in order to predict the dataset itself

# The prediction function is aimed at approximating the predictive posterior distribution
+# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)
+function prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)
+    h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))
+    ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))
+    c = zeros(p); c[1] = 1.0
+    b = zeros(q); b[1] = 1.0
+    ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)
+    θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))
+    ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)
+    e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))
+    ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out)  
+    @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out)  
+end
prediction (generic function with 1 method)
predictions = []
+for x_prev in x_prev_test
+    push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))
+    # after every new prediction we can actually "retrain" the model to use the power of Bayesian approach
+    # we will skip this part at this notebook
+end
plot(x_test, label="test data", legend=:topleft)
+plot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label="predicted", xlabel="day", ylabel="price")

diff --git a/v2.16.0/examples/problem_specific/Gamma Mixture/index.html b/v2.16.0/examples/problem_specific/Gamma Mixture/index.html new file mode 100644 index 000000000..7ba3c349f --- /dev/null +++ b/v2.16.0/examples/problem_specific/Gamma Mixture/index.html @@ -0,0 +1,129 @@ + +Gamma Mixture Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gamma Mixture Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.

Load packages

using RxInfer, Random, StatsPlots
# create custom structure for model parameters for simplicity
+struct GammaMixtureModelParameters
+    nmixtures   # number of mixtures
+    priors_as   # tuple of priors for variable a
+    priors_bs   # tuple of priors for variable b
+    prior_s     # prior of variable s
+end

Model specification

@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)
+
+    # fetch information from struct
+    nmixtures = parameters.nmixtures
+    priors_as = parameters.priors_as
+    priors_bs = parameters.priors_bs
+    prior_s   = parameters.prior_s
+
+    # set prior on global selection variable
+    s ~ Dirichlet(probvec(prior_s))
+
+    # allocate vectors of random variables
+    as = randomvar(nmixtures)
+    bs = randomvar(nmixtures)
+
+    # set priors on variables of mixtures
+    for i in 1:nmixtures
+        as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))
+        bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))
+    end
+
+    # introduce random variables for local selection variables and data
+    z = randomvar(nobservations)
+    y = datavar(Float64, nobservations)
+
+    # convert vector to tuples for proper functioning of GammaMixture node
+    tas = tuple(as...)
+    tbs = tuple(bs...)
+
+    # specify local selection variable and data generating process
+    for i in 1:nobservations
+        z[i] ~ Categorical(s)
+        y[i] ~ GammaMixture(z[i], tas, tbs)
+    end
+    
+end
constraints = @constraints begin 
+
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+
+    q(as) = q(as[begin])..q(as[end])
+    q(bs) = q(bs[begin])..q(bs[end])
+    
+    q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])
+end
Constraints:
+  marginals form:
+    q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+    q(as) = q(as[(begin)..(end)])
+    q(bs) = q(bs[(begin)..(end)])
+Options:
+  warn = true
# specify seed and number of data points
+rng = MersenneTwister(43)
+n_samples = 2500
+
+# specify parameters of mixture model that generates the data
+# Note that mixture components have exactly the same means
+mixtures  = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]
+nmixtures = length(mixtures)
+mixing    = rand(rng, nmixtures)
+mixing    = mixing ./ sum(mixing)
+mixture   = MixtureModel(mixtures, mixing)
+
+# generate data set
+dataset = rand(rng, mixture, n_samples);
# specify priors of probabilistic model
+# NOTE: As the means of the mixtures "collide", we specify informative prior for selector variable
+nmixtures = 2
+gpriors = GammaMixtureModelParameters(
+    nmixtures,                                                    # number of mixtures
+    [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ],                         # priors on variables a
+    [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ],      # priors on variables b
+    Dirichlet(1e3*mixing)                                         # prior on variable s
+)
+
+gmodel         = gamma_mixture_model(length(dataset), gpriors)
+gdata          = (y = dataset, )
+ginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))
+greturnvars    = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())
+
+goptions = (
+     
+    default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently
+)
+
+gresult = infer(
+    model         = gmodel, 
+    data          = gdata,
+    constraints   = constraints,
+    options       = (limit_stack_depth = 100,),
+    initmarginals = ginitmarginals,
+    returnvars    = greturnvars,
+    free_energy   = true,
+    iterations    = 250, 
+    showprogress  = true
+);
# extract inferred parameters
+_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])
+_dists   = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))
+_mixing = mean(gresult.posteriors[:s])
+
+# create model from inferred parameters
+_mixture   = MixtureModel(_dists, _mixing);
# report on outcome of inference
+println("Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))")
+println("Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))")
+println("========")
+println("Generated mixing: $(mixing)")
+println("Inferred mixing: $(_mixing)")
Generated means: 0.3333333333333333 and 0.33333333333333337
+Inferred means: 0.33822470398804994 and 0.33305534672666653
+========
+Generated mixing: [0.18923488676601088, 0.8107651132339891]
+Inferred mixing: [0.11395888467453213, 0.8860411153254679]
# plot results
+p1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p1 = plot!(mixture, label=false, title="Generated mixtures", linewidth=3.0)
+
+p2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p2 = plot!(_mixture, label=false, title="Inferred mixtures", linewidth=3.0)
+
+# evaluate the convergence of the algorithm by monitoring the BFE
+p3 = plot(gresult.free_energy, label=false, xlabel="iterations", title="Bethe FE")
+
+plot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))

diff --git a/v2.16.0/examples/problem_specific/Gaussian Mixture/index.html b/v2.16.0/examples/problem_specific/Gaussian Mixture/index.html new file mode 100644 index 000000000..50f2e99de --- /dev/null +++ b/v2.16.0/examples/problem_specific/Gaussian Mixture/index.html @@ -0,0 +1,170 @@ + +Gaussian Mixture · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gaussian Mixture

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.

Load packages

using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings

Univariate Gaussian Mixture Model

Consider the data set of length $N$ observed below.

function generate_univariate_data(nr_samples; rng = MersenneTwister(123))
+
+    # data generating parameters
+    class        = [1/3, 2/3]
+    mean1, mean2 = -10, 10
+    precision    = 1.777
+
+    # generate data
+    z = rand(rng, Categorical(class), nr_samples)
+    y = zeros(nr_samples)
+    for k in 1:nr_samples
+        y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))
+    end
+
+    return y
+
+end;
data_univariate = generate_univariate_data(100)
+histogram(data_univariate, bins=50, label="data", normed=true)
+xlims!(minimum(data_univariate), maximum(data_univariate))
+ylims!(0, Inf)
+ylabel!("relative occurrence [%]")
+xlabel!("y")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, w, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(w_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Beta}(s \mid \alpha_s, \beta_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \sigma_k^2) \\ p(w_{k}) &= \Gamma(w_k \mid \alpha_k, \beta_k) \\ + p(z_n \mid s) &= \mathrm{Ber}(z_n \mid s) \\ + p(y_n \mid m, w, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, w_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $w = \{ w_1, w_2, \ldots, w_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

Here we implement the following model with uninformative values for the hyperparameters as

@model function univariate_gaussian_mixture_model(nr_samples)
+    
+    s ~ Beta(1.0, 1.0)
+    
+    m1 ~ Normal(mean = -2.0, var = 1e3)
+    w1 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    m2 ~ Normal(mean = 2.0, var = 1e3)
+    w2 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    z = randomvar(nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    for n in 1:nr_samples
+        z[n] ~ Bernoulli(s)
+        y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, w \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, w \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(w_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Beta}(s \mid \hat{\alpha}_s, \hat{\beta}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\sigma}^2_k) \\ + q(w_k) &= \Gamma (w_k \mid \hat{\alpha}_k, \hat{\beta}_k) \\ + q(z_n) &= \mathrm{Ber}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

results_univariate = infer(
+    model = univariate_gaussian_mixture_model(length(data_univariate)), 
+    constraints = MeanField(),
+    data  = (y = data_univariate,), 
+    initmarginals = (
+        s  = vague(Beta), 
+        m1 = NormalMeanVariance(-2.0, 1e3), 
+        m2 = NormalMeanVariance(2.0, 1e3), 
+        w1 = vague(GammaShapeRate), 
+        w2 = vague(GammaShapeRate)
+    ), 
+    iterations  = 10, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m2, m1, s, w2, w1, z)
+  Free Energy:     | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.
+277, 135.277, 135.277, 135.277, 135.277]

Results

Below the inference results can be seen as a function of the iterations

mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L"posterior $m_1$")
+mp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L"posterior $m_2$")
+mp = plot!(mp, [ -10 ], seriestype = :hline, label = L"true $m_1$")
+mp = plot!(mp, [ 10 ], seriestype = :hline, label = L"true $m_2$")
+
+wp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L"posterior $w_1$", legend = :bottomright, ylim = (-1, 3))
+wp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L"posterior $w_2$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_1$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_2$")
+
+swp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L"posterior $s$")
+swp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L"true $s$")
+
+fep = plot(results_univariate.free_energy, label = "Free Energy", legend = :topright)
+
+plot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))
+xlabel!("iteration")

Multivariate Gaussian Mixture Model

The above example can also be extended to the multivariate case. Consider the data set below

function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))
+
+    L         = 50.0
+    nr_mixtures = 6
+
+    probvec = normalize!(ones(nr_mixtures), 1)
+
+    switch = Categorical(probvec)
+
+    gaussians = map(1:nr_mixtures) do index
+        angle      = 2π / nr_mixtures * (index - 1)
+        basis_v    = L * [ 1.0, 0.0 ]
+        R          = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]
+        mean       = R * basis_v 
+        covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))
+        return MvNormal(mean, covariance)
+    end
+
+    z = rand(rng, switch, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+
+    for n in 1:nr_samples
+        y[n] = rand(rng, gaussians[z[n]])
+    end
+
+    return y
+
+end;
data_multivariate = generate_multivariate_data(500)
+
+sdim(n) = (a) -> map(d -> d[n], a) # helper function
+scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)
+xlabel!(L"y_1")
+ylabel!(L"y_2")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, W, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(W_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Dir}(s \mid \alpha_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \Sigma_k) \\ p(W_{k}) &= \mathcal{W}(W_k \mid V_k, \nu_k) \\ + p(z_n \mid s) &= \mathrm{Cat}(z_n \mid s) \\ + p(y_n \mid m, W, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, W_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $W = \{ W_1, W_2, \ldots, W_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)
+    
+    z = randomvar(nr_samples)
+    m = randomvar(nr_mixtures)
+    w = randomvar(nr_mixtures)
+    y = datavar(Vector{Float64}, nr_samples)
+    
+    for k in 1:nr_mixtures        
+        m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])
+        w[k] ~ Wishart(3, 1e2*diagm(ones(2)))
+    end
+    
+    s ~ Dirichlet(ones(nr_mixtures))
+    
+    means = tuple(m...)
+    precs = tuple(w...)
+    
+    for n in 1:nr_samples
+        z[n] ~ Categorical(s) 
+        y[n] ~ NormalMixture(z[n], means, precs)
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, W \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, W \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(W_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Dir}(s \mid \hat{\alpha}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\Sigma}_k) \\ + q(w_k) &= \mathcal{W}(W_k \mid \hat{V}_k, \hat{\nu}_k) \\ + q(z_n) &= \mathrm{Cat}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

rng = MersenneTwister(121)
+m = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]
+results_multivariate = infer(
+    model = multivariate_gaussian_mixture_model(
+        6, 
+        length(data_multivariate), 
+        m,
+        [diagm(1e2 * ones(2)) for k in 1:6]
+    ), 
+    data  = (y = data_multivariate,), 
+    constraints   = MeanField(),
+    initmarginals = (
+        s = vague(Dirichlet, 6), 
+        m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], 
+        w = Wishart(3, diagm(1e2 * ones(2)))
+    ), 
+    iterations  = 50, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m, w, s, z)
+  Free Energy:     | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49  …  3894.49, 3894.49, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]

Results

Below the inference results can be seen

p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title="Data", xlims=(-75, 75), ylims=(-75, 75))
+p_result = plot(xlims = (-75, 75), ylims = (-75, 75), title="Inference result", legend=false, colorbar = false)
+for (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])
+    gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))
+    global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title="Inference result", legend=false, levels = 7, colorbar = false)
+end
+p_fe = plot(results_multivariate.free_energy, label = "Free Energy")
+
+plot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))

diff --git a/v2.16.0/examples/problem_specific/Hierarchical Gaussian Filter/index.html b/v2.16.0/examples/problem_specific/Hierarchical Gaussian Filter/index.html new file mode 100644 index 000000000..b696a7700 --- /dev/null +++ b/v2.16.0/examples/problem_specific/Hierarchical Gaussian Filter/index.html @@ -0,0 +1,145 @@ + +Hierarchical Gaussian Filter · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Hierarchical Gaussian Filter

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).

Simple HGF model can be defined as:

\[\begin{aligned} + x^{(j)}_k & \sim \, \mathcal{N}(x^{(j)}_{k - 1}, f_k(x^{(j - 1)}_k)) \\ + y_k & \sim \, \mathcal{N}(x^{(j)}_k, \tau_k) +\end{aligned}\]

where $j$ is an index of layer in hierarchy, $k$ is a time step and $f_k$ is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with $f_k = \exp(\kappa x + \omega)$ variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:

\[\begin{aligned} + z_k & \sim \, \mathcal{N}(z_{k - 1}, \mathcal{\tau_z}) \\ + x_k & \sim \, \mathcal{N}(x_{k - 1}, \exp(\kappa z_k + \omega)) \\ + y_k & \sim \, \mathcal{N}(x_k, \mathcal{\tau_y}) +\end{aligned}\]

In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.

For simplicity we will consider $\tau_z$, $\tau_y$, $\kappa$ and $\omega$ known and fixed, but there are no principled limitations to make them random variables too.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, k, w, zv, yv)
+    z_prev = 0.0
+    x_prev = 0.0
+
+    z = Vector{Float64}(undef, n)
+    v = Vector{Float64}(undef, n)
+    x = Vector{Float64}(undef, n)
+    y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        z[i] = rand(rng, Normal(z_prev, sqrt(zv)))
+        v[i] = exp(k * z[i] + w)
+        x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))
+        y[i] = rand(rng, Normal(x[i], sqrt(yv)))
+
+        z_prev = z[i]
+        x_prev = x[i]
+    end 
+    
+    return z, x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 42
+
+rng = MersenneTwister(seed)
+
+# Parameters of HGF process
+real_k = 1.0
+real_w = 0.0
+z_variance = abs2(0.2)
+y_variance = abs2(0.1)
+
+# Number of observations
+n = 300
+
+z, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.

let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    scatter!(px, 1:n, y, label = "y_i", color = :red, ms = 2, alpha = 0.2)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

To create a model we use the @model macro:

# We create a single-time step of corresponding state-space process to
+# perform online learning (filtering)
+@model function hgf(real_k, real_w, z_variance, y_variance)
+    
+    # Priors from previous time step for `z`
+    zt_min_mean = datavar(Float64)
+    zt_min_var  = datavar(Float64)
+    
+    # Priors from previous time step for `x`
+    xt_min_mean = datavar(Float64)
+    xt_min_var  = datavar(Float64)
+
+    zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)
+    xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)
+
+    # Higher layer is modelled as a random walk 
+    zt ~ NormalMeanVariance(zt_min, z_variance)
+    
+    # Lower layer is modelled with `GCV` node
+    gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)
+    
+    # Noisy observations 
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(xt, y_variance)
+    
+    return gcvnode
+end
+
+@constraints function hgfconstraints() 
+    q(xt, zt, xt_min) = q(xt, xt_min)q(zt)
+end
+
+@meta function hgfmeta()
+    # Lets use 31 approximation points in the Gauss Hermite cubature approximation method
+    GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) 
+end
hgfmeta (generic function with 1 method)
function run_inference(data, real_k, real_w, z_variance, y_variance)
+
+    autoupdates   = @autoupdates begin
+        zt_min_mean, zt_min_var = mean_var(q(zt))
+        xt_min_mean, xt_min_var = mean_var(q(xt))
+    end
+
+    return infer(
+        model         = hgf(real_k, real_w, z_variance, y_variance),
+        constraints   = hgfconstraints(),
+        meta          = hgfmeta(),
+        data          = (y = data, ),
+        autoupdates   = autoupdates,
+        keephistory   = length(data),
+        historyvars    = (
+            xt = KeepLast(),
+            zt = KeepLast()
+        ),
+        initmarginals = (
+            zt = NormalMeanVariance(0.0, 5.0),
+            xt = NormalMeanVariance(0.0, 5.0),
+        ), 
+        iterations    = 5,
+        free_energy   = true,
+        autostart     = true,
+        callbacks     = (
+            after_model_creation = (model, returnval) -> begin 
+                gcvnode = returnval
+                setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))
+            end,
+        )
+    )
+end
run_inference (generic function with 1 method)
result = run_inference(y, real_k, real_w, z_variance, y_variance);
+
+mz = result.history[:zt];
+mx = result.history[:xt];
let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = "estimated z_i", color = :teal)
+    
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = "estimated x_i", color = :violet)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:

plot(result.free_energy_history, label = "Bethe Free Energy")

As we can see BetheFreeEnergy converges nicely to a stable point.

At final, lets check the overall performance of our resulting Variational Message Passing algorithm:

@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)
BenchmarkTools.Trial: 40 samples with 1 evaluation.
+ Range (min … max):  106.663 ms … 184.785 ms  ┊ GC (min … max): 0.00% … 0.0
+0%
+ Time  (median):     125.543 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   127.181 ms ±  14.793 ms  ┊ GC (mean ± σ):  1.51% ± 2.7
+2%
+
+   ▂     ▂     ▅█ ▅ ▂                                            
+  ▅█▁▁█▅▅█▁▁▁▁▅████▅█▁▁▁▅█▅▁▁▅▁▁▅▁▁▁▅▁▁▁▁▁▅▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▅ ▁
+  107 ms           Histogram: frequency by time          185 ms <
+
+ Memory estimate: 18.82 MiB, allocs estimate: 458387.
diff --git a/v2.16.0/examples/problem_specific/Invertible Neural Network Tutorial/index.html b/v2.16.0/examples/problem_specific/Invertible Neural Network Tutorial/index.html new file mode 100644 index 000000000..56b9c9474 --- /dev/null +++ b/v2.16.0/examples/problem_specific/Invertible Neural Network Tutorial/index.html @@ -0,0 +1,293 @@ + +Invertible neural networks: a tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Invertible neural networks: a tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Table of contents

  1. Introduction
  2. Model specification
  3. Model compilation
  4. Probabilistic inference
  5. Parameter estimation

Introduction

Load required packages

Before we can start, we need to import some packages:

using RxInfer
+using Random
+using StableRNGs
+
+using ReactiveMP        # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality
+using LinearAlgebra     # only used for some matrix specifics
+using Plots             # only used for visualisation
+using Distributions     # only used for sampling from multivariate distributions
+using Optim             # only used for parameter optimisation

Model specification

Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as 

model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Alternatively, the input_dim can also be passed as an InputLayer layer as 

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

In the above AdditiveCouplingLayer layers the input ${\bf{x}} = [x_1, x_2, \ldots, x_N]$ is partitioned into chunks of unit length. These partitions are additively coupled to an output ${\bf{y}} = [y_1, y_2, \ldots, y_N]$ as

\[\begin{aligned} + y_1 &= x_1 \\ + y_2 &= x_2 + f_1(x_1) \\ + \vdots \\ + y_N &= x_N + f_{N-1}(x_{N-1}) +\end{aligned}\]

Importantly, this structure can easily be converted as

\[\begin{aligned} + x_1 &= y_1 \\ + x_2 &= y_2 - f_1(x_1) \\ + \vdots \\ + x_N &= y_N - f_{N-1}(x_{N-1}) +\end{aligned}\]

\[f_n\]

is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.

A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false),
+        PermutationLayer(PermutationMatrix(2)),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Model compilation

In the current models, the layers are setup to work with the passed input dimension. This means that the function $f_n$ is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get

model
FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P
+lanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa
+yerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou
+plingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar
+FlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad
+ditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive
+MP.PlanarFlowEmpty{1}(),), 1)))

The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):

  • FlowModel - specifies that we are dealing with a flow model.
  • 3 - Number of layers.
  • Tuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.
  • Tuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions $f_n$.
  • PermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].

From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as

compiled_model = compile(model)
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(0.24357081234214367, -0.7202599
+849473186, 0.7012262639170591),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(-0.0928216039987209, -2.329353058120145, 0.570152767728
+4544),), 1)))

Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.

compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361
+28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323
+52386),), 1)))

Probabilistic inference

We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.

function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)
+
+    rng = StableRNG(seed)
+    
+    # specify latent sampling distribution
+    dist = MvNormal([1.5, 0.5], I)
+
+    # sample from the latent distribution
+    x = rand(rng, dist, nr_samples)
+
+    # transform data
+    y = zeros(Float64, size(x))
+    for k = 1:nr_samples
+        y[:,k] .= ReactiveMP.forward(model, x[:,k])
+    end
+
+    # return data
+    return y, x
+
+end;
# generate data
+y, x = generate_data(1000, compiled_model)
+
+# plot generated data
+p1 = scatter(x[1,:], x[2,:], alpha=0.3, title="Original data", size=(800,400))
+p2 = scatter(y[1,:], y[2,:], alpha=0.3, title="Transformed data", size=(800,400))
+plot(p1, p2, legend = false)

The probabilistic model for doing inference can be described as 

@model function invertible_neural_network(nr_samples::Int64)
+    
+    # initialize variables
+    z_μ   = randomvar()
+    z_Λ   = randomvar()
+    x     = randomvar(nr_samples)
+    y_lat = randomvar(nr_samples)
+    y     = datavar(Vector{Float64}, nr_samples)
+
+    # specify prior
+    z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))
+    z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)
+
+        # specify transformed latent value
+        y_lat[k] ~ Flow(x[k])
+
+        # specify observations
+        y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))
+
+    end
+
+    # return variables
+    return z_μ, z_Λ, x, y_lat, y
+
+end;

Here the model is passed inside a meta data object of the flow node. Inference then resorts to

observations = [y[:,k] for k=1:size(y,2)]
+
+fmodel         = invertible_neural_network(length(observations))
+data          = (y = observations, )
+initmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))
+returnvars    = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())
+
+constraints = @constraints begin
+    q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)
+end
+
+@meta function fmeta(model)
+    compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
+    Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). 
+                                               # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))
+end
+
+# First execution is slow due to Julia's initial compilation 
+result = infer(
+    model = fmodel, 
+    data  = data,
+    constraints   = constraints,
+    meta          = fmeta(model),
+    initmarginals = initmarginals,
+    returnvars    = returnvars,
+    free_energy   = true,
+    iterations    = 10, 
+    showprogress  = false
+)
Inference results:
+  Posteriors       | available for (z_μ, z_Λ, y_lat, x)
+  Free Energy:     | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357
+0.6, 23570.6, 23570.6, 23570.6, 23570.6]
fe_flow = result.free_energy
+zμ_flow = result.posteriors[:z_μ]
+zΛ_flow = result.posteriors[:z_Λ]
+x_flow  = result.posteriors[:x]
+y_flow  = result.posteriors[:y_lat];

As we can see, the variational free energy decreases inside of our model.

plot(1:10, fe_flow/size(y,2), xlabel="iteration", ylabel="normalized variational free energy [nats/sample]", legend=false)

If we plot a random noisy observation and its approximated transformed uncertainty we obtain:

# pick a random observation
+id = rand(StableRNG(321), 1:size(y,2))
+rand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))
+warped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');
+
+p1 = scatter(x[1,:], x[2,:], alpha=0.1, title="Latent distribution", size=(1200,500), label="generated data")
+contour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)
+scatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color="red", markershape=:x, markersize=5, label="inferred mean")
+contour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors="red", levels=1, linewidth=2, colorbar=false)
+scatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color="red", label="transformed noisy observation")
+p2 = scatter(y[1,:], y[2,:], alpha=0.1, label="generated data")
+scatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color="red", marker=:x, label="inferred mean")
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors="red", levels=1, linewidth=2, label="random noisy observation", colorba=false)
+scatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color="red", label="random noisy observation")
+plot(p1, p2, legend = true)

Parameter estimation

The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+
+    # sample weights
+    w = rand(rng, nr_samples, 2)
+
+    # sample appraisal
+    y = zeros(Float64, nr_samples)
+    for k = 1:nr_samples
+        y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)
+    end
+
+    # return data
+    return y, w
+
+end;
data_y, data_x = generate_data(50);
+scatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel="w1", ylabel="w2", colorbar=false, legend=false)

We will then specify a possible model as

# specify flow model
+model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

The corresponding probabilistic model for the binary classification task can be created as

@model function invertible_neural_network_classifier(nr_samples::Int64)
+    
+    # initialize variables
+    x_lat  = randomvar(nr_samples)
+    y_lat1 = randomvar(nr_samples)
+    y_lat2 = randomvar(nr_samples)
+    y      = datavar(Float64, nr_samples)
+    x      = datavar(Vector{Float64}, nr_samples)
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))
+
+        # specify transformed latent value
+        y_lat1[k] ~ Flow(x_lat[k])
+        y_lat2[k] ~ dot(y_lat1[k], [1, 1])
+
+        # specify observations
+        y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }
+
+    end
+
+    # return variables
+    return x_lat, x, y_lat1, y_lat2, y
+
+end;
fcmodel       = invertible_neural_network_classifier(length(data_y))
+data          = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )
+
+@meta function fmeta(model, params)
+    compiled_model = compile(model, params)
+    Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)
+end
fmeta (generic function with 2 methods)

Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as

For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.

function f(params)
+    Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure
+    result = infer(
+        model                   = fcmodel, 
+        data                    = data,
+        meta                    = fmeta(model, params),
+        free_energy             = true,
+        free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure
+        iterations              = 10, 
+        showprogress            = false
+    );
+    
+    result.free_energy[end]
+end;

Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:

res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)
  • uses finitediff and is slower/less accurate.

or

# create gradient function
+g = (x) -> ForwardDiff.gradient(f, x);
+
+# specify initial params
+params = randn(nr_params(model))
+
+# create custom optimizer (here Adam)
+optimizer = Adam(params; λ=1e-1)
+
+# allocate space for gradient
+∇ = zeros(nr_params(model))
+
+# perform optimization
+for it = 1:10000
+
+    # backward pass
+    ∇ .= ForwardDiff.gradient(f, optimizer.x)
+
+    # gradient update
+    ReactiveMP.update!(optimizer, ∇)
+
+end
+
res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)
Iter     Function value   Gradient norm 
+     0     5.888958e+02     8.943663e+02
+ * time: 5.91278076171875e-5
+   100     1.059826e+01     4.120090e+00
+ * time: 11.980152130126953
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.010332e+01
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.21e-03 ≰ 0.0e+00
+    |x - x'|/|x'|          = 5.80e-04 ≰ 0.0e+00
+    |f(x) - f(x')|         = 6.28e-03 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03
+    |g(x)|                 = 2.07e+00 ≰ 1.0e-08
+
+ * Work counters
+    Seconds run:   14  (vs limit Inf)
+    Iterations:    113
+    f(x) calls:    301
+    ∇f(x) calls:   301

optimization results are then given as

params = Optim.minimizer(res)
+inferred_model = compile(model, params)
+trans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'
+trans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])
+trans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title="original data")
+p2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title="|> warp")
+p3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title="|> dot")
+plot(p1, p2, p3, layout=(1,3), legend=false)

using StatsFuns: normcdf
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title="original labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title="predicted labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title="Classification map", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+plot(p1, p2, p3, layout=(1,3), legend=false)

diff --git a/v2.16.0/examples/problem_specific/Probit Model (EP)/index.html b/v2.16.0/examples/problem_specific/Probit Model (EP)/index.html new file mode 100644 index 000000000..9956a2f94 --- /dev/null +++ b/v2.16.0/examples/problem_specific/Probit Model (EP)/index.html @@ -0,0 +1,76 @@ + +Probit Model (EP) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Probit Model (EP)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable $x_t$ with the discrete variable $y_t$. The model is defined as:

\[\begin{aligned} + u &= 0.1 \\ + x_0 &\sim \mathcal{N}(0, 100) \\ + x_t &\sim \mathcal{N}(x_{t-1}+ u, 0.01) \\ + y_t &\sim \mathrm{Ber}(\Phi(x_t)) +\end{aligned}\]

Import packages

using RxInfer, StableRNGs, Random, Plots
+using StatsFuns: normcdf

Data generation

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+    
+    # hyper parameters
+    u = 0.1
+
+    # allocate space for data
+    data_x = zeros(nr_samples + 1)
+    data_y = zeros(nr_samples)
+    
+    # initialize data
+    data_x[1] = -2
+    
+    # generate data
+    for k = 2:nr_samples + 1
+        
+        # calculate new x
+        data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)
+        
+        # calculate y
+        data_y[k-1] = normcdf(data_x[k]) > rand(rng)
+        
+    end
+    
+    # return data
+    return data_x, data_y
+    
+end;
n = 40
40
data_x, data_y = generate_data(n);
p = plot(xlabel = "t", ylabel = "x, y")
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x")

Model specification

@model function probit_model(nr_samples::Int64)
+    
+    # allocate space for variables
+    x = randomvar(nr_samples + 1)
+    y = datavar(Float64, nr_samples)
+    
+    # specify uninformative prior
+    x[1] ~ Normal(mean = 0.0, precision = 0.01)
+    
+    # create model 
+    for k = 2:nr_samples + 1
+        x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)
+        y[k - 1] ~ Probit(x[k]) where {
+            # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge
+            # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations
+            pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) 
+        }
+    end
+    
+end;

Inference

result = infer(
+    model = probit_model(length(data_y)), 
+    data  = (y = data_y, ), 
+    iterations = 5, 
+    returnvars = (x = KeepLast(),),
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (x)
+  Free Energy:     | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]

Results

mx = result.posteriors[:x]
+
+p = plot(xlabel = "t", ylabel = "x, y", legend = :bottomright)
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x", lw = 2)
+p = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label="x (inferred mean)")
+
+f = plot(xlabel = "t", ylabel = "BFE")
+f = plot!(result.free_energy, label = "Bethe Free Energy")
+
+plot(p, f, size = (800, 400))

diff --git a/v2.16.0/examples/problem_specific/RTS vs BIFM Smoothing/index.html b/v2.16.0/examples/problem_specific/RTS vs BIFM Smoothing/index.html new file mode 100644 index 000000000..1034258f2 --- /dev/null +++ b/v2.16.0/examples/problem_specific/RTS vs BIFM Smoothing/index.html @@ -0,0 +1,242 @@ + +RTS vs BIFM Smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

RTS vs BIFM Smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

___Credits to Martin de Quincey___

This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:

  1. F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762
  2. H. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.

We perform Kalman smoothing in the linear state space model, represented by:

\[\begin{aligned} + Z_{k+1} &= A Z_k + B U_k \\ + Y_k &= C Z_k + W_k +\end{aligned}\]

with observations $Y_k$, latent states $Z_k$ and inputs $U_k$. $W_k$ is the observation noise. $A \in \mathrm{R}^{n \times n}$, $B \in \mathrm{R}^{n \times m}$ and $C \in \mathrm{R}^{d \times n}$ are the transition matrices in the model. Here $n$, $m$ and $d$ denote the dimensionality of the latent, input and output dimension, respectively.

The corresponding probabilistic model can be represented as

\[\begin{aligned} + p(y,\ z,\ u) + &= p(z_0) \prod_{k=1}^N p(y_k \mid z_k)\ p(z_k\mid z_{k-1},\ u_{k-1})\ p(u_{k-1}) \\ + &= \mathcal{N}(z_0 \mid \mu_{z_0}, \Sigma_{z_0}) \left( \prod_{k=1}^N \mathcal{N}(y_k \mid C z_k,\ \Sigma_W)\ \delta(z_k - (Az_{k-1} + Bu_{k-1})) \mathcal{N}(u_{k-1} \mid \mu_{i_{k-1}},\ \Sigma_{u_{k-1}}) \right) +\end{aligned}\]

Import packages

using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs

Data generation

function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)
+    
+    # define noise levels
+    input_noise  = 500.0
+    output_noise = 50.0
+
+    # create random generator for reproducibility
+    rng = MersenneTwister(seed)
+
+    # generate matrices, input statistics and noise matrices
+    A      = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat))                                            # size (dim_lat x dim_lat)
+    B      = rand(dim_lat, dim_in)                                                                              # size (dim_lat x dim_in)
+    C      = rand(dim_out, dim_lat)                                                                             # size (dim_out x dim_lat)
+    μu     = rand(dim_in) .* collect(1:dim_in)                                                                  # size (dim_in x 1)
+    Σu     = input_noise  .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in))))      # size (dim_in x dim_in)
+    Σy     = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out))))   # size (dim_out x dim_out)
+    Wu     = inv(Σu)
+    Wy     = inv(Σy)
+    
+    # return parameters
+    return A, B, C, μu, Σu, Σy, Wu, Wy
+
+end;
function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)
+        
+    # create random data generator
+    rng = StableRNG(seed)
+    
+    # preallocate space for variables
+    z = Vector{Vector{Float64}}(undef, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+    u = rand(rng, MvNormal(μu, Σu), nr_samples)'
+    
+    # set initial value of latent states
+    z_prev = zeros(size(A,1))
+    
+    # generate data
+    for i in 1:nr_samples
+
+        # generate new latent state
+        z[i] = A * z_prev + B * u[i,:]
+
+        # generate new observation
+        y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))
+        
+        # generate new observation
+        z_prev .= z[i]
+        
+    end
+    
+    # return generated data
+    return z, y, u
+    
+end
generate_data (generic function with 1 method)
# specify settings
+nr_samples = 200
+dim_out = 3
+dim_in = 3
+dim_lat = 25
+
+# generate parameters
+A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);
+            
+# generate data
+data_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);
+
+# visualise data
+p = Plots.plot(xlabel = "sample", ylabel = "observations")
+# plot each dimension independently
+for i in 1:dim_out
+    Plots.scatter!(p, getindex.(data_y, i), label = "y_$i", alpha = 0.5, ms = 2)
+end
+p

Model specification

@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+    
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    dim_out = size(C, 1)
+    
+    # initialize variables
+    z = randomvar(nr_samples)                 # hidden states (random variable)
+    u = randomvar(nr_samples)                 # inputs (random variable)
+    y = datavar(Vector{Float64}, nr_samples)  # outputs (observed variables)
+    
+    # set initial hidden state
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    
+    # update last/previous hidden state
+    z_prev = z_prior
+
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i] ~ MvNormalMeanPrecision(μu, Wu)
+        
+        # specify updated hidden state
+        z[i] ~ A * z_prev + B * u[i]
+        
+        # specify observation
+        y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+end
@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    
+    # initialize variables
+    z  = randomvar(nr_samples)                  # latent states
+    yt = randomvar(nr_samples)                  # latent observations
+    y  = datavar(Vector{Float64}, nr_samples)   # actual observations
+    u  = randomvar(nr_samples)                  # inputs
+    
+    # set priors
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    z_tmp   ~ BIFMHelper(z_prior) where { q = MeanField() }
+    
+    # update last/previous hidden state
+    z_prev = z_tmp
+    
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i]   ~ MvNormalMeanPrecision(μu, Wu)
+
+        # specify observation
+        yt[i]  ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }
+        y[i]   ~ MvNormalMeanPrecision(yt[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+    # set final value
+    z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))
+    
+end

Probabilistic inference

function inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+    
+    # In this task the inference is unstable and can diverge
+    meta = @meta begin 
+        *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)
+    end
+    
+    result = infer(
+        model      = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast()),
+        meta = meta
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_RTS (generic function with 1 method)
function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)
+    result = infer(
+        model      = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast())
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_BIFM (generic function with 1 method)

Experiments for 200 observations

z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+z_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);
ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state z")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state z")
+
+mz_RTS = mean.(z_RTS)
+mz_BIFM = mean.(z_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:5
+    Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state u")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state u")
+
+rdata_u = collect(eachrow(data_u))
+mu_RTS = mean.(u_RTS)
+mu_BIFM = mean.(u_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:1
+    Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

Benchmark

# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation
+# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`
+run_benchmark = false
+
+if run_benchmark
+    trials_range = 30
+    trials_n = 500
+    trials_RTS  = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+    trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+
+
+    @showprogress for k = 1 : trials_range
+
+        # generate parameters
+        local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);
+                    
+        # generate data|
+        local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);
+
+        # run inference
+        trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+        trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+
+    end
+
+    m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9
+    q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9
+    m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9
+    q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;
+
+    p = Plots.plot(ylabel = "duration [sec]", xlabel = "latent state dimension", title = "Benchmark", yscale = :log)
+    p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = "blue", label = "mean (RTS)")
+    p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = "orange", label = "mean (BIFM)")
+    Plots.savefig(p, "../pics/rts_bifm_benchmark.png")
+    p
+end

diff --git a/v2.16.0/examples/problem_specific/Simple Nonlinear Node/index.html b/v2.16.0/examples/problem_specific/Simple Nonlinear Node/index.html new file mode 100644 index 000000000..bc3fc72e5 --- /dev/null +++ b/v2.16.0/examples/problem_specific/Simple Nonlinear Node/index.html @@ -0,0 +1,67 @@ + +Simple Nonlinear Node · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Simple Nonlinear Node

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, StableRNGs

Here is an example of creating custom node with nonlinear function approximation with samplelist.

Custom node creation

struct NonlinearNode end # Dummy structure just to make Julia happy
+
+struct NonlinearMeta{R, F}
+    rng      :: R
+    fn       :: F   # Nonlinear function, we assume 1 float input - 1 float output
+    nsamples :: Int # Number of samples used in approximation
+end
@node NonlinearNode Deterministic [ out, in ]

We need to define two Sum-product message computation rules for our new custom node

  • Rule for outbound message on out edge given inbound message on in edge
  • Rule for outbound message on in edge given inbound message on out edge
  • Both rules accept optional meta object
# Rule for outbound message on `out` edge given inbound message on `in` edge
+@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin 
+    samples = rand(meta.rng, m_in, meta.nsamples)
+    return SampleList(map(meta.fn, samples))
+end
# Rule for outbound message on `in` edge given inbound message on `out` edge
+@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin     
+    return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))
+end

Model specification

After we have defined our custom node with custom rules we may proceed with a model specification:

\[\begin{aligned} +p(\theta) &= \mathcal{N}(\theta|\mu_{\theta}, \sigma_{\theta}),\\ +p(m) &= \mathcal{N}(\theta|\mu_{m}, \sigma_{m}),\\ +p(w) &= f(\theta),\\ +p(y_i|m, w) &= \mathcal{N}(y_i|m, w), +\end{aligned}\]

Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable $\theta$ through a non-linear transformation $f$ to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of $\theta$. 

@model function nonlinear_estimation(n)
+    
+    θ ~ Normal(mean = 0.0, variance = 100.0)
+    m ~ Normal(mean = 0.0, variance = 1.0)
+    
+    w ~ NonlinearNode(θ)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = m, precision = w)
+    end
+    
+end
@constraints function nconstsraints(nsamples)
+    q(θ) :: SampleList(nsamples, LeftProposal())
+    q(w) :: SampleList(nsamples, RightProposal())
+    
+    q(θ, w, m) = q(θ)q(m)q(w)
+end
nconstsraints (generic function with 1 method)
@meta function nmeta(fn, nsamples)
+    NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)
+end
nmeta (generic function with 1 method)

Here we generate some data

nonlinear_fn(x) = abs(exp(x) * sin(x))
nonlinear_fn (generic function with 1 method)
seed = 123
+rng  = StableRNG(seed)
+
+niters   = 15 # Number of VMP iterations
+nsamples = 5_000 # Number of samples in approximation
+
+n = 500 # Number of IID samples
+μ = -10.0
+θ = -1.0
+w = nonlinear_fn(θ)
+
+data = rand(rng, NormalMeanPrecision(μ, w), n);
result = infer(
+    model = nonlinear_estimation(n),
+    meta =  nmeta(nonlinear_fn, nsamples),
+    constraints = nconstsraints(nsamples),
+    data = (y = data, ), 
+    initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),
+    returnvars = (θ = KeepLast(), ),
+    iterations = niters,  
+    showprogress = true
+)
Inference results:
+  Posteriors       | available for (θ)
θposterior = result.posteriors[:θ]
SampleList(Univariate, 5000)
using Plots, StatsPlots
+
+estimated = Normal(mean_std(θposterior)...)
+
+plot(estimated, title="Posterior for θ", label = "Estimated", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))
+vline!([ θ ], label = "Real value of θ")

diff --git a/v2.16.0/examples/problem_specific/Universal Mixtures/index.html b/v2.16.0/examples/problem_specific/Universal Mixtures/index.html new file mode 100644 index 000000000..e115d0518 --- /dev/null +++ b/v2.16.0/examples/problem_specific/Universal Mixtures/index.html @@ -0,0 +1,94 @@ + +Universal Mixtures · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Universal Mixtures

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Distributions, Random, Plots

John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment

\[p(y_i \mid \theta) = \mathrm{Ber}(y_i \mid \theta),\]

where $y_i \in \{0,1\}$ are the outcomes of the coin tosses, i.e. heads or tails, and where $\theta$ is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter $\theta$, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of $\theta\in[0,1]$ they come up with the prior beliefs:

\[p(\theta \mid \text{John}) = \mathrm{Beta}(\theta \mid 7, 2)\]

\[p(\theta \mid \text{Jane}) = \mathrm{Beta}(\theta \mid 2, 7)\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior beliefs")
+plot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label="P(θ) John", c=1)
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="p(θ) Jane", c=3,)

John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. 

true_coin = Bernoulli(0.25)
+nr_throws = 10
+dataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))
+nr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)
+println("experimental outcome: \n - heads: ", nr_heads, "\n - tails: ", nr_tails);
experimental outcome: 
+ - heads: 3
+ - tails: 7

For computing the posterior beliefs $p(\theta \mid y)$ about the parameter $\theta$, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:

John's model:

\[p(y, \theta \mid \text{John}) = p(\theta \mid \text{John}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_john(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's prior model over θ
+    θ ~ Beta(7.0, 2.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Jane's model:

\[p(y, \theta \mid \text{Jane}) = p(\theta \mid \text{Jane}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_jane(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify Jane's prior model over θ
+    θ ~ Beta(2.0, 7.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy $\mathrm{F}_B$ bounds the model evidence $p(y)$ as

\[\mathrm{F}_B[p,q] \geq - \ln p(y)\]

result_john = infer(
+    model = beta_model_john(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true,
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[8.96366]
result_jane = infer(
+    model = beta_model_jane(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[6.63988]

From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying $\theta$ parameter. They formulate this through the posterior distributions $p(\theta \mid y, \text{John})$ and $p(\theta \mid y, \text{Jane})$:

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior beliefs")
+plot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) John", c=1)
+plot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="p(θ|y) Jane", c=3,)

What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over $\theta$, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as

\[p(y, \theta, c \mid \text{Mary}) = p(c \mid \text{Mary}) \, p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} \prod_{i=1}^N p(y_i \mid \theta),\]

where $c$ describes the probability of John being correct as

\[p(c \mid \text{Mary}) = \mathrm{Ber}(c \mid 0.7)\]

The predictive distribution $p(\theta \mid \text{Mary})$ for $\theta$ (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over $c$ as

\[p(\theta \mid \text{Mary}) = \sum_{c\in\{0,1\}} p(c\mid\text{Mary}) p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} = 0.7 \cdot p(\theta \mid \text{John}) + 0.3 \cdot p(\theta \mid \text{Jane})\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior belief")
+plot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label="P(θ) Mary", c=1)
+plot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label="")
+plot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label="")

She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:

@model function beta_model_mary(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's and Jane's prior models over θ
+    θ_jane ~ Beta(2.0, 7.0)
+    θ_john ~ Beta(7.0, 2.0)
+
+    # specify initial guess as to who is right
+    john_is_right ~ Bernoulli(0.7) 
+
+    # specify mixture prior Distribution
+    θ ~ Mixture(john_is_right, (θ_jane, θ_john))
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

This Mixture node updates the belief over $c$ on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.

result_mary = infer(
+    model = beta_model_mary(nr_throws), 
+    data  = (y = dataset, ),
+    returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),
+    addons = AddonLogScale(),
+    postprocess = UnpackMarginalPostprocess(),
+)
Inference results:
+  Posteriors       | available for (john_is_right, θ_john, θ, θ_jane)

Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over $\theta$ also changed, and as expected the estimate from Jane was more prominent.

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior belief")
+plot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) Mary", c=1)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label="", c=3)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label="", c=3)

diff --git a/v2.16.0/examples/problem_specific/overview/index.html b/v2.16.0/examples/problem_specific/overview/index.html new file mode 100644 index 000000000..40d579d7a --- /dev/null +++ b/v2.16.0/examples/problem_specific/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Problem specific

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Problem specific examples contain specialized models and inference for various domains.

diff --git a/v2.16.0/index.html b/v2.16.0/index.html new file mode 100644 index 000000000..626ab43b9 --- /dev/null +++ b/v2.16.0/index.html @@ -0,0 +1,2 @@ + +Home · RxInfer.jl
GitHub

RxInfer

Julia package for automatic Bayesian inference on a factor graph with reactive message passing.

Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.

Package Features

  • User friendly syntax for specification of probabilistic models.
  • Automatic generation of message passing algorithms including
  • Support for hybrid models combining discrete and continuous latent variables.
  • Support for hybrid distinct message passing inference algorithm under a unified paradigm.
  • Factorisation and functional form constraints specification.
  • Evaluation of Bethe free energy as a model performance measure.
  • Schedule-free reactive message passing API.
  • High performance.
  • Scalability for large models with millions of parameters and observations.
  • Inference procedure is differentiable.
  • Easy to extend with custom nodes and message update rules.

Why RxInfer

Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a "variational Free Energy" cost function. For large models, manual derivation of these gradients might not be feasible, while automated "black-box" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.

RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different "what-if" scenarios and enables very efficient inference in specific cases.

Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.

How to get started?

Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.

Table of Contents

References

Ecosystem

The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:

  • ReactiveMP.jl - core package for efficient and scalable for reactive message passing
  • GraphPPL.jl - package for model and constraints specification
  • Rocket.jl - reactive programming tools

Index

diff --git a/v2.16.0/library/bethe-free-energy/index.html b/v2.16.0/library/bethe-free-energy/index.html new file mode 100644 index 000000000..899b9ebb5 --- /dev/null +++ b/v2.16.0/library/bethe-free-energy/index.html @@ -0,0 +1,2 @@ + +Bethe Free Energy · RxInfer.jl
GitHub

Bethe Free Energy implementation in RxInfer

The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.

Factorized model

Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, $y = (y_1, \dots, y_j, \dots, y_m)\,,$ and variables that can not be observed directly, also known as latent variables, $x = (x_1, \dots, x_i, \dots, x_n)\,.$ We then define a model that factorizes over consituent smaller factors (functions), as $f(y,x) = \prod_a f_a(y_a,x_a)\,.$

Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).

Variational Free Energy

The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, $F[q](\hat{y}) = \mathbb{E}_{q(x)}\left[\log \frac{q(x)}{f(y=\hat{y}, x)} \right]\,.$ A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.

The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.

Variational inference

The goal of variational inference is to find a variational distibution that minimizes the VFE, $q^{*}(x) = \arg\min_{q\in\mathcal{Q}} F[q](\hat{y})\,.$ This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.

For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.

Bethe approximation

Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.

A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, $q(x) \triangleq \frac{\prod_a q_a(x_a)}{\prod_i q_i(x_i)^{d_i - 1}}\,.$ The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.

The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.

The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.

Bethe Free Energy

The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as $F_B[q](\hat{y}) = \sum_a U_a[q_a](\hat{y}_a) - \sum_a H[q_a] + \sum_i (d_i - 1) H[q_i]\,.$ The first term of the BFE specifies an average energy, $U_a[q_a](\hat{y}_a) = -\mathbb{E}_{q_a(x_a)}\left[\log f_a(y_a=\hat{y}_a, x_a)\right]\,,$ which internalizes the factors of the model. The last two terms specify entropies.

Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.

For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.

For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.

Further reading

  • Pearl (1986) on the original foundations of Bayesian networks and belief propagation;
  • Yedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;
  • Dauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);
  • Senoz et al. (2021) on constraint manipulation and message passing on FFGs.
RxInfer.AbstractScoreObjective — Type
AbstractScoreObjective

Abstract type for functional objectives that can be used in the score function.

Note

score is defined in the ReactiveMP package.

source
RxInfer.BetheFreeEnergy — Type
BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)

Creates Bethe Free Energy values stream when passed to the score function.

source
RxInfer.apply_diagnostic_check — Function
apply_diagnostic_check(check, context, stream)

This function applies a check to the stream. Accepts optional context object for custom error messages.

source
diff --git a/v2.16.0/library/exported-methods/index.html b/v2.16.0/library/exported-methods/index.html new file mode 100644 index 000000000..d452b36bc --- /dev/null +++ b/v2.16.0/library/exported-methods/index.html @@ -0,0 +1,858 @@ + +Exported methods · RxInfer.jl
GitHub

Using methods from RxInfer

In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:

using RxInfer

A nice explanation about how modules/packages work in Julia can be found in the official documentation.

In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:

import RxInfer: mean

One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:

import RxInfer: mean as mean_from_rxinfer
+import Distributions: mean as mean_from_distributions
+
+mean_from_rxinfer === mean_from_distributions
true

Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.

# It is easier to let Julia resolve names automatically
+# Julia will not overwrite `mean` that is coming from both packages
+using RxInfer, Distributions
mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`
0.0
mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`
0.0

List of available methods

Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.

Note

Some exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.

foreach(println, names(RxInfer))
@autoupdates
+@average_energy
+@call_marginalrule
+@call_rule
+@constraints
+@logscale
+@marginalrule
+@meta
+@model
+@node
+@rule
+AND
+AR
+ARMeta
+ARsafe
+ARunsafe
+AbstractActor
+AbstractActorFactory
+AbstractApproximationMethod
+AbstractFormConstraint
+AbstractMStorage
+AbstractMessage
+AbstractMixtureModel
+AbstractMvNormal
+AbstractOperator
+AbstractPipelineStage
+AbstractSubject
+AbstractSubjectFactory
+AbstractSubscribable
+AbstractVariable
+Actor
+ActorProxy
+ActorSourceProxy
+ActorTrait
+Adam
+AdditiveCouplingLayer
+AddonDebug
+AddonLogScale
+AddonMemory
+Arcsine
+ArrayLikeVariate
+ArrayObservable
+AsapScheduler
+AsyncPipelineStage
+AsyncScheduler
+AutoProposal
+AutoVar
+Autoregressive
+AverageEnergy
+BIFM
+BIFMHelper
+BIFMMeta
+BaseActorTrait
+BayesBase
+BehaviorSubject
+BehaviorSubjectFactory
+Bernoulli
+BernoulliLogit
+Beta
+BetaBinomial
+BetaPrime
+BetheFreeEnergy
+BetheFreeEnergyCheckInfs
+BetheFreeEnergyCheckNaNs
+BetheFreeEnergyDefaultChecks
+BetheFreeEnergyDefaultMarginalSkipStrategy
+Binomial
+Biweight
+BufferActor
+CTMeta
+CTransition
+CVI
+CallableTeardownLogic
+Categorical
+Cauchy
+Chernoff
+Chi
+Chisq
+CholeskyVariate
+CircularKeepActor
+ClosedProd
+CompanionMatrix
+CompanionMatrixTransposed
+CompiledFlowModel
+CompletedObservable
+CompletionActor
+CompletionActorTrait
+CompositeFormConstraint
+CompositePipelineStage
+ConnectableObservable
+ConstVariable
+ConstantBaseMeasure
+ConstraintsSpecification
+Contingency
+Continuous
+ContinuousDistribution
+ContinuousMatrixDistribution
+ContinuousMultivariateDistribution
+ContinuousMultivariateLogPdf
+ContinuousTransition
+ContinuousTransitionMeta
+ContinuousUnivariateDistribution
+ContinuousUnivariateLogPdf
+Cosine
+CountingReal
+CustomProdStrategy
+DataVariable
+DefaultConstraints
+DefaultMeta
+DefaultPostprocess
+DeltaFn
+DeltaFnNode
+DeltaMeta
+Deterministic
+DiagNormal
+DiagNormalCanon
+DifferentialEntropy
+Dirac
+Dirichlet
+DirichletMultinomial
+DiscontinuePipelineStage
+Discrete
+DiscreteDistribution
+DiscreteMatrixDistribution
+DiscreteMultivariateDistribution
+DiscreteNonParametric
+DiscreteUniform
+DiscreteUnivariateDistribution
+Distribution
+Distributions
+Domain
+DoubleExponential
+EdgeworthMean
+EdgeworthSum
+EdgeworthZ
+EmptyPipelineStage
+Epanechnikov
+Erlang
+ErrorActor
+ErrorActorTrait
+Estimator
+Exponential
+ExponentialFamily
+ExponentialFamilyDistribution
+ExponentialFamilyDistributionAttributes
+ExtraArgumentInCompleteCall
+FDist
+FactorBoundFreeEnergy
+FactorGraphModel
+FactorNodeCreationOptions
+FactorNodesCollection
+FactorizedJoint
+FastCholesky
+FaultedObservable
+FirstNotFoundException
+FisherNoncentralHypergeometric
+Flow
+FlowMeta
+FlowModel
+FoldLeftProdStrategy
+FoldRightProdStrategy
+FormConstraintCheckEach
+FormConstraintCheckLast
+FormConstraintCheckPickDefault
+ForwardDiffGrad
+Frechet
+FullFactorisation
+FullNormal
+FullNormalCanon
+FunctionActor
+FunctionObservable
+GCV
+GCVMetadata
+Gamma
+GammaDistributionsFamily
+GammaInverse
+GammaMixture
+GammaMixtureNode
+GammaShapeRate
+GammaShapeScale
+GaussHermiteCubature
+GaussLaguerreQuadrature
+GaussianDistributionsFamily
+GaussianMeanPrecision
+GaussianMeanVariance
+GaussianMixture
+GaussianMixtureNode
+GaussianWeighteMeanPrecision
+GeneralizedExtremeValue
+GeneralizedPareto
+GenericProd
+Geometric
+GraphPPL
+Gumbel
+HalfNormal
+Hypergeometric
+IMPLY
+ImportanceSamplingApproximation
+IncludeAll
+InconsistentActorWithSubscribableDataTypesError
+InconsistentSourceActorDataTypesError
+InconsistentSourceOperatorDataTypesError
+InconsistentSubjectDataTypesError
+InferableOperator
+InferableOperatorTrait
+InferenceResult
+InputLayer
+InvalidActorTrait
+InvalidActorTraitUsageError
+InvalidMultipleTeardownLogicTraitUsageError
+InvalidOperatorTrait
+InvalidOperatorTraitUsageError
+InvalidSubjectTrait
+InvalidSubjectTraitUsageError
+InvalidSubscribableTrait
+InvalidSubscribableTraitUsageError
+InvalidTeardownLogic
+InvalidTeardownLogicTraitUsageError
+InverseGamma
+InverseGaussian
+InverseWishart
+IsoNormal
+IsoNormalCanon
+JohnsonSU
+JointGaussian
+JointNormal
+JointOrderStatistics
+KSDist
+KSOneSided
+KeepActor
+KeepEach
+KeepLast
+Kolmogorov
+Kumaraswamy
+LKJ
+LKJCholesky
+LabeledObservable
+LambdaActor
+Laplace
+LaplaceApproximation
+LastNotFoundException
+LazyObservable
+LeftProposal
+LeftTypedOperator
+LeftTypedOperatorTrait
+Levy
+LimitSubscribersGuard
+Lindley
+Linearization
+LinearizedProductOf
+LocationScale
+LogNormal
+LogUniform
+LoggerActor
+LoggerPipelineStage
+Logistic
+LogitNormal
+MAX_PREGENERATED_MSTORAGE_SIZE
+MILLISECONDS_IN_SECOND
+MLEstimator
+Marginal
+Marginalisation
+MatrixBeta
+MatrixDirichlet
+MatrixDistribution
+MatrixFDist
+MatrixNormal
+MatrixReshaped
+MatrixTDist
+Matrixvariate
+MeanField
+MeanParametersSpace
+MeanToNatural
+Message
+MetaSpecification
+MissingCreateActorFactoryImplementationError
+MissingDataArgumentInNextCall
+MissingErrorArgumentInErrorCall
+MissingOnCallImplementationError
+MissingOnCompleteImplementationError
+MissingOnErrorImplementationError
+MissingOnNextImplementationError
+MissingOnScheduledSubscribeImplementationError
+MissingOnSubscribeImplementationError
+MissingOnUnsubscribeImplementationError
+MissingOperatorRightImplementationError
+Mixture
+MixtureDistribution
+MixtureModel
+MixtureNode
+MomentMatching
+Multinomial
+Multivariate
+MultivariateDistribution
+MultivariateGaussianDistributionsFamily
+MultivariateMixture
+MultivariateNormal
+MultivariateNormalDistributionsFamily
+MvGaussianMeanCovariance
+MvGaussianMeanPrecision
+MvGaussianWeightedMeanPrecision
+MvLogNormal
+MvLogitNormal
+MvNormal
+MvNormalCanon
+MvNormalKnownCov
+MvNormalMeanCovariance
+MvNormalMeanPrecision
+MvNormalMeanScalePrecision
+MvNormalWeightedMeanPrecision
+MvNormalWishart
+MvTDist
+NANOSECONDS_IN_MILLISECOND
+NANOSECONDS_IN_SECOND
+NOT
+NaturalParametersSpace
+NaturalToMean
+NegativeBinomial
+NetworkObservable
+NeverObservable
+NextActor
+NextActorTrait
+NonConstantBaseMeasure
+NonMatrixDistribution
+NoncentralBeta
+NoncentralChisq
+NoncentralF
+NoncentralHypergeometric
+NoncentralT
+NoopPostprocess
+Normal
+NormalCanon
+NormalDistributionsFamily
+NormalGamma
+NormalInverseGaussian
+NormalMeanPrecision
+NormalMeanVariance
+NormalMixture
+NormalMixtureNode
+NormalWeightedMeanPrecision
+OR
+OperatorTrait
+OperatorsComposition
+OrderStatistic
+OverrideHandler
+PGeneralizedGaussian
+Pareto
+PendingScheduler
+PendingSubject
+PendingSubjectFactory
+PermutationLayer
+PermutationMatrix
+PlanarFlow
+PointMass
+Poisson
+PoissonBinomial
+PostponeScheduler
+PreserveTypeLeftProd
+PreserveTypeProd
+PreserveTypeRightProd
+Probit
+ProbitMeta
+ProdCVI
+Product
+ProductOf
+ProxyObservable
+PushEach
+PushEachBut
+PushNew
+PushNewBut
+PushStrategy
+QQPair
+RadialFlow
+RandomVariable
+RandomVariableCreationOptions
+Rayleigh
+ReactiveMP
+RealInterval
+RecentSubject
+RecentSubjectFactory
+ReplaySubject
+ReplaySubjectFactory
+Rician
+RightProposal
+RightTypedOperator
+RightTypedOperatorTrait
+Rocket
+RxInfer
+RxInferenceEngine
+RxInferenceEvent
+SampleList
+SampleListMeta
+Sampleable
+ScheduledSubscribable
+ScheduledSubscribableTrait
+Semicircle
+ServerActor
+SimpleSubscribableTrait
+SingleObservable
+Skellam
+SkewNormal
+SkewedExponentialPower
+SkipClamped
+SkipClampedAndInitial
+SkipInitial
+SoftDot
+Soliton
+SourceProxy
+StandardBasisVector
+Stochastic
+StorageActor
+StudentizedRange
+Subject
+SubjectFactory
+SubjectTrait
+Subscribable
+SubscribableTrait
+SubstituteHandler
+SufficientStats
+SymTriangularDist
+SyncActor
+SyncActorTimedOutException
+SyncFileObservable
+TDist
+TapAfterSubscription
+TapAfterUnsubscription
+TapBeforeSubscription
+TapBeforeUnsubscription
+Teardown
+TeardownLogic
+TerminalProdArgument
+TimerObservable
+Transition
+TriangularDist
+Triweight
+Truncated
+TruncatedNormal
+TypedOperator
+TypedOperatorTrait
+UT
+Uniform
+Uninformative
+Univariate
+UnivariateDistribution
+UnivariateGMM
+UnivariateGaussianDistributionsFamily
+UnivariateMixture
+UnivariateNormalDistributionsFamily
+UnpackMarginalPostprocess
+Unscented
+UnscentedTransform
+UnspecifiedConstraints
+UnspecifiedDimension
+UnspecifiedDomain
+UnspecifiedFormConstraint
+UnspecifiedMeta
+UnsubscribableTeardownLogic
+ValidSubjectTrait
+ValueSupport
+VariableBoundEntropy
+VariablesCollection
+VariateForm
+VariationalMessage
+VoidActor
+VoidTeardown
+VoidTeardownLogic
+VonMises
+VonMisesFisher
+WalleniusNoncentralHypergeometric
+Weibull
+Wishart
+WishartDistributionsFamily
+ZeroMeanDiagNormal
+ZeroMeanDiagNormalCanon
+ZeroMeanFullNormal
+ZeroMeanFullNormalCanon
+ZeroMeanIsoNormal
+ZeroMeanIsoNormalCanon
+accumulated
+actor_extract_type
+actor_proxy!
+apply_pipeline_stage
+approximation_name
+approximation_short_name
+as_actor
+as_marginal
+as_message
+as_operator
+as_subject
+as_subscribable
+as_teardown
+as_variable
+async
+basemeasure
+buffer
+call_operator!
+call_operator_composition!
+canonform
+catch_error
+ccdf
+cdf
+censored
+cf
+cgf
+cholinv
+cholinv_logdet
+chollogdet
+cholsqrt
+circularkeep
+circvar
+clamplog
+collectLatest
+combineLatest
+combineLatestUpdates
+compile
+complete!
+completed
+component
+components
+componentwise_logpdf
+componentwise_pdf
+compute_logscale
+concat
+concat_map
+concat_map_to
+concentration
+connect
+connectable
+constrain_form
+constvar
+convert_paramfloattype
+convolve
+cor
+count
+cov
+cquantile
+create_actor
+create_model
+create_subject
+datavar
+debounce_time
+deep_eltype
+default_form_check_strategy
+default_if_empty
+default_prod_constraint
+default_prod_rule
+defer
+degree
+delay
+diageye
+dim
+dimension
+discontinue
+distribution_typewrapper
+dof
+dot
+dtanh
+entropy
+enumerate
+error!
+error_if
+error_if_empty
+error_if_not
+estimate
+exhaust_map
+expected_logdet
+factorisation
+failprob
+fastcholesky
+fastcholesky!
+faulted
+file
+filter
+filter_type
+find
+find_index
+first
+fisherinformation
+fit
+fit_mle
+from
+functional_dependencies
+functionalform
+fuse_supports
+generate
+getapproximation
+getattributes
+getbasemeasure
+getconditioner
+getconst
+getconstant
+getconstraints
+getdata
+getfisherinformation
+getlayers
+getlogpartition
+getlogscale
+getmapping
+getmarginal
+getmarginals
+getmemory
+getmeta
+getmodel
+getnaturalparameters
+getnode_ids
+getnodes
+getoptions
+getprediction
+getpredictions
+getrandom
+getsufficientstatistics
+getsupport
+getvalues
+getvardict
+getvariables
+ghcubature
+gradlogpdf
+hasconstvar
+hasdatavar
+hasfinitesupport
+hasrandomvar
+huge
+ignore
+infer
+inference
+insupport
+interfaces
+interval
+invcov
+invlogccdf
+invlogcdf
+invscale
+is_clamped
+is_initial
+is_marginalisation
+is_moment_matching
+is_point_mass_form_constraint
+isbasemeasureconstant
+isbounded
+isconnected
+isdeterministic
+isequal_typeof
+isleptokurtic
+islowerbounded
+ismesokurtic
+isplatykurtic
+isprobvec
+isproper
+isstochastic
+isupperbounded
+iterable
+keep
+kldivergence
+kurtosis
+labeled
+lambda
+laplace
+last
+lazy
+limit_subscribers
+localmarginalnames
+localmarginals
+location
+location!
+logccdf
+logcdf
+logdetcov
+logdiffcdf
+logger
+loglikelihood
+logmvbeta
+logpartition
+logpdf
+logpdf!
+logpdf_optimized
+logpdf_sampling_optimized
+lowercase
+make
+make_form_constraint
+make_node
+map
+map_to
+marginalrule
+max
+mean
+mean_cov
+mean_invcov
+mean_precision
+mean_std
+mean_var
+meandir
+meanform
+meanlogx
+median
+merge_map
+merged
+metadata
+mgf
+min
+mirrorlog
+mode
+model_name
+modes
+moment
+multicast
+mvtrigamma
+name
+ncategories
+ncomponents
+network
+never
+next!
+noop
+nr_params
+nsamples
+ntrials
+of
+on_call!
+on_complete!
+on_error!
+on_next!
+on_subscribe!
+on_unsubscribe!
+operator_right
+override
+pairwise
+parallel
+paramfloattype
+params
+params!
+partype
+pdf
+pdf!
+pdfsquaredL2norm
+precision
+probs
+probval
+probvec
+prod
+prod!
+product_distribution
+promote_paramfloattype
+promote_samplefloattype
+promote_sampletype
+promote_variate_type
+proxy
+publish
+publish_behavior
+publish_recent
+publish_replay
+qqbuild
+quantile
+race
+rand
+rand!
+randomvar
+rate
+reduce
+ref_count
+release!
+rerun
+resolve_prod_strategy
+rule
+rxinference
+safe
+sample
+sample!
+samplefloattype
+sampler
+sampletype
+sampling_optimized
+scale
+scale!
+scan
+schedule_on
+scheduled
+score
+sdtype
+server
+set!
+setTimeout
+setmarginal!
+setmarginals!
+setmessage!
+setmessages!
+shape
+share
+share_recent
+share_replay
+skewness
+skip_complete
+skip_error
+skip_next
+skipindex
+softdot
+some
+source_proxy!
+span
+sqmahal
+sqmahal!
+srcubature
+start_with
+std
+stdlogx
+storage
+subscribable_extract_type
+subscribe!
+substitute
+succprob
+sufficientstatistics
+suffstats
+sum
+support
+switch_map
+switch_map_to
+sync
+take
+take_until
+tap
+tap_on_complete
+tap_on_subscribe
+tap_on_unsubscribe
+teardown!
+throwError
+timer
+tiny
+to_array
+truncated
+tuple_with_left
+tuple_with_right
+unsubscribe!
+update!
+uppercase
+vague
+value_support
+var
+variate_form
+varlogx
+void
+voidTeardown
+weightedmean
+weightedmean_cov
+weightedmean_invcov
+weightedmean_precision
+weightedmean_std
+weightedmean_var
+weights
+with_latest
+wsample
+wsample!
+xtlog
+zipped
diff --git a/v2.16.0/library/functional-forms/index.html b/v2.16.0/library/functional-forms/index.html new file mode 100644 index 000000000..e8c82b461 --- /dev/null +++ b/v2.16.0/library/functional-forms/index.html @@ -0,0 +1,26 @@ + +Built-in functional form constraints · RxInfer.jl
GitHub

Built-in Functional Forms

This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.

Custom functional forms

See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.

UnspecifiedFormConstraint

Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.

@constraints begin 
+    q(x) :: Nothing # This is the default setting
+end

PointMassFormConstraint

The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. 

@constraints begin 
+    q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object
+end
RxInfer.PointMassFormConstraint — Type
PointMassFormConstraint

One of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.

Keyword arguments

  • optimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer
  • starting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point
  • boundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries

Custom optimizer callback interface

# This is an example of the `custom_optimizer` interface
+function custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # should return argmin of the -logpdf(distribution)
+end

Custom starting point callback interface

# This is an example of the `custom_starting_point` interface
+function custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # built-in optimizer expects an array, even for a univariate distribution
+    return [ 0.0 ] 
+end

Custom boundaries callback interface

# This is an example of the `custom_boundaries` interface
+function custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # returns a tuple of `lower` and `upper` boundaries
+    return (-Inf, Inf)
+end

Traits

  • is_point_mass_form_constraint = true
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = PointMass (for use in @constraints macro)
source

SampleListFormConstraint

SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.

@constraints begin 
+    q(x) :: SampleList(1000)
+    # or 
+    q(y) :: SampleList(1000, LeftProposal())
+end
RxInfer.SampleListFormConstraint — Type
SampleListFormConstraint(rng, strategy, method)

One of the form constraint objects. Approximates DistProduct with a SampleList object.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = SampleList (for use in @constraints macro)
source
RxInfer.LeftProposal — Type

Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.

source
RxInfer.RightProposal — Type

Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.

source

FixedMarginalFormConstraint

Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.

@constraints function block_updates(x_posterior = nothing) 
+    # `nothing` returns the computed posterior marginal
+    q(x) :: Marginal(x_posterior)
+end
RxInfer.FixedMarginalFormConstraint — Type
FixedMarginalFormConstraint

One of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = Marginal (for use in @constraints macro)
source

CompositeFormConstraint

It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:

form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()
@constraints begin 
+    q(x) :: SampleList(1000) :: PointMass()
+end
diff --git a/v2.16.0/library/model-specification/index.html b/v2.16.0/library/model-specification/index.html new file mode 100644 index 000000000..1a2bb33ce --- /dev/null +++ b/v2.16.0/library/model-specification/index.html @@ -0,0 +1,4 @@ + +Model specification · RxInfer.jl
GitHub

Model specification in RxInfer

RxInfer.@model — Macro
@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model description
+end

@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.

Supported alias in the model specification

  • a || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).
  • a && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • a -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • ¬a and !a: alias for NOT(a) node (Unicode \neg, operator precedence ||, &&, -> and ! is the same as in Julia).
  • a + b + c: alias for (a + b) + c
  • a * b * c: alias for (a * b) * c
  • Normal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.
  • Normal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.
  • MvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • Gamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.
  • Gamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.
source
RxInfer.ModelGenerator — Type
ModelGenerator

ModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.

See also: infer

source
RxInfer.create_model — Function
create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)

Creates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.

Returns a tuple of 2 values:

    1. an instance of FactorGraphModel
    1. return value from the @model macro function definition
source
RxInfer.ModelInferenceOptions — Type
ModelInferenceOptions(; kwargs...)

Creates model inference options object. The list of available options is present below.

Options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.
  • warn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.

Advanced options

  • pipeline: changes the default pipeline for each factor node in the graph
  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

See also: infer

source
diff --git a/v2.16.0/manuals/background/index.html b/v2.16.0/manuals/background/index.html new file mode 100644 index 000000000..443a5abe6 --- /dev/null +++ b/v2.16.0/manuals/background/index.html @@ -0,0 +1,2 @@ + +Background: variational inference · RxInfer.jl
GitHub
diff --git a/v2.16.0/manuals/comparison/index.html b/v2.16.0/manuals/comparison/index.html new file mode 100644 index 000000000..454ac9322 --- /dev/null +++ b/v2.16.0/manuals/comparison/index.html @@ -0,0 +1,28 @@ + +RxInfer.jl vs. Others · RxInfer.jl
GitHub

Comparison to other packages

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.

DISCLAIMER:

  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, and we'll be more than willing to rectify.
  2. The comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.
ToolboxUniversalityEfficiencyExpressivenessDebugging & VisualizationModularityInference EngineLanguageCommunity & Ecosystem
RxInfer.jl~✓✓~✗Message-passingJulia✗
ForneyLab.jl✗~✗~✗Message-passingJulia✗
Infer.net~✓✗✓✗Message-passingC#✗
PGMax✗✓✗✓✗Message-passingPython✗
Turing.jl✓✗✓~✗SamplingJulia✓
PyMC✓✗✓✓✗SamplingPython✓
NumPyro✓✓~✓✗SamplingPython✓
TensorFlow Probability✓✗~✓✗SamplingPython✓
Stan✓✗✓✓✗SamplingStan✓

(Date of creation: 20/10/2023)

Legend

  • ✓ : Full capability or feature is present.
  • ~ : Partial capability or feature is present.
  • ✗ : No capability or feature.

Notes:

  • Universality: Denotes the capability to depict a vast array of probabilistic models.
  • Efficiency: Highlights computational competence. A "–" in this context suggests perceived slowness.
  • Expressiveness: Assesses the ability to concisely formulate intricate probabilistic models.
  • Debugging & Visualization: Evaluates the suite of tools for model debugging and visualization.
  • Modularity: Reflects the potential to create models by integrating smaller models.
  • Inference Engines: Pinpoints the primary inference strategy employed by the toolbox.
  • Language: Identifies the programming language integral to the toolbox.
  • Community & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.

RxInfer.jl breakdown

  • Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.

  • Efficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.

  • Modularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:

@model function inner_inner(τ, y)
+    y ~ Normal(τ[1], τ[2])
+end
+
+@model function inner(θ, α)
+    β ~ Normal(0, 1)
+    α ~ Gamma(β, 1)
+    α ~ inner_inner(τ = θ)
+end
+
+@model function outer()
+    local w
+    for i = 1:5
+        w[i] ~ inner(θ = Gamma(1, 1))
+    end
+    y ~ inner(θ = w[2:3])
+end
  • Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(0.0, 1.0)\\ + w & \sim \mathrm{InverseGamma}(1.0, 1.0)\\ + y & \sim \mathrm{Normal}(x, w) +\end{aligned}\]

The model then is expressed in RxInfer.jl as follows:

using RxInfer
+
+@model function example_model()
+    x ~ Normal(mean=0.0, var=1.0)
+    w ~ InverseGamma(α = 1, θ = 1)
+    y ~ Normal(mean = x, var = w)
+end
  • Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.
diff --git a/v2.16.0/manuals/constraints-specification/index.html b/v2.16.0/manuals/constraints-specification/index.html new file mode 100644 index 000000000..eb98d2d42 --- /dev/null +++ b/v2.16.0/manuals/constraints-specification/index.html @@ -0,0 +1,111 @@ + +Constraints specification · RxInfer.jl
GitHub

Constraints Specification

RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.

using RxInfer

General syntax

@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:


+# `functional` style
+@constraints function create_my_constraints(arg1, arg2)
+    ...
+end
+
+# `block` style
+myconstraints = @constraints begin 
+    ...
+end
+

In the first case it returns a function that return constraints upon calling, e.g. 

@constraints function make_constraints(mean_field)
+    q(x) :: PointMass
+
+    if mean_field
+        q(x, y) = q(x)q(y)
+    end
+end
+
+myconstraints = make_constraints(true)
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

and in the second case it evaluates automatically and returns constraints object directly.

myconstraints = @constraints begin
+    q(x) :: PointMass
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

Options specification

@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

myconstraints = @constraints [ warn = false ] begin 
+   ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/constraints specification

Marginal and messages form constraints

To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)

The following constraint:

@constraints begin
+    q(x) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:

\[\mathrm{approximate~} q(x) = \frac{\overrightarrow{\mu}(x)\overleftarrow{\mu}(x)}{\int \overrightarrow{\mu}(x)\overleftarrow{\mu}(x) \mathrm{d}x}\mathrm{~as~PointMass}\]

Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):

@constraints begin
+    q(x) :: PointMass
+    μ(x) :: SampleList(1000)
+    # it is possible to assign different form constraints on the same variable
+    # both for the marginal and for the messages
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+    μ(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) [ prod_constraint = GenericProd() ]
+  factorisation:
+Options:
+  warn = true
+

@constraints macro understands "stacked" form constraints. For example the following form constraint

@constraints begin
+    q(x) :: SampleList(1000) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass.

Note

Not all combinations of "stacked" form constraints are compatible between each other.

You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.

Factorisation constraints on posterior distribution q()

@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:

For example:

@constraints begin
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.

@constraints begin
+    q(x) = q(x[begin])..q(x[end])
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x) = q(x[(begin)..(end)])
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables $x_i$.

Note

@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])

It is possible to write more complex factorisation constraints, for example:

@constraints begin
+    q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x[(begin)..(end)], y[(begin)..(end)])
+Options:
+  warn = true
+

specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is

@constraints function make_constraints(k)
+    q(x) = q(x[begin:k])q(x[k+1:end])
+end
make_constraints (generic function with 1 method)

In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end].

To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+constraints = @constraints begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); constraints = constraints)

Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument.

diff --git a/v2.16.0/manuals/custom-node/70ad343c.svg b/v2.16.0/manuals/custom-node/70ad343c.svg new file mode 100644 index 000000000..3b7252ac3 --- /dev/null +++ b/v2.16.0/manuals/custom-node/70ad343c.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/custom-node/index.html b/v2.16.0/manuals/custom-node/index.html new file mode 100644 index 000000000..836af3d6c --- /dev/null +++ b/v2.16.0/manuals/custom-node/index.html @@ -0,0 +1,86 @@ + +Defining a custom node and rules · RxInfer.jl
GitHub

Creating your own custom nodes

Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.

To create a custom node in RxInfer, 4 steps are required:

  1. Create your custom node in RxInfer using the @node macro.
  2. Define the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.
  3. Specify computations for marginal distributions of the relevant variables with the @marginalrule macro.
  4. Implement the computation of the Free Energy in a node with the @average_energy macro.

Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!

Problem statement

Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin $K=20$ times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment $x_k\in\{0,1\}$ using the Bernoulli distribution as

\[p(x_k \mid \pi) = \mathrm{Ber}(x_k \mid \pi) = \pi^{x_k} (1-\pi)^{1-x_k},\]

where $\pi \in[0,1]$ denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of $\pi$ which she models using the Beta distribution as

\[p(\pi) = \mathrm{Beta}(\pi \mid 4, 8).\]

With this prior belief, the total probabilistic model that she has for this experiment is given by

\[p(x_{1:K}, \pi) = p(\pi) \prod_{k=1}^K p(x_k \mid \pi).\]

Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of $\pi$, $p(\pi \mid x_{1:K})$, denoting how $\pi$ is distributed after we have seen the data.

Step 1: Creating the custom node

Note

In this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.

First things first, let's import RxInfer:

using RxInfer

In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:

  1. The name of the node. (::Type)
  2. Whether the node is Deterministic or Stochastic.
  3. The interfaces of the node and any potential aliases. (::Vector)

For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as

# struct for Bernoulli distribution with success probability π
+struct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution
+    π :: T
+    new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError("π must be between 0 and 1"))
+end
+
+# for simplicity, let's also specify the mean of the distribution
+Distributions.mean(d::MyBernoulli) = d.π

In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.

Note

You can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)

For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of $\pi$, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.

The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.

Concluding, we can create the MyBernoulli factor node as

@node MyBernoulli Stochastic [out, (π, aliases = [p])]

Cool! Step 1 is done, we have created a custom node.

Step 2: Defining rules for our node

In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as $p(\pi\mid x_{1:K})$, we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.

Sum-product message passing update rules

In sum-product message passing we compute outgoing messages to our node as

\[\vec{\mu}(x) \propto \int \mathrm{Ber}(x\mid \pi) \vec{\mu}(\pi) \mathrm{d}x\]

\[\overleftarrow{\mu}(\pi) \propto \sum_{x \in \{0,1\}} \mathrm{Ber}(x\mid \pi) \overleftarrow{\mu}(x)\]

This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.

For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain $\pi = \frac{\alpha}{\alpha + \beta}$, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as

@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))

Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for "the incoming message on interface π". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.

The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):

@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))

Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:

\[\overleftarrow{\mu}(π) \propto \mathrm{Beta}(1 + x, 2 - x)\]

Which gives us the following update rule:

@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin
+    p = mean(m_out)
+    Beta(one(p) + p, 2one(p) - p)
+end

Variational message passing update rules

We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as

\[\vec{\nu}(x) \propto \exp \int q(\pi) \ln \mathrm{Ber}(x\mid \pi) \mathrm{d}x\]

\[\overleftarrow{\nu}(\pi) \propto \exp \sum_{x \in \{0,1\}} q(x) \ln \mathrm{Ber}(x\mid \pi)\]

These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.

#rules towards out
+@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))
+
+@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin
+    rho_1 = mean(log, q_π)          # E[ln(x)]
+    rho_2 = mean(mirrorlog, q_π)    # E[log(1-x)]
+    m = max(rho_1, rho_2)
+    tmp = exp(rho_1 - m)
+    p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))
+    return Bernoulli(p)
+end
+
+#rules towards π
+@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin
+    p = mean(q_out)
+    return Beta(one(p) + p, 2one(p) - p)
+end
Node

Typically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.

In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.

Step 3: Defining joint marginals for our node

The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by

\[F[q,f] = - \sum_{a\in\mathcal{V}} \mathrm{H}[q_a(s_a)] - \sum_{a\in\mathcal{V}}\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)] + \sum_{i\in\mathcal{E}}\mathrm{H}[q_i(s_i)]\]

Here we call $q_a(s_a)$ the joint marginals around a node and $-\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)]$ we term the average energy.

In order to be able to compute the Bethe free energy, we need to first describe how to compute $q_a(s_a)$, defined in our case as

\[q(x_k, \pi) = \vec{\mu}(\pi) \overleftarrow{\mu}(x_k) \mathrm{Ber}(x_k \mid \pi)\]

To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:

@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin
+    r = mean(m_out)
+    p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)
+    return (out = m_out, p = p)
+end

In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as $q(x_k, \pi) = q(x_k)q(\pi)$. These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing $q(\pi)$ we need to compute the product $\vec{\mu}(\pi)\overleftarrow{\mu}(\pi)$. We already know how $\overleftarrow{\mu}(\pi)$ looks like from the previous step, so we can just use the prod function.

Step 4: Defining the average energy for our node

To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as $-\mathrm{E}_{q(x_k, \pi)}[\ln p(x_k \mid \pi)]$, however, because we know that we observe $x_k$ and therefore $q(x_k, \pi)$ factorizes, we can instead compute $\begin{aligned} -\mathrm{E}_{q(x_k)q(\pi)}[\ln p(x_k \mid \pi)] &= -\mathrm{E}_{q(x_k)q(\pi)} [\ln (\pi^{x_k} (1-\pi)^{1 - x_k})] \\ +&= -\mathrm{E}_{q(x_k)q(\pi)} [x_k \ln(\pi) + (1-x_k) \ln(1-\pi)] \\ +&= -\mathrm{E}_{q(x_k)}[x_k] \mathrm{E}_{q(\pi)} [\ln(\pi)] - (1-\mathrm{E}_{q(x_k)}[x_k]) \mathrm{E}_{q(\pi)}[\ln(1-\pi)] \end{aligned}$

Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to $\mathrm{E}_{q(x)}[1-\log{x}]$.

@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)

In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....

Using our node in a model

With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:

using Random
+
+rng = MersenneTwister(42)
+n = 500
+π_real = 0.75
+distribution = Bernoulli(π_real)
+
+dataset = float.(rand(rng, distribution, n))

Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:

@model function coin_model_mybernoulli(n)
+
+    # `datavar` creates data 'inputs' in our model
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    π ~ Beta(4.0, 8.0)
+
+    # We assume that outcome of each coin flip is governed by the MyBernoulli distribution
+    for i in 1:n
+        y[i] ~ MyBernoulli(π)
+    end
+
+end

Finally, we can run inference with this model and the generated dataset:

result_mybernoulli = infer(
+    model = coin_model_mybernoulli(length(dataset)),
+    data  = (y = dataset, ),
+)
Inference results:
+  Posteriors       | available for (π)
+

We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.

using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label="p(π|x)", c=3)
+vline!([π_real], label="Real π")
Example block output

As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.

@model function coin_model(n)
+
+    y = datavar(Float64, n)
+    p ~ Beta(4.0, 8.0)
+
+    for i in 1:n
+        y[i] ~ Bernoulli(p)
+    end
+
+end
+
+result_bernoulli = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, ),
+)
+
+if !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])
+    error("Results are not identical")
+else
+    println("Results are identical 🎉🎉🎉")
+end
Results are identical 🎉🎉🎉

Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.

diff --git a/v2.16.0/manuals/debugging/2d54fd36.svg b/v2.16.0/manuals/debugging/2d54fd36.svg new file mode 100644 index 000000000..4965b0997 --- /dev/null +++ b/v2.16.0/manuals/debugging/2d54fd36.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/debugging/b7380703.svg b/v2.16.0/manuals/debugging/b7380703.svg new file mode 100644 index 000000000..7d0e9a382 --- /dev/null +++ b/v2.16.0/manuals/debugging/b7380703.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/debugging/index.html b/v2.16.0/manuals/debugging/index.html new file mode 100644 index 000000000..74583e5fa --- /dev/null +++ b/v2.16.0/manuals/debugging/index.html @@ -0,0 +1,60 @@ + +Debugging · RxInfer.jl
GitHub

Debugging

Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. 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

We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a "Memory Addon". Below is an example explaining how you can extract this history and use it to fix a bug.

Consider the coin toss example from earlier in the documentation. We model the binary outcome $x$ (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the $\theta$ parameter, with a known shape 𝑎 and rate 𝑏 parameter.

\[x_i \sim \mathrm{Bernoulli}(\theta)\]

\[\theta \sim \mathrm{Beta}(a, b)\]

where $x_i \in {0, 1}$ are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:

using RxInfer, Random, Plots
+
+n = 4
+θ_real = 0.3
+dataset = convert.(Int64, rand(Bernoulli(θ_real), n))
+
+@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, huge)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+

The model will run without errors. But when we plot the posterior distribution for $\theta$, something's wrong. The posterior seems to be a flat distribution:

rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+    addons = (AddonMemory(),)
+)
Inference results:
+  Posteriors       | available for (θ)
+

Now we have access to the messages that led to the marginal posterior:

Addons_messages

The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:

\[\underbrace{\overrightarrow{\mu}_{θ}(θ)}_{\substack{ \text{outgoing}\\ \text{message}}} = \sum_{x_1,\ldots,x_n} \underbrace{\overrightarrow{\mu}_{X_1}(x_1)\cdots \overrightarrow{\mu}_{X_n}(x_n)}_{\substack{\text{incoming} \\ \text{messages}}} \cdot \underbrace{f(θ,x_1,\ldots,x_n)}_{\substack{\text{node}\\ \text{function}}}\]

Graph

Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of $\theta$ we used in the code block above. So why does the posterior have this rate parameter?

All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.

@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, 100)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+
rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

Now the posterior is visible in the plot.

diff --git a/v2.16.0/manuals/delta-node/index.html b/v2.16.0/manuals/delta-node/index.html new file mode 100644 index 000000000..b7f929c2b --- /dev/null +++ b/v2.16.0/manuals/delta-node/index.html @@ -0,0 +1,59 @@ + +Delta node · RxInfer.jl
GitHub

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.

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:

  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.
  3. Stacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.

The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:

MethodsGaussian NodesExponential Family NodesStacking Delta Nodes
Linearization✓✗✓
Unscented✓✗✓
CVI✓✓✗

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.

For clarity, consider the following example:

using RxInfer
+
+@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=0.0, var=1.0)
+    y ~ tanh(x)
+    z ~ Normal(mean=y, var=1.0)
+end

To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:

delta_meta = @meta begin
+    tanh() -> Linearization()
+end
Meta specification:
+  tanh() -> Linearization()
+Options:
+  warn = true

or

delta_meta = @meta begin
+    tanh() -> Unscented()
+end
Meta specification:
+  tanh() -> Unscented{Float64, Float64, Float64, Nothing}(0.001, 2.0, 0.0, nothing)
+Options:
+  warn = true

For a deeper understanding of the Unscented method and its parameters, consult the docstrings.

Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:

delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)
+end
Meta specification:
+  tanh() -> DeltaMeta{Linearization, typeof(atanh)}(Linearization(), atanh)
+Options:
+  warn = true

To execute the inference procedure:

infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))
Inference results:
+  Posteriors       | available for (y, x)
+

This methodology is consistent even when the delta node is associated with multiple nodes. For instance:

f(x, g) = x*tanh(g)
f (generic function with 1 method)
@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=1.0, var=1.0)
+    g ~ Normal(mean=1.0, var=1.0)
+    y ~ f(x, g)
+    z ~ Normal(mean=y, var=0.1)
+end

The corresponding meta specification is:

delta_meta = @meta begin
+    f() -> DeltaMeta(method = Linearization())
+end
Meta specification:
+  f() -> DeltaMeta{Linearization, Nothing}(Linearization(), nothing)
+Options:
+  warn = true

or simply

delta_meta = @meta begin
+    f() -> Linearization()
+end
Meta specification:
+  f() -> Linearization()
+Options:
+  warn = true

If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:

delta_meta = @meta begin 
+    f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))
+end

Exponential Family Case

When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:

using RxInfer
+
+@model function delta_node_example1()
+    z = datavar(Float64)
+    x ~ Gamma(shape=1.0, rate=1.0)
+    y ~ tanh(x)
+    z ~ Bernoulli(y)
+end

The corresponding meta specification can be represented as:

using StableRNGs
+using Optimisers
+
+delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))
+end
Meta specification:
+  tanh() -> DeltaMeta{ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}, Nothing}(ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}(StableRNGs.LehmerRNG(state=0x00000000000000000000000000000055), 100, 100, Optimisers.Descent{Float64}(0.01), ForwardDiffGrad{0}(), 1, Val{true}(), true), nothing)
+Options:
+  warn = true

Consult the ProdCVI docstrings for a detailed explanation of these parameters.

diff --git a/v2.16.0/manuals/getting-started/23d0f401.svg b/v2.16.0/manuals/getting-started/23d0f401.svg new file mode 100644 index 000000000..7f06e368a --- /dev/null +++ b/v2.16.0/manuals/getting-started/23d0f401.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/getting-started/3475385f.svg b/v2.16.0/manuals/getting-started/3475385f.svg new file mode 100644 index 000000000..a91e18a41 --- /dev/null +++ b/v2.16.0/manuals/getting-started/3475385f.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/getting-started/index.html b/v2.16.0/manuals/getting-started/index.html new file mode 100644 index 000000000..17894b3cb --- /dev/null +++ b/v2.16.0/manuals/getting-started/index.html @@ -0,0 +1,91 @@ + +Getting started · RxInfer.jl
GitHub

Getting started

RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.

RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.

This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.

Installation

Install RxInfer through the Julia package manager:

] add RxInfer

Importing RxInfer

To add RxInfer package (and all associated packages) into a running Julia session simply run:

using RxInfer

Read more about about using in the Using methods from RxInfer section of the documentation.

Example: Inferring the bias of a coin

The RxInfer approach to solving inference problems consists of three phases:

  1. Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.
  2. Inference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.
  3. Inference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.

Coin flip simulation

Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).

First let's setup our environment by importing all needed packages:

using RxInfer, Distributions, Random

Next, let's define our dataset:

rng = MersenneTwister(42)
+n = 10
+p = 0.75
+distribution = Bernoulli(p)
+
+dataset = float.(rand(rng, Bernoulli(p), n))
10-element Vector{Float64}:
+ 1.0
+ 1.0
+ 1.0
+ 1.0
+ 0.0
+ 0.0
+ 1.0
+ 1.0
+ 0.0
+ 1.0

Model specification

In 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.

Likelihood

We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.

\[y_i \sim \mathrm{Bernoulli}(\theta),\]

where $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]$.

Prior

We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.

\[\theta \sim Beta(a, b),\]

where $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.

Joint probability

The joint probability is given by the multiplication of the likelihood and the prior, i.e.

\[P(y_{1:N}, θ) = P(θ) \prod_{i=1}^N P(y_i | θ).\]

Now let's see how to specify this model using GraphPPL's package syntax.

# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during inference step
+    return y, θ
+end

As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create "clamped" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Inference specification

Automatic inference specification

Once 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 inference function that supports static datasets.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
+
θestimated = result.posteriors[:θ]
Beta{Float64}(α=9.0, β=10.0)
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803

Read more information about the inference function in the Static Inference documentation section.

Manual inference specification

There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:

  1. Return variables of interests from model specification
  2. Subscribe on variables of interests posterior marginal updates
  3. Pass data to the model
  4. Unsubscribe

Here is an example of inference procedure:

function custom_inference(data)
+    n = length(data)
+
+    # `coin_model` function from `@model` macro returns a reference to the model generator object
+    # we need to use the `create_model` function to get actual model object
+    model, (y, θ) = create_model(coin_model(n))
+
+    # Reference for future posterior marginal
+    mθ = nothing
+
+    # `getmarginal` function returns an observable of future posterior marginal updates
+    # We use `Rocket.jl` API to subscribe on this observable
+    # As soon as posterior marginal update is available we just save it in `mθ`
+    subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)
+
+    # `update!` function passes data to our data inputs
+    update!(y, data)
+
+    # It is always a good practice to unsubscribe and to
+    # free computer resources held by the subscription
+    unsubscribe!(subscription)
+
+    # Here we return our resulting posterior marginal
+    return mθ
+end
custom_inference (generic function with 1 method)

Inference execution

Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.

θestimated = custom_inference(dataset)
Marginal(Beta{Float64}(α=9.0, β=10.0))
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title="Prior", fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+p2 = plot(rθ, (x) -> pdf(θestimated, x), title="Posterior", fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+
+plot(p1, p2, layout = @layout([ a; b ]))
Example block output

In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:

dataset_100   = float.(rand(rng, Bernoulli(p), 100))
+dataset_1000  = float.(rand(rng, Bernoulli(p), 1000))
+dataset_10000 = float.(rand(rng, Bernoulli(p), 10000))
θestimated_100   = custom_inference(dataset_100)
+θestimated_1000  = custom_inference(dataset_1000)
+θestimated_10000 = custom_inference(dataset_10000)
p3 = plot(title = "Posterior", legend = :topleft)
+
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_100)", c = 4)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_1000)", c = 5)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_10000)", c = 6)
+
+plot(p1, p3, layout = @layout([ a; b ]))
Example block output

With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.

println("mean: ", mean(θestimated_10000))
+println("std:  ", std(θestimated_10000))
mean: 0.7529223698671196
+std:  0.004310967761308469

Where to go next?

There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.

diff --git a/v2.16.0/manuals/inference/infer/index.html b/v2.16.0/manuals/inference/infer/index.html new file mode 100644 index 000000000..ef1fe2a1d --- /dev/null +++ b/v2.16.0/manuals/inference/infer/index.html @@ -0,0 +1,120 @@ + +Static vs Streamline inference · RxInfer.jl
GitHub

Automatic Inference Specification

RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors.

It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.

For details on manual inference specification, see the Manual Inference section.

RxInfer.infer — Function
infer(
+    model; 
+    data = nothing,
+    datastream = nothing,
+    autoupdates = nothing,
+    initmarginals = nothing,
+    initmessages = nothing,
+    constraints = nothing,
+    meta = nothing,
+    options = nothing,
+    returnvars = nothing, 
+    predictvars = nothing, 
+    historyvars = nothing,
+    keephistory = nothing,
+    iterations = nothing,
+    free_energy = false,
+    free_energy_diagnostics = BetheFreeEnergyDefaultChecks,
+    showprogress = false,
+    callbacks = nothing,
+    addons = nothing,
+    postprocess = DefaultPostprocess(),
+    warn = true,
+    events = nothing,
+    uselock = false,
+    autostart = true,
+    catch_exception = false
+)

This function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.

Arguments

For more information about some of the arguments, please check below.

  • model: specifies a model generator, required
  • data: NamedTuple or Dict with data, required (or datastream or predictvars)
  • datastream: A stream of NamedTuple with data, required (or data)
  • autoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates
  • initmarginals = nothing: NamedTuple or Dict with initial marginals, optional
  • initmessages = nothing: NamedTuple or Dict with initial messages, optional
  • constraints = nothing: constraints specification object, optional, see @constraints
  • meta = nothing: meta specification object, optional, may be required for some models, see @meta
  • options = nothing: model creation options, optional, see ModelInferenceOptions
  • returnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information
  • predictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)
  • historyvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)
  • keephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)
  • iterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information
  • free_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl
  • free_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.
  • showprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)
  • catch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)
  • callbacks = nothing: inference cycle callbacks, optional, see below for more info
  • addons = nothing: inject and send extra computation information along messages, see below for more info
  • postprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info
  • events = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)
  • uselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)
  • autostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)
  • warn = true: enables/disables warnings

Note on NamedTuples

When passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.

The model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:

@model function coin_toss(some_argument, some_keyword_argument = 3)
+    ...
+end
+
+result = infer(
+    model = coin_toss(some_argument; some_keyword_argument = 3)
+)

Note: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.

  • data

Either data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.

Note: The behavior of the data keyword argument depends on the inference setting (batch or streamline).

The data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.

  • streamline setting

All entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.

  • datastream

The datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.

Note: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.

For specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as

infer(...
+    initmarginals = (
+        # initialize the marginal distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)
+
+This argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.
+
+- ### `initmessages`
+
+For specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as

julia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )

  • options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.

  • pipeline: changes the default pipeline for each factor node in the graph

  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

  • returnvars

returnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.

Batch inference:

  • Accepts a NamedTuple or Dict of return variable specifications.
  • Two specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).
  • When iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).
  • Use iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.

Example:

result = infer(
+    ...,
+    returnvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    )
+)

Shortcut for setting the same option for all variables:

result = infer(
+    ...,
+    returnvars = KeepLast()  # or KeepEach()
+)

Streamline inference:

  • For each symbol in returnvars, infer creates an observable stream of posterior updates.
  • Agents can subscribe to these updates using the Rocket.jl package.

Example:

engine = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    returnvars = (:x, :τ),
+    autostart  = false
+)
  • predictvars

predictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.

Similar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    predictvars = (
+        o = KeepLast(),
+        τ = KeepEach()
+    )
+)

Note: The predictvars argument is exclusive for batch setting.

  • historyvars

historyvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.

historyvars accepts a NamedTuple or Dict or return var specification. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    ),
+    keephistory = 10
+)

It is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.

Example:

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = KeepLast(),
+    keephistory = 10
+)
  • keep_history

Specifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.

  • iterations

Specifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration.

  • free_energy

Streamline inference:

Specifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.

  • When free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.
    • engine.free_energy_history: Averaged BFE history over VMP iterations.
    • engine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.
    • engine.free_energy_raw_history: Raw BFE history.

Batch inference:

Specifies if the infer function should return Bethe Free Energy (BFE) values.

  • Optionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.

  • free_energy_diagnostics

This settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.

  • catch_exception

The catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.

  • callbacks

The inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.

result = infer(
+    ...,
+    callbacks = (
+        on_marginal_update = (model, name, update) -> println("$(name) has been updated: $(update)"),
+        after_inference    = (args...) -> println("Inference has been completed")
+    )
+)

The callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:

  • on_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)
  • before_model_creation: args: ()
  • after_model_creation: args: (model::FactorGraphModel, returnval)
  • before_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • before_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • after_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)
  • after_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)

before_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.

  • addons

The addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.

  • postprocess

The postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.

source
RxInfer.InferenceResult — Type
InferenceResult

This structure is used as a return value from the infer function.

Public Fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.
  • free_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.
  • error: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.

See also: infer

source
RxInfer.start — Function
start(engine::RxInferenceEngine)

Starts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.stop

source
RxInfer.stop — Function
stop(engine::RxInferenceEngine)

Stops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.start

source
RxInfer.@autoupdates — Macro
@autoupdates

Creates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification.

Each line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.

For example:

@autoupdates begin 
+    x = f(q(z))
+end

This structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically.

As an example consider the following model and auto-update specification:

@model function kalman_filter()
+    x_current_mean = datavar(Float64)
+    x_current_var  = datavar(Float64)
+
+    x_current ~ Normal(mean = x_current_mean, var = x_current_var)
+
+    x_next ~ Normal(mean = x_current, var = 1.0)
+
+    y = datavar(Float64)
+    y ~ Normal(mean = x_next, var = 1.0)
+end

This model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:

autoupdates = @autoupdates begin
+    x_current_mean, x_current_var = mean_cov(q(x_next))
+end

This structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.

See also: infer

source
RxInfer.RxInferenceEngine — Type
RxInferenceEngine

The return value of the rxinference function.

Public fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.
  • free_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.
  • history: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.
  • free_energy_history: (optional) Free energy history, average over variational iterations
  • free_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)
  • free_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)
  • events: (optional) A stream of events send by the inference engine. See the events argument for the infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.

Use the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.

See also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop

source
RxInfer.RxInferenceEvent — Type
RxInferenceEvent{T, D}

The RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.

The events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:

using Rocket
+
+struct MyEventListener <: Rocket.Actor{RxInferenceEvent}
+    # ... extra fields
+end
+
+function Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })
+    model, iteration = event
+    println("Iteration $(iteration) has been finished.")
+end
+
+function Rocket.on_error!(listener::MyEventListener, err)
+    # ...
+end
+
+function Rocket.on_complete!(listener::MyEventListener)
+    # ...
+end
+

and later on:

engine = infer(events = Val((:after_iteration, )), ...)
+
+subscription = subscribe!(engine.events, MyEventListener(...))

See also: infer, RxInferenceEngine

source
diff --git a/v2.16.0/manuals/inference/manual/434cc3aa.svg b/v2.16.0/manuals/inference/manual/434cc3aa.svg new file mode 100644 index 000000000..e9baff201 --- /dev/null +++ b/v2.16.0/manuals/inference/manual/434cc3aa.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/inference/manual/88b30006.svg b/v2.16.0/manuals/inference/manual/88b30006.svg new file mode 100644 index 000000000..fc827f857 --- /dev/null +++ b/v2.16.0/manuals/inference/manual/88b30006.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/inference/manual/9c5d4107.svg b/v2.16.0/manuals/inference/manual/9c5d4107.svg new file mode 100644 index 000000000..0f9dea88b --- /dev/null +++ b/v2.16.0/manuals/inference/manual/9c5d4107.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.0/manuals/inference/manual/index.html b/v2.16.0/manuals/inference/manual/index.html new file mode 100644 index 000000000..c91a0a95a --- /dev/null +++ b/v2.16.0/manuals/inference/manual/index.html @@ -0,0 +1,103 @@ + +Manual inference specification · RxInfer.jl
GitHub

Manual inference

For advanced use cases it is advised to use manual inference specification.

Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:

  1. Create a model with @model macro and get a references to random variables and data inputs
  2. Subscribe to random variable posterior marginal updates
  3. Subscribe to Bethe Free Energy updates (optional)
  4. Feed model with observations
  5. Unsubscribe from posterior marginal updates (optional)

It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.

Model creation

During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.

using RxInfer, Distributions, Random
+
+@model function my_model()
+    m2 ~ NormalMeanVariance(0.0, 1.0)
+    m1 ~ NormalMeanVariance(m2, 1.0)
+
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(m1, 1.0)
+
+    # Return variables of interests, optional
+    return m1, y
+end

And later on we may create our model with the create_model function and obtain references for variables of interests:

model, (m1, y) = create_model(my_model())

Alternatively, it is possible to query any variable using squared brackets on model object:

model[:m1] # m1
+model[:y]  # y

@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.

Posterior marginal updates

The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.

We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:

m1_posterior_updates = getmarginal(m1)

After that we can subscribe on new updates and perform some actions based on new values:

m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin
+    println("New posterior for m1: ", new_posterior)
+end)

Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.

@model function my_model()
+    ...
+    m_n = randomvar(n)
+    ...
+    return m_n, ...
+end
+
+model, (m_n, ...) = create_model(my_model())
+
+m_n_updates = getmarginals(m_n)

Feeding observations

By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.

To feed an observation for a specific data input we use update! function:

update!(y, 0.0)
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:

update!(y, 0.0) # Observation didn't change, should result in the same posterior
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

If y is an array of data inputs it is possible to pass an array of observation to update! function:

for i in 1:length(data)
+    update!(y[i], data[i])
+end
+# is an equivalent of
+update!(y, data)

Variational Message Passing

Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.

using RxInfer, Distributions, Random
real_mean      = -4.0
+real_precision = 0.2
+rng            = MersenneTwister(1234)
+
+n    = 100
+data = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)
@model function normal_estimation(n)
+    m ~ NormalMeanVariance(0.0, 10.0)
+    w ~ Gamma(0.1, 10.0)
+
+    y = datavar(Float64, n)
+
+    for i in 1:n
+        y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }
+    end
+
+    return m, w, y
+end

We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:

model, (m, w, y) = create_model(normal_estimation(n))
+
+# We use vague initial marginals
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))

To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:

m_marginals = []
+w_marginals = []
+
+subscriptions = subscribe!([
+    (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),
+    (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),
+])
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(subscriptions)

As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.

using Plots
+
+p1    = plot(title = "'Mean' posterior marginals")
+grid1 = -6.0:0.01:4.0
+
+for iter in [ 1, 2, 10 ]
+
+    estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = "Estimated mean after $iter VMP iterations")
+
+end
+
+plot!(p1, [ real_mean ], seriestype = :vline, label = "Real mean", color = :red4, opacity = 0.7)
Example block output
p2    = plot(title = "'Precision' posterior marginals")
+grid2 = 0.01:0.001:0.35
+
+for iter in [ 2, 3, 10 ]
+
+    estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = "Estimated precision after $iter VMP iterations")
+
+end
+
+plot!(p2, [ real_precision ], seriestype = :vline, label = "Real precision", color = :red4, opacity = 0.7)
Example block output

Computing Bethe Free Energy

VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.

The RxInfer package exports score function for an observable of free energy values:

fe_observable = score(model, BetheFreeEnergy())
# Reset posterior marginals for `m` and `w`
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))
+
+fe_values = []
+
+fe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(fe_subscription)
plot(fe_values, label = "Bethe Free Energy", xlabel = "Iteration #")
Example block output
diff --git a/v2.16.0/manuals/inference/overview/index.html b/v2.16.0/manuals/inference/overview/index.html new file mode 100644 index 000000000..89f306a73 --- /dev/null +++ b/v2.16.0/manuals/inference/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Inference execution

The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):

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.

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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.

Automatic inference specification on static datasets

RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section.

Automatic inference specification on real-time datasets

RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section.

Manual inference specification

While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.

diff --git a/v2.16.0/manuals/inference/postprocess/index.html b/v2.16.0/manuals/inference/postprocess/index.html new file mode 100644 index 000000000..e803c9552 --- /dev/null +++ b/v2.16.0/manuals/inference/postprocess/index.html @@ -0,0 +1,2 @@ + +Inference results postprocessing · RxInfer.jl
GitHub

Inference results postprocessing

infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:

diff --git a/v2.16.0/manuals/meta-specification/index.html b/v2.16.0/manuals/meta-specification/index.html new file mode 100644 index 000000000..82a644c32 --- /dev/null +++ b/v2.16.0/manuals/meta-specification/index.html @@ -0,0 +1,122 @@ + +Meta specification · RxInfer.jl
GitHub

Meta Specification

Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.

General syntax

@meta macro accepts either regular Julia function or a single begin ... end block:

@meta function MyModelMeta(arg1, arg2)
+    Node(y,x) -> MetaObject(arg1, arg2)
+end
+
+my_meta = @meta begin 
+    Node(y,x) -> MetaObject(arg1, arg2)
+end

In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order $5$ can be specified as follows:

@meta function ARmodel_meta(num_order)
+    AR() -> ARMeta(Univariate, num_order, ARsafe())
+end
+
+my_meta = ARmodel_meta(5)

In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:

num_order = 5
+
+my_meta = @meta begin 
+    AR() -> ARMeta(Multivariate, num_order, ARsafe())
+end

Both syntax variations provide the same meta specification and there is no preference given to one over the other.

Options specification

@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

my_meta = @meta [ warn = false ] begin 
+   ...
+end
+
+@meta [ warn = false ] function MyModelMeta()
+    ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/meta specification

Meta specification

First, let's start with an example:

my_meta = @meta begin 
+    GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))
+end

This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.

You can have a list of as many meta specification entries as possible for different nodes:

my_meta = @meta begin 
+    GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))
+    AR() -> ARMeta(Multivariate, 5, ARsafe())
+    MyCustomNode() -> MyCustomMetaObject(arg1, arg2)
+end

To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+my_meta = @meta begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); meta = my_meta)

Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:

inferred_result = infer(
+    model = my_model(arguments...),
+    meta = my_meta,
+    ...
+)

Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:

@model function my_model()
+    ...
+
+    y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }
+
+    ...
+end

If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.

Create your own meta

Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:

# create your own meta structure for your custom node
+struct MyCustomMeta
+    arg1 
+    arg2 
+end
+
+# apply the new meta structure to your node
+@meta function model_meta(arg1, arg2)
+    MyCustomNode() -> MyCustomMeta(arg1,arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

or create different meta structures for a node, e.g. AR node:

# create your own meta structure for the AR node
+struct MyARMeta
+    arg1
+    arg2
+end
+
+# apply the new meta structure to the AR node
+@meta function model_meta(arg1, arg2)
+    AR() -> MyARMeta(arg1, arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.

Example

This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(2.5, 0.5)\\ + y & \sim \mathrm{Normal}(2*x, 2.0) +\end{aligned}\]

where $y$ is observable data and $x$ is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.

using RxInfer
+
+#create data
+y_data = 4.0
+
+#make model
+@model function gaussian_model()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+#do inference
+inference_result = infer(
+    model = gaussian_model(),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (x)
+

However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean $m$ clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:

#create your new meta structure for Normal node
+struct MetaConstrainedMeanNormal{T}
+    lower_limit :: T
+    upper_limit :: T
+end
+
+#define rules with meta for the Normal node
+@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
+
+@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
#make model
+@model function gaussian_model_with_meta()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+custom_meta = @meta begin
+    NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)
+end
+
+#do inference
+inference_result = inference(
+    model = gaussian_model(),
+    data = (y = y_data,),
+    meta = custom_meta
+)
Inference results:
+  Posteriors       | available for (x)
+

Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.

diff --git a/v2.16.0/manuals/model-specification/index.html b/v2.16.0/manuals/model-specification/index.html new file mode 100644 index 000000000..c3c20b0db --- /dev/null +++ b/v2.16.0/manuals/model-specification/index.html @@ -0,0 +1,117 @@ + +Model specification · RxInfer.jl
GitHub

Model Specification

The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: 

@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model specification here
+    return ...
+end

Model options, model_arguments and model_keyword_arguments are optional and may be omitted:

@model function model_name()
+    # model specification here
+    return ...
+end

The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:

@model function my_model(model_arguments...)
+    # model specification here
+    # ...
+    return x, y
+end
generator = my_model(model_arguments...)

In order to create an instance of the model object we should use the create_model function:

model, (x, y) = create_model(generator)

It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.

A full example before diving in

Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:

@model function state_space_model(n_observations, noise_variance)
+
+    c = constvar(1.0)
+    x = randomvar(n_observations)
+    y = datavar(Float64, n_observations)
+
+    x[1] ~ NormalMeanVariance(0.0, 100.0)
+
+    for i in 2:n_observations
+       x[i] ~ x[i - 1] + c
+       y[i] ~ NormalMeanVariance(x[i], noise_var)
+    end
+
+    return x, y
+end

Graph variables creation

Constants

Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).

You can create a constant within a model specification macro with constvar() function. For example:

@model function model_name(...)
+    ...
+    c = constvar(1.0)
+
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0
+    end
+    ...
+end
Note

constvar() function is supposed to be used only within the @model macro.

Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:

@model function model_name(nsamples::Int, c::ConstVariable)
+    ...
+    # no need to call for a constvar() here
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`
+    end
+    ...
+end
Note

::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.

Data variables

It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.

Examples: 

@model function model_name(...)
+    ...
+    y = datavar(Float64) # Creates a single data input with `y` as identificator
+    y = datavar(Float64, n) # Returns a vector of  `y_i` data input objects with length `n`
+    y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`
+    y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

datavar() function is supposed to be used only within the @model macro.

datavar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = datavar(Float64, n) where { allow_missing = true }
+    ...
+end

Data variables available options

  • allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.

Random variables

There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.

Examples: 

@model function model_name(...)
+    ...
+    x = randomvar() # Returns a single random variable which can be used later in the model
+    x = randomvar(n) # Returns an vector of random variables with length `n`
+    x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`
+    x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

randomvar() function is supposed to be used only within the @model macro.

randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = randomvar() where { prod_constraint = ProdGeneric() }
+    ...
+end

Random variables available options

  • prod_constraint
  • prod_strategy
  • marginal_form_constraint
  • marginal_form_check_strategy
  • messages_form_constraint
  • messages_form_check_strategy
  • pipeline

The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.

Node creation

Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables.

Distributions.jl compatibility

For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:

  1. Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.
  2. Depending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.
  3. In certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.

Tilde syntax

We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define

@model function model_name(...)
+    ...
+    m = randomvar()
+    v = randomvar()
+    y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically
+    ...
+end

Another example, but using a deterministic relation between random variables:

@model function model_name(...)
+    ...
+    a = randomvar()
+    b = randomvar()
+    c ~ a + b
+    ...
+end
Note

The RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.

The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:

noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.

It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.

Note

It is forbidden to use random variable within square brackets in the model specification.

y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.
+
+y ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.

It is also possible to return a node reference from the ~ operator. Use the following syntax:

node, y ~ NormalMeanVariance(mean, var)

Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.

Broadcasting syntax

Note

Broadcasting syntax requires at least v2.1.0 of GraphPPL.jl

GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:

y = datavar(Float64, n)
+y .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations

More complex expression are also allowed:

m ~ NormalMeanPrecision(0.0, 0.0001)
+t ~ Gamma(1.0, 1.0)
+
+y = randomvar(Float64, n)
+y .~ NormalMeanPrecision(m, t)
A = constvar(...)
+x = randomvar(n)
+y = datavar(Vector{Float64}, n)
+
+w         ~ Wishart(3, diageye(2))
+x[1]      ~ MvNormalMeanPrecision(zeros(2), diageye(2))
+x[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A
+y        .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix

Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:

# Suppose `x` is a 2-dimensional Gaussian distribution
+z .~ x .+ constvar([ 1, 1 ])
+# Which is equivalent to 
+for i in 1:n
+   z[i] ~ x[i] + constvar([ 1, 1 ])
+end

Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:

# Without explicit `constvar`
+z .~ x .+ [ 1, 1 ]
+# Which is equivalent to 
+array = [1, 1]
+for i in 1:n
+   z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian 
+end

Read more about how broadcasting machinery works in Julia in the official documentation.

Node creation options

To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q

A list of the available options specific to the ReactiveMP inference engine is presented below.

Factorisation constraint option

See also Constraints Specification section.

Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:

variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }

where RecognitionFactorisationConstraint can be the following

  1. MeanField()

Automatically specifies a mean-field factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }
  1. FullFactorisation()

Automatically specifies a full factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }
  1. q(μ)q(v)q(out) or q(μ) * q(v) * q(out)

A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.

Examples: 

# Using interface names of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names for some node
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }
+
+# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names aliases for some node
+# In general aliases correspond to the function names for distribution parameters
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }
+
+# Using random variables names from `~` operator expression
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }
+
+# All methods can be combined easily
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }

Metadata option

Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.

z ~ f(x, y) where { meta = ... }
diff --git a/v2.16.0/search_index.js b/v2.16.0/search_index.js new file mode 100644 index 000000000..3eed72b94 --- /dev/null +++ b/v2.16.0/search_index.js @@ -0,0 +1,3 @@ +var documenterSearchIndex = {"docs": +[{"location":"manuals/delta-node/#delta-node-manual","page":"Delta node","title":"Delta node manual","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/#Features-and-Supported-Inference-Scenarios","page":"Delta node","title":"Features and Supported Inference Scenarios","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Gaussian Nodes: For delta nodes linked to strictly multivariate or univariate Gaussian distributions, the recommended methods are Linearization or Unscented transforms.\nExponential Family Nodes: For the delta node connected to nodes from the exponential family, the CVI (Conjugate Variational Inference) is the method of choice.\nStacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Methods Gaussian Nodes Exponential Family Nodes Stacking Delta Nodes\nLinearization ✓ ✗ ✓\nUnscented ✓ ✗ ✓\nCVI ✓ ✓ ✗","category":"page"},{"location":"manuals/delta-node/#Gaussian-Case","page":"Delta node","title":"Gaussian Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For clarity, consider the following example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=0.0, var=1.0)\n y ~ tanh(x)\n z ~ Normal(mean=y, var=1.0)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Unscented()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For a deeper understanding of the Unscented method and its parameters, consult the docstrings.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To execute the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"This methodology is consistent even when the delta node is associated with multiple nodes. For instance:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"f(x, g) = x*tanh(g)","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=1.0, var=1.0)\n g ~ Normal(mean=1.0, var=1.0)\n y ~ f(x, g)\n z ~ Normal(mean=y, var=0.1)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification is:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization())\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or simply","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))\nend","category":"page"},{"location":"manuals/delta-node/#Exponential-Family-Case","page":"Delta node","title":"Exponential Family Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example1()\n z = datavar(Float64)\n x ~ Gamma(shape=1.0, rate=1.0)\n y ~ tanh(x)\n z ~ Bernoulli(y)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification can be represented as:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using StableRNGs\nusing Optimisers\n\ndelta_meta = @meta begin \n tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Consult the ProdCVI docstrings for a detailed explanation of these parameters.","category":"page"},{"location":"manuals/inference/postprocess/#user-guide-inference-postprocess","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"","category":"section"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:","category":"page"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"DefaultPostprocess\nUnpackMarginalPostprocess\nNoopPostprocess","category":"page"},{"location":"manuals/inference/postprocess/#RxInfer.DefaultPostprocess","page":"Inference results postprocessing","title":"RxInfer.DefaultPostprocess","text":"DefaultPostprocess picks the most suitable postprocessing step automatically\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.UnpackMarginalPostprocess","page":"Inference results postprocessing","title":"RxInfer.UnpackMarginalPostprocess","text":"This postprocessing step removes the Marginal wrapper type from the result\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.NoopPostprocess","page":"Inference results postprocessing","title":"RxInfer.NoopPostprocess","text":"This postprocessing step does nothing\n\n\n\n\n\n","category":"type"},{"location":"manuals/model-specification/#user-guide-model-specification","page":"Model specification","title":"Model Specification","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Model options, model_arguments and model_keyword_arguments are optional and may be omitted:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name()\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function my_model(model_arguments...)\n # model specification here\n # ...\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"generator = my_model(model_arguments...)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"In order to create an instance of the model object we should use the create_model function:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"model, (x, y) = create_model(generator)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.","category":"page"},{"location":"manuals/model-specification/#A-full-example-before-diving-in","page":"Model specification","title":"A full example before diving in","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function state_space_model(n_observations, noise_variance)\n\n c = constvar(1.0)\n x = randomvar(n_observations)\n y = datavar(Float64, n_observations)\n\n x[1] ~ NormalMeanVariance(0.0, 100.0)\n\n for i in 2:n_observations\n x[i] ~ x[i - 1] + c\n y[i] ~ NormalMeanVariance(x[i], noise_var)\n end\n\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/#Graph-variables-creation","page":"Model specification","title":"Graph variables creation","text":"","category":"section"},{"location":"manuals/model-specification/#user-guide-model-specification-constant-variables","page":"Model specification","title":"Constants","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"You can create a constant within a model specification macro with constvar() function. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n c = constvar(1.0)\n\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nconstvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(nsamples::Int, c::ConstVariable)\n ...\n # no need to call for a constvar() here\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\n::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-data-variables","page":"Model specification","title":"Data variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64) # Creates a single data input with `y` as identificator\n y = datavar(Float64, n) # Returns a vector of `y_i` data input objects with length `n`\n y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`\n y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\ndatavar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"datavar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64, n) where { allow_missing = true }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Data-variables-available-options","page":"Model specification","title":"Data variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-random-variables","page":"Model specification","title":"Random variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n x = randomvar() # Returns a single random variable which can be used later in the model\n x = randomvar(n) # Returns an vector of random variables with length `n`\n x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`\n x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nrandomvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = randomvar() where { prod_constraint = ProdGeneric() }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Random-variables-available-options","page":"Model specification","title":"Random variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"prod_constraint\nprod_strategy\nmarginal_form_constraint\nmarginal_form_check_strategy\nmessages_form_constraint\nmessages_form_check_strategy\npipeline","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.","category":"page"},{"location":"manuals/model-specification/#Node-creation","page":"Model specification","title":"Node creation","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables. ","category":"page"},{"location":"manuals/model-specification/#Distributions.jl-compatibility","page":"Model specification","title":"Distributions.jl compatibility","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.\nDepending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.\nIn certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.","category":"page"},{"location":"manuals/model-specification/#Tilde-syntax","page":"Model specification","title":"Tilde syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n m = randomvar()\n v = randomvar()\n y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Another example, but using a deterministic relation between random variables:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n a = randomvar()\n b = randomvar()\n c ~ a + b\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nThe RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nIt is forbidden to use random variable within square brackets in the model specification.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.\n\ny ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is also possible to return a node reference from the ~ operator. Use the following syntax:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"node, y ~ NormalMeanVariance(mean, var)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.","category":"page"},{"location":"manuals/model-specification/#Broadcasting-syntax","page":"Model specification","title":"Broadcasting syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nBroadcasting syntax requires at least v2.1.0 of GraphPPL.jl ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y = datavar(Float64, n)\ny .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"More complex expression are also allowed:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"m ~ NormalMeanPrecision(0.0, 0.0001)\nt ~ Gamma(1.0, 1.0)\n\ny = randomvar(Float64, n)\ny .~ NormalMeanPrecision(m, t)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A = constvar(...)\nx = randomvar(n)\ny = datavar(Vector{Float64}, n)\n\nw ~ Wishart(3, diageye(2))\nx[1] ~ MvNormalMeanPrecision(zeros(2), diageye(2))\nx[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A\ny .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Suppose `x` is a 2-dimensional Gaussian distribution\nz .~ x .+ constvar([ 1, 1 ])\n# Which is equivalent to \nfor i in 1:n\n z[i] ~ x[i] + constvar([ 1, 1 ])\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Without explicit `constvar`\nz .~ x .+ [ 1, 1 ]\n# Which is equivalent to \narray = [1, 1]\nfor i in 1:n\n z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian \nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Read more about how broadcasting machinery works in Julia in the official documentation.","category":"page"},{"location":"manuals/model-specification/#Node-creation-options","page":"Model specification","title":"Node creation options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A list of the available options specific to the ReactiveMP inference engine is presented below.","category":"page"},{"location":"manuals/model-specification/#Factorisation-constraint-option","page":"Model specification","title":"Factorisation constraint option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"See also Constraints Specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"where RecognitionFactorisationConstraint can be the following","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"MeanField()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a mean-field factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"FullFactorisation()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a full factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"q(μ)q(v)q(out) or q(μ) * q(v) * q(out)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Using interface names of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names for some node\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }\n\n# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names aliases for some node\n# In general aliases correspond to the function names for distribution parameters\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }\n\n# Using random variables names from `~` operator expression\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }\n\n# All methods can be combined easily\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }","category":"page"},{"location":"manuals/model-specification/#Metadata-option","page":"Model specification","title":"Metadata option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"z ~ f(x, y) where { meta = ... }","category":"page"},{"location":"examples/overview/#examples-overview","page":"Overview","title":"Examples overview","text":"","category":"section"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"Basic examples: Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.\nAdvanced examples: Advanced examples contain more complex inference problems.\nProblem specific: Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference","page":"Manual inference specification","title":"Manual inference","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"For advanced use cases it is advised to use manual inference specification. ","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Create a model with @model macro and get a references to random variables and data inputs\nSubscribe to random variable posterior marginal updates \nSubscribe to Bethe Free Energy updates (optional)\nFeed model with observations \nUnsubscribe from posterior marginal updates (optional)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-model-creation","page":"Manual inference specification","title":"Model creation","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random\n\n@model function my_model()\n m2 ~ NormalMeanVariance(0.0, 1.0)\n m1 ~ NormalMeanVariance(m2, 1.0)\n\n y = datavar(Float64)\n y ~ NormalMeanVariance(m1, 1.0)\n\n # Return variables of interests, optional\n return m1, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"And later on we may create our model with the create_model function and obtain references for variables of interests:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m1, y) = create_model(my_model())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Alternatively, it is possible to query any variable using squared brackets on model object:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model[:m1] # m1\nmodel[:y] # y\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-marginal-updates","page":"Manual inference specification","title":"Posterior marginal updates","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_updates = getmarginal(m1)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"After that we can subscribe on new updates and perform some actions based on new values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin\n println(\"New posterior for m1: \", new_posterior)\nend)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function my_model()\n ...\n m_n = randomvar(n)\n ...\n return m_n, ...\nend\n\nmodel, (m_n, ...) = create_model(my_model())\n\nm_n_updates = getmarginals(m_n)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-observations","page":"Manual inference specification","title":"Feeding observations","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To feed an observation for a specific data input we use update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0) # Observation didn't change, should result in the same posterior\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"If y is an array of data inputs it is possible to pass an array of observation to update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"for i in 1:length(data)\n update!(y[i], data[i])\nend\n# is an equivalent of\nupdate!(y, data)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp","page":"Manual inference specification","title":"Variational Message Passing","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"real_mean = -4.0\nreal_precision = 0.2\nrng = MersenneTwister(1234)\n\nn = 100\ndata = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function normal_estimation(n)\n m ~ NormalMeanVariance(0.0, 10.0)\n w ~ Gamma(0.1, 10.0)\n\n y = datavar(Float64, n)\n\n for i in 1:n\n y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }\n end\n\n return m, w, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m, w, y) = create_model(normal_estimation(n))\n\n# We use vague initial marginals\nsetmarginal!(m, vague(NormalMeanVariance)) \nsetmarginal!(w, vague(Gamma))\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m_marginals = []\nw_marginals = []\n\nsubscriptions = subscribe!([\n (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),\n (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),\n])\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(subscriptions)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using Plots\n\np1 = plot(title = \"'Mean' posterior marginals\")\ngrid1 = -6.0:0.01:4.0\n\nfor iter in [ 1, 2, 10 ]\n\n estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = \"Estimated mean after $iter VMP iterations\")\n\nend\n\nplot!(p1, [ real_mean ], seriestype = :vline, label = \"Real mean\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"p2 = plot(title = \"'Precision' posterior marginals\")\ngrid2 = 0.01:0.001:0.35\n\nfor iter in [ 2, 3, 10 ]\n\n estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = \"Estimated precision after $iter VMP iterations\")\n\nend\n\nplot!(p2, [ real_precision ], seriestype = :vline, label = \"Real precision\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp-bfe","page":"Manual inference specification","title":"Computing Bethe Free Energy","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer package exports score function for an observable of free energy values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"fe_observable = score(model, BetheFreeEnergy())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"# Reset posterior marginals for `m` and `w`\nsetmarginal!(m, vague(NormalMeanVariance))\nsetmarginal!(w, vague(Gamma))\n\nfe_values = []\n\nfe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(fe_subscription)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"plot(fe_values, label = \"Bethe Free Energy\", xlabel = \"Iteration #\")","category":"page"},{"location":"contributing/new-package/#Contributing-to-the-dependencies","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.","category":"page"},{"location":"contributing/new-package/#The-benefits-of-small-packages-for-the-ecosystem","page":"Contributing to the dependencies","title":"The benefits of small packages for the ecosystem","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.\nCollaboration: Teams can work on different packages concurrently, speeding up development.\nVersion Control: Precise versioning and fewer dependencies lead to leaner projects.\nPerformance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.\nFlexibility: Developers can select and customize packages for their needs.\nCommunity: Smaller packages attract contributors, fostering collaboration and faster feedback.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.","category":"page"},{"location":"contributing/new-package/#Use-[PkgTemplates](https://github.com/JuliaCI/PkgTemplates.jl)","page":"Contributing to the dependencies","title":"Use PkgTemplates","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> using PkgTemplates\n\njulia> USER = \"your github user name\" # Use `reactivebayes` if developing within the ReactiveBayes organisation\n\njulia> template = Template(\n user = USER, \n plugins = [\n CompatHelper(), \n ProjectFile(), \n SrcDir(), \n Git(), \n License(), \n Readme(), \n Tests(), \n GitHubActions(), \n Codecov(), \n Documenter{GitHubActions}(), \n Formatter(style=\"blue\"), \n BlueStyleBadge(), \n PkgEvalBadge()\n])\n\njulia> template(\"MyNewCoolPackage\")","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the minimum supported version of Julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9.2\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Try to be conservative and set as low version of Julia as possible.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the authors of the package","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The authors field is present in the Project.toml, e.g ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"authors = [\"John Wick \", ...]","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Add requires dependencies and their [compat] bounds","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"or ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] activate .","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Then, add dependencies like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] add SomeCoolDependency, SomeOtherCoolDependency","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9\"\nSomeCoolDependency = \"0.19.2\"\nSomeOtherCoolDependency = \"1.3.12\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For more details on compat bounds, check the official Julia documentation.","category":"page"},{"location":"contributing/new-package/#Adjust-README.md","page":"Contributing to the dependencies","title":"Adjust README.md","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"note: Note\nSome badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.","category":"page"},{"location":"contributing/new-package/#Write-code-and-tests","page":"Contributing to the dependencies","title":"Write code and tests","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.","category":"page"},{"location":"contributing/new-package/#Simplify-Testing-with-ReTestItems","page":"Contributing to the dependencies","title":"Simplify Testing with ReTestItems","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.","category":"page"},{"location":"contributing/new-package/#Write-code-and-the-documentation","page":"Contributing to the dependencies","title":"Write code and the documentation","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=docs docs/make.jl","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.","category":"page"},{"location":"contributing/new-package/#Hosting-Documentation-with-GitHub-Actions","page":"Contributing to the dependencies","title":"Hosting Documentation with GitHub Actions","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.","category":"page"},{"location":"contributing/new-package/#Enable-GitHub-Pages-in-Repository-Settings","page":"Contributing to the dependencies","title":"Enable GitHub Pages in Repository Settings","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Navigate to the GitHub Pages settings of your repository.\nChoose the Deploy from a branch option.\nSelect the gh-pages branch.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#examples-assessing-people’s-skills","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of \"Model-Based Machine Learning\" by Winn et al.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Problem-Statement","page":"Assessing People’s Skills","title":"Problem Statement","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We model the result for question i as a continuous variable r_iin01, and skill/attitude as a binary variable s_i in 0 1, where s_1 represents whether the student has partied, and s_2 and s_3 represent whether the student has studied the chapters for the corresponding questions.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We assume the following logic:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"If the student is alert (has not partied), then they will score on the first question;\nIf the student is alert or has studied chapter two, then they will score on question two;\nIf the student can answer question two and has studied chapter three, then they will score on question three.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Definition","page":"Assessing People’s Skills","title":"Generative Model Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"To model the probability for correct answers, we assume a latent state variable t_i in 01. The dependencies between the variables can then be modeled by the following Bayesian network:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"(s_1) (s_2) (s_3)\n | | |\n v v v\n(t_1)-->(t_2)-->(t_3)\n | | |\n v v v\n(r_1) (r_2) (r_3)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"As prior beliefs, we assume that a student is equally likely to study/party or not: s_i sim Ber(05) for all i. Next, we model the domain logic as beginaligned t_1 = s_1\n t_2 = t_1 s_2\n t_3 = t_2 s_3 endaligned For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as t_i sim Ber(s_i) for all i.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Custom-Nodes-and-Rules","page":"Assessing People’s Skills","title":"Custom Nodes and Rules","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"using RxInfer, Random\n\n# Create Score node\nstruct Score end\n\n@node Score Stochastic [out, in]","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Adding update rule for the Score node\n@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin \n return Bernoulli(mean(q_out))\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Specification","page":"Assessing People’s Skills","title":"Generative Model Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now build the full generative model.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# GraphPPL.jl exports the `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function skill_model()\n s = randomvar(3)\n t = randomvar(3)\n r = datavar(Float64, 3)\n\n # Priors\n for i=1:3\n s[i] ~ Bernoulli(0.5)\n end\n\n # Domain logic\n t[1] ~ ¬s[1]\n t[2] ~ t[1] || s[2]\n t[3] ~ t[2] && s[3]\n \n # Results\n for i=1:3\n r[i] ~ Score(t[i])\n end\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Inference-Specification","page":"Assessing People’s Skills","title":"Inference Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"test_results = [0.1, 0.1, 0.1]\ninference_result = infer(\n model = skill_model(),\n data = (r = test_results, )\n)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Inference results:\n Posteriors | available for (s, t)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Results","page":"Assessing People’s Skills","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Inspect the results\nmap(params, inference_result.posteriors[:s])","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"3-element Vector{Tuple{Float64}}:\n (0.9872448979591837,)\n (0.06377551020408162,)\n (0.4719387755102041,)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"These results suggest that this particular student was very likely out on the town last night.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#examples-predicting-bike-rental-demand","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using RxInfer","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Preamble:-Enabling-Predictions","page":"Predicting Bike Rental Demand","title":"Preamble: Enabling Predictions","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"RxInfer.jl facilitates predictions in two primary ways. ","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.\nExplicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Example","page":"Predicting Bike Rental Demand","title":"Example","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Consider the following model:","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"@model function example_model()\n y = datavar(Float64) where {allow_missing = true}\n\n h ~ NormalMeanPrecision(0, 1.0)\n x ~ NormalMeanPrecision(h, 1.0)\n y ~ NormalMeanPrecision(x, 10.0)\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Implicit Prediction\nresult = infer(model = example_model(), data = (y = missing,))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Explicit Prediction\nresult = infer(model = example_model(), predictvars = (y = KeepLast(),))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using CSV, DataFrames, Plots","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Objective","page":"Predicting Bike Rental Demand","title":"Objective","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Dataset-Source","page":"Predicting Bike Rental Demand","title":"Dataset Source","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Load the data\ndf = CSV.read(\"../data/bike_count/modified_bicycle.csv\", DataFrame)\ndf[1:10, :]","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"10×6 DataFrame\n Row │ datetime temp atemp humidity windspeed count\n │ String31 Float64 Float64 Float64 Float64 Int64\n─────┼──────────────────────────────────────────────────────────────────\n 1 │ 2011-01-01 0:00:00 9.84 14.395 81.0 0.0 16\n 2 │ 2011-01-01 1:00:00 9.02 13.635 80.0 0.0 40\n 3 │ 2011-01-01 2:00:00 9.02 13.635 80.0 0.0 32\n 4 │ 2011-01-01 3:00:00 9.84 14.395 75.0 0.0 13\n 5 │ 2011-01-01 4:00:00 9.84 14.395 75.0 0.0 1\n 6 │ 2011-01-01 5:00:00 9.84 12.88 75.0 6.0032 1\n 7 │ 2011-01-01 6:00:00 9.02 13.635 80.0 0.0 2\n 8 │ 2011-01-01 7:00:00 8.2 12.88 86.0 0.0 3\n 9 │ 2011-01-01 8:00:00 9.84 14.395 75.0 0.0 8\n 10 │ 2011-01-01 9:00:00 13.12 17.425 76.0 0.0 14","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# we reserve few samples for prediction\nn_future = 24\n\nX = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]\ny = Union{Float64, Missing}[df[:, \"count\"]...][1:end-n_future]\n\nstate_dim = length(X[1]); # dimensionality of feature space","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Generative-Model-with-Priors","page":"Predicting Bike Rental Demand","title":"Generative Model with Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"We present a generative model that delineates the latent dynamics of feature evolution, represented by mathbfh_t, and their link to the bike rental counts, mathbfy_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Equations-and-Priors","page":"Predicting Bike Rental Demand","title":"Equations and Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Feature Dynamics with Prior:\nPrior: mathbfa sim mathcalN(mathbf0 mathbfI)\nDynamics: mathbfh_t sim mathcalN(mathbfA h_t-1 mathbfQ)\nmathbfA\nis the transition matrix, reshaped from the prior vector mathbfa, and mathbfQ represents process noise.\nNoisy Observations:\nmathbfx_t sim mathcalN(mathbfh_t mathbfP)\nRepresents the observed noisy state of the features.\nCount Prediction with Prior:\nPrior: boldsymboltheta sim mathcalN(mathbf0 mathbfI)\nPrediction: y_t sim mathcalN(textsoftplus(boldsymboltheta^topmathbfh_t) sigma^2)\nModels the bike rental count as influenced by a non-linear transformation of the hidden state.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Interpretation","page":"Predicting Bike Rental Demand","title":"Interpretation","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This framework aims to simultaneously infer the transition matrix mathbfA and the regression parameters boldsymboltheta, providing a comprehensive view of the feature space dynamics and the count prediction.\nBy employing Gaussian priors on both mathbfa and boldsymboltheta, we incorporate beliefs about their distributions.\nThe inference process aims to discover these underlying dynamics, enabling predictions of both features mathbfx_t and counts y_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We augument the dataset with missing entries for 24 hours ahead\nappend!(X, repeat([missing], n_future))\nappend!(y, repeat([missing], n_future));","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Function to perform the state transition in the model.\n# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.\nfunction transition(a, x)\n nm, n = length(a), length(x)\n m = nm ÷ n # Calculate the number of rows for reshaping 'a' into a matrix\n A = reshape(a, (m, n)) \n return A * x\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"transition (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# The dotsoftplus function combines a dot product and softplus transformation.\n# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,\n# especially if the data suggests other forms of relationships or distributions.\nfunction dotsoftplus(a, x)\n log(1 + exp(dot(a, x)))\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"dotsoftplus (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# model definction\n@model function bicycle_ssm(n, h0, θ0, a0, Q, P)\n\n # `h` is a sequence of hidden states\n h = randomvar(n)\n\n # `x` is a sequence of observed states (features)\n x = datavar(Vector{Float64}, n) where {allow_missing = true}\n # `y` is a sequence of \"count\" bicycles\n y = datavar(Float64, n) where {allow_missing = true}\n\n a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))\n\n θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))\n\n h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))\n h_prev = h_prior\n \n for i in 1:n\n \n h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)\n \n x[i] ~ MvNormal(μ=h[i], Σ=P)\n \n y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)\n \n h_prev = h[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.\n# However, alternative methods like Unscented or CVI approximations can also be considered.\ntransition_meta = @meta begin \n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Meta specification:\n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We define rather uninformative priors \nprior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))\nprior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))\nprior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"MvNormalMeanCovariance(\nμ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0\n.0, 0.0]\nΣ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … \n0.0 1.0]\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages\nimessages = ( h = prior_h, a = prior_a, θ = prior_θ,)\n\nbicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))\n\nresult = infer(\n model = bicycle_model,\n data = (y = y, x=X), \n options = (limit_stack_depth = 500, ), \n returnvars = KeepLast(),\n initmessages = imessages,\n meta = transition_meta,\n iterations = 20,\n showprogress=true,\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (a, h, h_prior, θ)\n Predictions | available for (y, x)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# For a sake of this example, we extract only predictions\nmean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])\nmean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])\n\nmean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)\nmean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)\nmean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)\nmean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"slice = (300, length(y))\ndata = df[:, \"count\"][length(y)-n_future:length(y)]\n\np = scatter(y, \n color=:darkblue, \n markerstrokewidth=0,\n label=\"Observed Count\", \n alpha=0.6)\n\n# Plotting the mean prediction with variance ribbon\nplot!(mean_y, ribbon=sqrt.(cov_y), \n color=:orange, \n fillalpha=0.3,\n label=\"Predicted Mean ± Std Dev\")\n\n# Adding a vertical line to indicate the start of the future prediction\nvline!([length(y)-n_future], \n label=\"Prediction Start\", \n linestyle=:dash, \n linecolor=:green)\n\n# Future (unobserved) data\nplot!(length(y)-n_future:length(y), data, label=\"Future Count\")\n\n# Adjusting the limits\nxlims!(slice)\n\n# Enhancing the plot with titles and labels\ntitle!(\"Bike Rental Demand Prediction\")\nxlabel!(\"Time\")\nylabel!(\"Bike Count\")\n\n# Adjust the legend\nlegend=:topright\n\n# Show the final plot\ndisplay(p)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using Plots\n\n# Define a color palette\npalette = cgrad(:viridis)\n\n# Plot the hidden states with observations\np1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label=\"Hidden State 1\", legend=:topleft)\nplot!(df[!, :temp], color=:grey, label=\"Temperature\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Temperature vs Hidden State 1\")\n\np2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label=\"Hidden State 2\", legend=:topleft)\nplot!(df[!, :atemp], color=:grey, label=\"Feels-Like Temp\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Feels-Like Temp vs Hidden State 2\")\n\np3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label=\"Hidden State 3\", legend=:topleft)\nplot!(df[!, :humidity], color=:grey, label=\"Humidity\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Humidity vs Hidden State 3\")\n\np4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label=\"Hidden State 4\", legend=:topleft)\nplot!(df[!, :windspeed], color=:grey, label=\"Windspeed\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Windspeed vs Hidden State 4\")\n\nfor p in [p1, p2, p3, p4]\n xlims!(p, first(slice), last(slice))\nend\n\nplot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Conclusion","page":"Predicting Bike Rental Demand","title":"Conclusion","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.","category":"page"},{"location":"manuals/comparison/#comparison","page":"RxInfer.jl vs. Others","title":"Comparison to other packages","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"DISCLAIMER: ","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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, and we'll be more than willing to rectify.\nThe comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Toolbox Universality Efficiency Expressiveness Debugging & Visualization Modularity Inference Engine Language Community & Ecosystem\nRxInfer.jl ~ ✓ ✓ ~ ✗ Message-passing Julia ✗\nForneyLab.jl ✗ ~ ✗ ~ ✗ Message-passing Julia ✗\nInfer.net ~ ✓ ✗ ✓ ✗ Message-passing C# ✗\nPGMax ✗ ✓ ✗ ✓ ✗ Message-passing Python ✗\nTuring.jl ✓ ✗ ✓ ~ ✗ Sampling Julia ✓\nPyMC ✓ ✗ ✓ ✓ ✗ Sampling Python ✓\nNumPyro ✓ ✓ ~ ✓ ✗ Sampling Python ✓\nTensorFlow Probability ✓ ✗ ~ ✓ ✗ Sampling Python ✓\nStan ✓ ✗ ✓ ✓ ✗ Sampling Stan ✓","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"(Date of creation: 20/10/2023)","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Legend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"✓ : Full capability or feature is present.\n~ : Partial capability or feature is present.\n✗ : No capability or feature.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Notes:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: Denotes the capability to depict a vast array of probabilistic models.\nEfficiency: Highlights computational competence. A \"–\" in this context suggests perceived slowness.\nExpressiveness: Assesses the ability to concisely formulate intricate probabilistic models.\nDebugging & Visualization: Evaluates the suite of tools for model debugging and visualization.\nModularity: Reflects the potential to create models by integrating smaller models.\nInference Engines: Pinpoints the primary inference strategy employed by the toolbox.\nLanguage: Identifies the programming language integral to the toolbox.\nCommunity & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"","category":"page"},{"location":"manuals/comparison/#RxInfer.jl-breakdown","page":"RxInfer.jl vs. Others","title":"RxInfer.jl breakdown","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.\nEfficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.\nModularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"@model function inner_inner(τ, y)\n y ~ Normal(τ[1], τ[2])\nend\n\n@model function inner(θ, α)\n β ~ Normal(0, 1)\n α ~ Gamma(β, 1)\n α ~ inner_inner(τ = θ)\nend\n\n@model function outer()\n local w\n for i = 1:5\n w[i] ~ inner(θ = Gamma(1, 1))\n end\n y ~ inner(θ = w[2:3])\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"beginaligned\n x sim mathrmNormal(00 10)\n w sim mathrmInverseGamma(10 10)\n y sim mathrmNormal(x w)\nendaligned","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"The model then is expressed in RxInfer.jl as follows:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"using RxInfer\n\n@model function example_model()\n x ~ Normal(mean=0.0, var=1.0)\n w ~ InverseGamma(α = 1, θ = 1)\n y ~ Normal(mean = x, var = w)\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#examples-infinite-data-stream","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"using RxInfer, Plots, Random, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"mutable struct Environment\n rng :: AbstractRNG\n current_state :: Float64\n observation_precision :: Float64\n history :: Vector{Float64}\n observations :: Vector{Float64}\n \n Environment(current_state, observation_precision; seed = 123) = begin \n return new(StableRNG(seed), current_state, observation_precision, [], [])\n end\nend\n\nfunction getnext!(environment::Environment)\n environment.current_state = environment.current_state + 1.0\n nextstate = 10sin(0.1 * environment.current_state)\n observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))\n push!(environment.history, nextstate)\n push!(environment.observations, observation)\n return observation\nend\n\nfunction gethistory(environment::Environment)\n return environment.history\nend\n\nfunction getobservations(environment::Environment)\n return environment.observations\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"getobservations (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Model-specification","page":"Infinite Data Stream","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"@model function kalman_filter()\n \n # Prior for the previous state\n x_prev_mean = datavar(Float64)\n x_prev_var = datavar(Float64)\n \n x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)\n \n # Prior for the observation noise\n τ_shape = datavar(Float64)\n τ_rate = datavar(Float64)\n \n τ ~ Gamma(shape = τ_shape, rate = τ_rate)\n \n # Random walk with fixed precision\n x_current ~ Normal(mean = x_prev, precision = 1.0)\n \n # Noisy observation\n y = datavar(Float64)\n y ~ Normal(mean = x_current, precision = τ)\n \nend\n\n# We assume the following factorisation between variables \n# in the variational distribution\n@constraints function filter_constraints()\n q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"filter_constraints (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Prepare-environment","page":"Infinite Data Stream","title":"Prepare environment","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"initial_state = 0.0\nobservation_precision = 0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"After we have created the environment we can observe how our signal behaves:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"testenvironment = Environment(initial_state, observation_precision);\n\nanimation = @animate for i in 1:100\n getnext!(testenvironment)\n \n history = gethistory(testenvironment)\n observations = getobservations(testenvironment)\n \n p = plot(size = (1000, 300))\n \n p = plot!(p, 1:i, history[1:i], label = \"Hidden signal\")\n p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = \"Observation\")\nend\n\ngif(animation, \"../pics/infinite-data-stream.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-static-dataset","page":"Infinite Data Stream","title":"Filtering on static dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"n = 300\nstatic_environment = Environment(initial_state, observation_precision);\n\nfor i in 1:n\n getnext!(static_environment)\nend\n\nstatic_history = gethistory(static_environment)\nstatic_observations = getobservations(static_environment);\nstatic_datastream = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_static(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n keephistory = 10_000,\n historyvars = (x_current = KeepLast(), τ = KeepLast()),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n free_energy = true,\n autostart = true,\n )\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_static (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"result = run_static(static_environment, static_datastream);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"static_inference = @animate for i in 1:n\n estimated = result.history[:x_current]\n p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = \"Estimation\")\n p = plot!(static_history[1:i], label = \"Real states\") \n p = scatter!(static_observations[1:i], ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\nend\n\ngif(static_inference, \"../pics/infinite-data-stream-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"plot(result.free_energy_history, label = \"Bethe Free Energy (averaged)\")","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-realtime-dataset","page":"Infinite Data Stream","title":"Filtering on realtime dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"Next lets create a \"real\" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_and_plot(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n posteriors = []\n \n plotfn = (q_current) -> begin \n IJulia.clear_output(true)\n \n push!(posteriors, q_current)\n\n p = plot(mean.(posteriors), ribbon = var.(posteriors), label = \"Estimation\")\n p = plot!(gethistory(environment), label = \"Real states\") \n p = scatter!(getobservations(environment), ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\n\n display(p)\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n autostart = false,\n )\n \n qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)\n \n RxInfer.start(engine)\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_and_plot (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# This example runs in our documentation pipeline, which does not support \"real-time\" execution context\n# We skip this code if run not in Jupyter notebook (see below an example with gif)\nengine = nothing \nif isdefined(Main, :IJulia)\n timegen = 41 # 41 ms\n environment = Environment(initial_state, observation_precision);\n observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations\n datastream = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));\n engine = run_and_plot(environment, datastream)\nend;","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"if !isnothing(engine) && isdefined(Main, :IJulia)\n RxInfer.stop(engine)\n IJulia.clear_output(true)\nend;","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#examples-universal-mixtures","page":"Universal Mixtures","title":"Universal Mixtures","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"using RxInfer, Distributions, Random, Plots","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y_i mid theta) = mathrmBer(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where y_i in 01 are the outcomes of the coin tosses, i.e. heads or tails, and where theta is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter theta, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of thetain01 they come up with the prior beliefs:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJohn) = mathrmBeta(theta mid 7 2)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJane) = mathrmBeta(theta mid 2 7)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior beliefs\")\nplot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) John\", c=1)\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"p(θ) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"true_coin = Bernoulli(0.25)\nnr_throws = 10\ndataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))\nnr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)\nprintln(\"experimental outcome: \\n - heads: \", nr_heads, \"\\n - tails: \", nr_tails);","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"experimental outcome: \n - heads: 3\n - tails: 7","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"For computing the posterior beliefs p(theta mid y) about the parameter theta, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#John's-model:","page":"Universal Mixtures","title":"John's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJohn) = p(theta mid textJohn) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_john(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's prior model over θ\n θ ~ Beta(7.0, 2.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#Jane's-model:","page":"Universal Mixtures","title":"Jane's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJane) = p(theta mid textJane) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_jane(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify Jane's prior model over θ\n θ ~ Beta(2.0, 7.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy mathrmF_B bounds the model evidence p(y) as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"mathrmF_Bpq geq - ln p(y)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_john = infer(\n model = beta_model_john(nr_throws), \n data = (y = dataset, ),\n free_energy = true,\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[8.96366]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_jane = infer(\n model = beta_model_jane(nr_throws), \n data = (y = dataset, ),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[6.63988]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying theta parameter. They formulate this through the posterior distributions p(theta mid y textJohn) and p(theta mid y textJane):","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior beliefs\")\nplot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) John\", c=1)\nplot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"p(θ|y) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over theta, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta c mid textMary) = p(c mid textMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where c describes the probability of John being correct as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(c mid textMary) = mathrmBer(c mid 07)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"The predictive distribution p(theta mid textMary) for theta (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over c as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textMary) = sum_cin01 p(cmidtextMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c = 07 cdot p(theta mid textJohn) + 03 cdot p(theta mid textJane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior belief\")\nplot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) Mary\", c=1)\nplot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label=\"\")\nplot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label=\"\")","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_mary(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's and Jane's prior models over θ\n θ_jane ~ Beta(2.0, 7.0)\n θ_john ~ Beta(7.0, 2.0)\n\n # specify initial guess as to who is right\n john_is_right ~ Bernoulli(0.7) \n\n # specify mixture prior Distribution\n θ ~ Mixture(john_is_right, (θ_jane, θ_john))\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This Mixture node updates the belief over c on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_mary = infer(\n model = beta_model_mary(nr_throws), \n data = (y = dataset, ),\n returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),\n addons = AddonLogScale(),\n postprocess = UnpackMarginalPostprocess(),\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (john_is_right, θ_john, θ, θ_jane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over theta also changed, and as expected the estimate from Jane was more prominent.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior belief\")\nplot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) Mary\", c=1)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label=\"\", c=3)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label=\"\", c=3)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/overview/#examples-basic_examples-overview","page":"Overview","title":"Basic examples","text":"","category":"section"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.\nBayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.\nKalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations\nPredicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.\nHow to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#examples-global-parameter-optimisation","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Univariate-State-Space-Model","page":"Global Parameter Optimisation","title":"Univariate State Space Model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us try use the following simple state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n x_t = x_t-1 + c \n y_t sim mathcalNleft(x_t p right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Our goal is to optimize parameters c and m_x_0.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)\n \n x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n)\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ x_prev + c\n y[i] ~ NormalMeanVariance(x[i], P)\n \n x_prev = x[i]\n end\n\n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"rng = MersenneTwister(42)\n\nP = 1.0\nn = 250\nc_real = -5.0\ndata = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# c[1] is C\n# c[2] is μ0\nfunction f(c)\n x0_prior = NormalMeanVariance(c[2], 100.0)\n result = infer(\n model = smoothing(n, x0_prior, c[1], P), \n data = (y = data,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using Optim","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 3.651509e+02 1.001412e+03\n * time: 0.023398876190185547\n * Status: success\n\n * Candidate solution\n Final objective value: 3.645772e+02\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.18e-06 ≰ 0.0e+00\n |x - x'|/|x'| = 2.30e-07 ≰ 0.0e+00\n |f(x) - f(x')| = 9.13e-07 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00\n |g(x)| = 2.56e-06 ≤ 1.0e-03\n\n * Work counters\n Seconds run: 6 (vs limit Inf)\n Iterations: 9\n f(x) calls: 67\n ∇f(x) calls: 67","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"2-element Vector{Float64}:\n 1.0007749243942134\n -5.14368311177876","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", [ 1.0, c_real ])\nprintln(\"Optimized: \", res.minimizer)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: [1.0, -5.0]\nOptimized: [1.0007749243942134, -5.14368311177876]","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Multivariate-state-space-model","page":"Global Parameter Optimisation","title":"Multivariate state space model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us consider the multivariate state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n mathbfx_t sim mathcalNleft(mathbfAx_t-1 mathbfQ right) \n mathbfy_t sim mathcalNleft(mathbfx_t mathbfP right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfx_0 sim mathcalN(mathbfm_x_0 mathbfV_x_0)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"and transition matrix ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfA = beginbmatrix costheta -sintheta sintheta costheta endbmatrix\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Covariance matrices mathbfV_x_0, mathbfP and mathbfQ are known. Our goal is to optimize parameters mathbfm_x_0 and theta.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)\n \n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n \n x_prev = x_prior\n \n A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)\n y[i] ~ MvNormalMeanCovariance(x[i], P)\n \n x_prev = x[i]\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Generate data\nfunction generate_rotate_ssm_data()\n rng = MersenneTwister(1234)\n\n θ = π / 8\n A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\n Q = Matrix(Diagonal(1.0 * ones(2)))\n P = Matrix(Diagonal(1.0 * ones(2)))\n\n n = 300\n\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n \n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(x[i], Q))\n \n x_prev = x[i]\n end\n\n return θ, A, Q, P, n, x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"generate_rotate_ssm_data (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"θ, A, Q, P, n, x, y = generate_rotate_ssm_data();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function f(θ)\n x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))\n result = infer(\n model = rotate_ssm(n, θ[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 2.192003e+04 9.032537e+04\n * time: 7.009506225585938e-5\n * Status: success\n\n * Candidate solution\n Final objective value: 1.161372e+03\n\n * Found with\n Algorithm: L-BFGS\n\n * Convergence measures\n |x - x'| = 5.09e-09 ≰ 0.0e+00\n |x - x'|/|x'| = 4.48e-10 ≰ 0.0e+00\n |f(x) - f(x')| = 0.00e+00 ≤ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14\n |g(x)| = 5.63e-07 ≰ 1.0e-12\n\n * Work counters\n Seconds run: 18 (vs limit Inf)\n Iterations: 9\n f(x) calls: 58\n ∇f(x) calls: 58","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", θ)\nprintln(\"Optimized: \", res.minimizer[1])\n\n@show sin(θ), sin(res.minimizer[1])\n@show cos(θ), cos(res.minimizer[1])","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: 0.39269908169872414\nOptimized: 0.3929332481380117\n(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)\n(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)\n(0.9238795325112867, 0.9237898955654058)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))\n\nresult = infer(\n model = rotate_ssm(n, res.minimizer[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n)\n\nxmarginals = result.posteriors[:x]\n\npx = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"inf₁\")\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"inf₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Learning-Kalman-filter-with-LSTM-driven-dynamic","page":"Global Parameter Optimisation","title":"Learning Kalman filter with LSTM driven dynamic","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Our objective is to compute the marginal posterior distribution of the latent (hidden) state x_k at each time step k, considering the history of measurements up to that time step:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"\np(x_k y_1k)\n\n\nThe above expression represents the probability distribution of the latent state x_k given the measurements y_1k up to time step k\n\njulia\nusing RxInfer BenchmarkTools Flux ReverseDiff Random Plots LinearAlgebra ProgressMeter JLD StableRNGs\n\n\n\n\n Generate data\n\njulia\n Lorenz system equations to be used to generate dataset\nBasekwdef mutable struct Lorenz\n dtFloat64\n σFloat64\n ρFloat64\n βFloat64\n xFloat64\n yFloat64\n zFloat64\nend\n\nfunction step(lLorenz)\n dx = lσ * (ly - lx) lx += ldt * dx\n dy = lx * (lρ - lz) - ly ly += ldt * dy\n dz = lx * ly - lβ * lz lz += ldt * dz\nend\n\n\n\n\njulia\n Dataset\nrng = StableRNG(999)\n\nordered_dataset = \nordered_parameters = \nfor σ = 1115\n for ρ = 2327\n for β_nom = 69\n attractor = Lorenz(002 σ ρ β_nom30 1 1 1)\n noise_free_data = 10 10 10\n for i=199\n step(attractor)\n push(noise_free_data attractorx attractory attractorz)\n end\n push(ordered_dataset noise_free_data)\n push(ordered_parameters σ ρ β_nom30)\n end\n end\nend\n\nnew_order = collect(1100)\nshuffle(rngnew_order)\n\ndataset = noisy dataset\nnoise_free_dataset = noise free dataset\nlorenz_parameters = \n\nfor i in new_order\n local data = \n push(noise_free_dataset ordered_dataseti)\n push(lorenz_parameters ordered_parametersi)\n for nfd in ordered_dataseti\n push(datanfd+randn(rng3))\n end\n push(dataset data)\nend\n\ntrainset = dataset160\nvalidset = dataset6180\ntestset = dataset81end\n\nnoise_free_trainset = noise_free_dataset160\nnoise_free_validset = noise_free_dataset6180\nnoise_free_testset = noise_free_dataset81end\n\n\n\n\n\n Data visualization\n\njulia\none_nonoise=noise_free_trainset1\none=trainset1\ngx gy gz = zeros(100) zeros(100) zeros(100)\nrx ry rz = zeros(100) zeros(100) zeros(100)\nfor i=1100\n rxi ryi rzi = onei1 onei2 onei3\n gxi gyi gzi = one_nonoisei1 one_nonoisei2 one_nonoisei3\nend\np1=plot(rxrylabel=Noise observations)\np1=plot(gxgylabel=True state)\nxlabel(x)\nylabel(y)\np2=plot(rxrzlabel=Noise observations)\np2=plot(gxgzlabel=True state)\nxlabel(x)\nylabel(z)\np3=plot(ryrzlabel=Noise observations)\np3=plot(gygzlabel=True state)\nxlabel(y)\nylabel(z)\nplot(p1 p2 p3 size = (800 200)layout=(13))\n\n\n(assetsexamplesGlobal Parameter Optimisation_22_1png)\n\n\n Inference\n\n\nWe use the following state-space model representation\n\nbeginaligned\nx_k sim p(x_k x_k-1) \ny_k sim p(y_k x_k)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where x_k sim p(x_k x_k-1) represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k-1=NN(y_k-1) \np(x_k x_k-1)=mathcalN(x_k A_k-1x_k-1 Q) \np(y_k x_k)=mathcalN(y_k Bx_k R)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where NN is the neural network. The input is the observation y_k-1, and output is the trasition matrix A_k-1. B denote distortion or measurment matrix. Q and R are covariance matrices. Note that the hidden state x_k comprises three coordinates, i.e. x_k = (rx_k ry_k rz_k)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Neural Network model\nmutable struct NN\n InputLayer\n OutputLater\n g\n params\n function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n InputLayer = Dense(W1, b1, relu)\n Lstm = LSTM(W2_1,W2_2,b2,s2_1)\n OutputLayer = Dense(W3, b3)\n g = Chain(InputLayer, OutputLayer);\n new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))\n end\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Model-specification","page":"Global Parameter Optimisation","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Note that we treat the trasition matrix A_k-1 as time-varying.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#State Space Model\n@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)\n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior_mean = zeros(3)\n x_prior_cov = Matrix(Diagonal(ones(3)))\n \n x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)\n y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }\n \n for i in 2:n\n x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }\n y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }\n end\n \n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We set distortion matrix B and the covariance matrices Q and R as identity matrix.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Q = Matrix(Diagonal(ones(3)))*2\nB = Matrix(Diagonal(ones(3)))\nR = Matrix(Diagonal(ones(3)))\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix A output by the neural network. And the A is treated as a datavar in the inference function.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n n = length(data)\n neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])\n return As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"get_matrix_AS (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"The weights of neural network NN are initialized as follows:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Initial model parameters\nW1, b1 = randn(5, 3)./100, randn(5)./100\nW2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)\nW3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Before network training, we show the inference results for the hidden states:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset before training\nindex = 1\ndata=testset[index]\nn=length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training-network","page":"Global Parameter Optimisation","title":"Training network","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this part, we use the Free Energy as the objective function to optimize the weights of network.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# free energy objective to be optimized during training\nfunction fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n fe_ = 0\n for train_instance in trainset\n result = infer(\n model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = train_instance, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n )\n fe_ += result.free_energy[end]\n end\n return fe_\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"fe_tot_est (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training","page":"Global Parameter Optimisation","title":"Training","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights\n# Uncomment the following code to train the network manually\n# opt = Flux.Optimise.RMSProp(0.006, 0.95)\n# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n# @showprogress for epoch in 1:800\n# grads = ReverseDiff.gradient(fe_tot_est, params);\n# for i=1:length(params)\n# Flux.Optimise.update!(opt,params[i],grads[i])\n# end\n# end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Test","page":"Global Parameter Optimisation","title":"Test","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Import the weights of neural network that we have trained.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load(\"../data/nn_prediction/weights.jld\")[\"data\"];","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset after training\nindex = 1\ndata = testset[index]\nn = length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\n\ngx, gy, gz = zeros(100), zeros(100), zeros(100)\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Prediction","page":"Global Parameter Optimisation","title":"Prediction","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill k and estimate the future state at time k+1, k+2, dots,k+T.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k=NN(x_k) \np(x_k+1 x_k)=mathcalN(x_k+1 A_kx_k Q) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#Define the prediction function\nmultiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))\nsumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)\n\nfunction runForward(A,B,Q,R,mh_old,Vh_old)\n mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)\n mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)\nend\n\nfunction g_predict(mh_old,Vh_old,Q)\n neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)\n # Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])\n As = As[1]\n return runForward(As,B,Q,R,mh_old,Vh_old), As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"g_predict (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"After k=75, the observations are not available, and we predict the future state from k=76 to the end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"tt = 75\nmh = mean(x_est[tt])\nVh = cov(x_est[tt])\nmo_list, Vo_list, A_list = [], [], [] \ninv_Q = inv(Q)\nfor t=1:100-tt\n (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)\n push!(mo_list, mo)\n push!(Vo_list, Vh)\n push!(A_list, A_t)\n global mh = mo\n global Vh = Vo\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Prediction visualization\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\nfor i=1:tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\nfor i=tt+1:100\n ii=i-tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]\nend\np1 = plot(rx,label=\"Ground truth rx\")\np1 = plot!(rx_est_m,label=\"Inffered state rx\",ribbon=rx_est_var)\np1 = scatter!(first.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Ground truth ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index][1:tt], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Ground truth rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#examples-autoregressive-models","page":"Autoregressive Models","title":"Autoregressive Models","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\np(gamma) = mathrmGamma(gammaa b)\np(mathbftheta) = mathcalN(mathbfthetamathbfmu Sigma)\np(x_tmathbfx_t-1t-k) = mathcalN(x_tmathbftheta^Tmathbfx_t-1t-k gamma^-1)\np(y_tx_t) = mathcalN(y_tx_t tau^-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where x_t is a current state of our system, mathbfx_t-1t-k is a sequence of k previous states, k is an order of autoregression process, mathbftheta is a vector of transition coefficients, gamma is a precision of state transition process, y_k is a noisy observation of x_k with precision tau.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's generate some synthetic dataset, we use a predefined sets of coeffcients for k = 1, 3 and 5 respectively:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The following coefficients correspond to stable poles\ncoefs_ar_1 = [-0.27002517200218096]\ncoefs_ar_2 = [0.4511170798064709, -0.05740081602446657]\ncoefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"function generate_ar_data(rng, n, θ, γ, τ)\n order = length(θ)\n states = Vector{Vector{Float64}}(undef, n + 3order)\n observations = Vector{Float64}(undef, n + 3order)\n \n γ_std = sqrt(inv(γ))\n τ_std = sqrt(inv(τ))\n \n states[1] = randn(rng, order)\n \n for i in 2:(n + 3order)\n states[i] = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])\n observations[i] = rand(rng, Normal(states[i][1], τ_std))\n end\n \n return states[1+3order:end], observations[1+3order:end]\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"generate_ar_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Seed for reproducibility\nseed = 123\nrng = MersenneTwister(seed)\n\n# Number of observations in synthetic dataset\nn = 500\n\n# AR process parameters\nreal_γ = 1.0\nreal_τ = 0.5\nreal_θ = coefs_ar_5\n\nstates, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's plot our synthetic dataset:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(first.(states), label = \"Hidden states\")\nscatter!(observations, label = \"Observations\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order k > 1 and for Univariate AR (reduces to simple State-Space-Model) with order k = 1.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function lar_model(T::Type, n, order, c, τ)\n \n \n # We create a sequence of random variables for hidden states\n x = randomvar(n)\n # As well a sequence of observartions\n y = datavar(Float64, n)\n \n ct = constvar(c)\n # We assume observation noise to be known\n cτ = constvar(τ)\n \n γ = randomvar()\n θ = randomvar()\n x0 = randomvar()\n \n # Prior for first state\n if T === Multivariate\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n else\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ Normal(μ = 0.0, γ = 1.0)\n x0 ~ Normal(μ = 0.0, γ = 1.0)\n end\n \n x_prev = x0\n \n for i in 1:n\n \n x[i] ~ AR(x_prev, θ, γ) \n \n if T === Multivariate\n y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)\n else\n y[i] ~ Normal(μ = ct * x[i], γ = cτ)\n end\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@constraints function ar_constraints() \n q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_constraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@meta function ar_meta(artype, order, stype)\n AR() -> ARMeta(artype, order, stype)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_meta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"morder = 5\nmartype = Multivariate\nmc = ReactiveMP.ar_unit(martype, morder)\nmconstraints = ar_constraints()\nmmeta = ar_meta(martype, morder, ARsafe())\n\nmoptions = (limit_stack_depth = 100, )\n\nmmodel = lar_model(martype, length(observations), morder, mc, real_τ)\nmdata = (y = observations, )\nminitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))\nmreturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\n# First execution is slow due to Julia's initial compilation \n# Subsequent runs will be faster (benchmarks are below)\nmresult = infer(\n model = mmodel, \n data = mdata,\n constraints = mconstraints,\n meta = mmeta,\n options = moptions,\n initmarginals = minitmarginals,\n returnvars = mreturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@unpack x, γ, θ = mresult.posteriors","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Dict{Symbol, Vector} with 3 entries:\n :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)\n, Ga…\n :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…\n :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We will use different initial marginals depending on type of our AR process","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p1 = plot(first.(states), label=\"Hidden state\")\np1 = scatter!(p1, observations, label=\"Observations\")\np1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label=\"Inferred states\", legend = :bottomright)\n\np2 = plot(mean.(γ), ribbon = std.(γ), label = \"Inferred transition precision\", legend = :topright)\np2 = plot!([ real_γ ], seriestype = :hline, label = \"Real transition precision\")\n\np3 = plot(mresult.free_energy, label = \"Bethe Free Energy\")\n\nplot(p1, p2, p3, layout = @layout([ a; b c ]))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's also plot a subrange of our results:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"subrange = div(n,5):(div(n, 5) + div(n, 5))\n\nplot(subrange, first.(states)[subrange], label=\"Hidden state\")\nscatter!(subrange, observations[subrange], label=\"Observations\")\nplot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label=\"Inferred states\", legend = :bottomright)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"It is also interesting to see where our AR coefficients converge to:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"let\n pθ = plot()\n\n θms = mean.(θ)\n θvs = var.(θ)\n \n l = length(θms)\n\n edim(e) = (a) -> map(r -> r[e], a)\n\n for i in 1:length(first(θms))\n pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = \"Estimated θ[$i]\")\n end\n \n for i in 1:length(real_θ)\n pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = \"Real θ[$i]\")\n end\n \n plot(pθ, legend = :outertopright, size = (800, 300))\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"$(length(real_θ))-order AR inference Bethe Free Energy: \", last(mresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"5-order AR inference Bethe Free Energy: 1024.0775661298358","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can also run a 1-order AR inference on 5-order AR data:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"uorder = 1\nuartype = Univariate\nuc = ReactiveMP.ar_unit(uartype, uorder)\nuconstraints = ar_constraints()\numeta = ar_meta(uartype, uorder, ARsafe())\n\nuoptions = (limit_stack_depth = 100, )\n\numodel = lar_model(uartype, length(observations), uorder, uc, real_τ)\nudata = (y = observations, )\nuinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))\nureturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\nuresult = infer(\n model = umodel, \n data = udata,\n meta = umeta,\n constraints = uconstraints,\n initmarginals = uinitmarginals,\n returnvars = ureturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"1-order AR inference Bethe Free Energy: \", last(uresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1-order AR inference Bethe Free Energy: 1025.8792949319954","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"if uresult.free_energy[end] > mresult.free_energy[end]\n println(\"We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.\")\nelse\n error(\"AR-1 performs better than AR-5...\") \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can see that, according to final Bethe Free Energy value, in this exampl\ne 5-order AR process can describe data better than 1-order AR.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Autoregressive-Moving-Average-Model","page":"Autoregressive Models","title":"Autoregressive Moving Average Model","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\ne_t sim mathcalN(0 gamma^-1) quad\ntheta sim mathcalMN(mathbf0 mathbfI) quad\neta sim mathcalMN(mathbf0 mathbfI) \nmathbfh_0 sim mathcalMNleft(beginbmatrix\ne_-1 \ne_-2\nendbmatrix mathbfIright) \nmathbfh_t = mathbfSmathbfh_t-1 + mathbfc e_t-1 \nmathbfx_t = boldsymboltheta^topmathbfx_t-1 + boldsymboleta^topmathbfh_t + e_t \nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where shift matrix mathbfS is","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfS = beginpmatrix\n0 0 \n1 0 \nendpmatrix\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"and unit vector mathbfc: ","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfc=1 0\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"when MA order is 2","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this way, mathbfh_t containing errors e_t can be viewed as hidden state.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., boldsymboleta^topmathbfh_t, (2) induced by errors e_t that prevents analytical update of precision parameter gamma (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Load packages\nusing RxInfer, LinearAlgebra, CSV, DataFrames, Plots","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Define shift function\nfunction shift(dim)\n S = Matrix{Float64}(I, dim, dim)\n for i in dim:-1:2\n S[i,:] = S[i-1, :]\n end\n S[1, :] = zeros(dim)\n return S\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"shift (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)\n \n c = zeros(p); c[1] = 1.0; # AR\n b = zeros(q); b[1] = 1.0; # MA\n S = shift(q); # MA\n \n # initialize variables\n h = randomvar(n-1)\n e = randomvar(n)\n z = randomvar(n)\n \n x = datavar(Float64, n) where { allow_missing = true }\n \n # priors\n γ ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))\n η ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))\n θ ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))\n τ ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))\n \n # initial\n h_0 ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))\n z[1] ~ AR(h_0, η, τ)\n e[1] ~ Normal(mean = 0.0, precision = γ)\n\n x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]\n \n h_prev = h_0\n for t in 1:n-1\n \n e[t+1] ~ Normal(mean = 0.0, precision = γ)\n h[t] ~ S*h_prev + b*e[t]\n z[t+1] ~ AR(h[t], η, τ)\n x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]\n h_prev = h[t]\n end\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"x_df = CSV.read(\"../data/arma/aal_stock.csv\", DataFrame)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1259×7 DataFrame\n Row │ date open high low close volume Name\n │ Date Float64 Float64 Float64 Float64 Int64 String3\n──────┼───────────────────────────────────────────────────────────────────\n 1 │ 2013-02-08 15.07 15.12 14.63 14.75 8407500 AAL\n 2 │ 2013-02-11 14.89 15.01 14.26 14.46 8882000 AAL\n 3 │ 2013-02-12 14.45 14.51 14.1 14.27 8126000 AAL\n 4 │ 2013-02-13 14.3 14.94 14.25 14.66 10259500 AAL\n 5 │ 2013-02-14 14.94 14.96 13.16 13.99 31879900 AAL\n 6 │ 2013-02-15 13.93 14.61 13.93 14.5 15628000 AAL\n 7 │ 2013-02-19 14.33 14.56 14.08 14.26 11354400 AAL\n 8 │ 2013-02-20 14.17 14.26 13.15 13.33 14725200 AAL\n ⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮\n 1253 │ 2018-01-30 52.45 53.05 52.36 52.59 4741808 AAL\n 1254 │ 2018-01-31 53.08 54.71 53.0 54.32 5962937 AAL\n 1255 │ 2018-02-01 54.0 54.64 53.59 53.88 3623078 AAL\n 1256 │ 2018-02-02 53.49 53.99 52.03 52.1 5109361 AAL\n 1257 │ 2018-02-05 51.99 52.39 49.75 49.76 6878284 AAL\n 1258 │ 2018-02-06 49.32 51.5 48.79 51.18 6782480 AAL\n 1259 │ 2018-02-07 50.91 51.98 50.89 51.4 4845831 AAL\n 1244 rows omitted","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# we will use \"close\" column\nx_data = filter(!ismissing, x_df[:, 5]);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Plot data\nplot(x_data, xlabel=\"day\", ylabel=\"price\", label=false)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p_order = 10 # AR\nq_order = 4 # MA","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"4","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Training set\ntrain_size = 1000\nx_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]\nx_train = Float64.(x_data[p_order+1:end])[1:train_size];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Test set\nx_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]\nx_test = Float64.(x_data[p_order+1:end])[train_size+1:end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Inference","page":"Autoregressive Models","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Constraints are needed for performing VMP\narma_constraints = @constraints begin\n q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)\nend;","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# This cell defines prior knowledge for model parameters\nh_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nγ_prior = GammaShapeRate(1e4, 1.0)\nτ_prior = GammaShapeRate(1e2, 1.0)\nη_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nθ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Model's graph has structural loops, hence, it requires pre-initialisation\narma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);\narma_imessages = (h_0 = h_prior, h = h_prior);\narma_meta = ar_meta(Multivariate, q_order, ARsafe());","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"result = infer(\n model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), \n data = (x = x_train, ),\n initmarginals = arma_imarginals,\n initmessages = arma_imessages,\n constraints = arma_constraints,\n meta = arma_meta,\n iterations = 50,\n options = (limit_stack_depth = 400, ),\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = \"eₜ\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# extract posteriors\nh_posterior = result.posteriors[:h][end][end]\nγ_posterior = result.posteriors[:γ][end]\nτ_posterior = result.posteriors[:τ][end]\nη_posterior = result.posteriors[:η][end]\nθ_posterior = result.posteriors[:θ][end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Prediction","page":"Autoregressive Models","title":"Prediction","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Here we are going to use our inference results in order to predict the dataset itself","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The prediction function is aimed at approximating the predictive posterior distribution\n# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)\nfunction prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)\n h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))\n ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))\n c = zeros(p); c[1] = 1.0\n b = zeros(q); b[1] = 1.0\n ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)\n θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))\n ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)\n e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))\n ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out) \n @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out) \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"prediction (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"predictions = []\nfor x_prev in x_prev_test\n push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))\n # after every new prediction we can actually \"retrain\" the model to use the power of Bayesian approach\n # we will skip this part at this notebook\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(x_test, label=\"test data\", legend=:topleft)\nplot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label=\"predicted\", xlabel=\"day\", ylabel=\"price\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/#examples-how-to-train-your-hidden-markov-model","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"","category":"section"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate()\n;","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time t, let's call the estimate of the Roomba's position s_t.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call A.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"At time t, we will call our observations x_t and encode the mapping from the Roomba's position to the observations in a matrix we call B. B also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"beginaligned\n s_t sim mathcalCat(A s_t-1)\n x_t sim mathcalCat(B s_t)\nendaligned","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices A and B so we can use them to track the whereabouts of our little cleaning agent.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"To generate our observation data, we'll follow these steps:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.\nDetermine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.\nDetermine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.\nRepeat steps 2-3 for as many samples as we want.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"The following code implements this process and generates our observation data:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"\"\"\"\n rand_vec(rng, distribution::Categorical)\n\nThis function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.\n\"\"\"\nfunction rand_vec(rng, distribution::Categorical) \n k = ncategories(distribution)\n s = zeros(k)\n drawn_category = rand(rng, distribution)\n s[drawn_category] = 1.0\n return s\nend\n\nfunction generate_data(n_samples; seed = 42)\n \n rng = MersenneTwister(seed)\n \n # Transition probabilities \n state_transition_matrix = [0.9 0.0 0.1;\n 0.0 0.9 0.1; \n 0.05 0.05 0.9] \n # Observation noise\n observation_distribution_matrix = [0.9 0.05 0.05;\n 0.05 0.9 0.05;\n 0.05 0.05 0.9] \n # Initial state\n s_initial = [1.0, 0.0, 0.0] \n \n states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states\n observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations\n \n s_prev = s_initial\n \n for t = 1:n_samples\n s_probvec = state_transition_matrix * s_prev\n states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))\n obs_probvec = observation_distribution_matrix * states[t]\n observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))\n s_prev = states[t]\n end\n \n return observations, states\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Test data\nN = 100\nx_data, s_data = generate_data(N);\n\nscatter(argmax.(s_data), leg=false, xlabel=\"Time\",yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the A and B matrices we can use MatrixDirichlet priors. For the A-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on A with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on B. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Model specification\n@model function hidden_markov_model(n)\n \n A ~ MatrixDirichlet(ones(3,3))\n B ~ MatrixDirichlet([ 10.0 1.0 1.0; \n 1.0 10.0 1.0; \n 1.0 1.0 10.0 ])\n \n s_0 ~ Categorical(fill(1.0 / 3.0, 3))\n \n s = randomvar(n)\n x = datavar(Vector{Float64}, n)\n \n s_prev = s_0\n \n for t in 1:n\n s[t] ~ Transition(s_prev, A) \n x[t] ~ Transition(s[t], B)\n s_prev = s[t]\n end\n \nend\n\n# Constraints specification\n@constraints function hidden_markov_model_constraints()\n q(s_0, s, A, B) = q(s_0, s)q(A)q(B)\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"hidden_markov_model_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"imodel = hidden_markov_model(N)\nidata = (x = x_data,)\n\nimarginals = (\n A = vague(MatrixDirichlet, 3, 3), \n B = vague(MatrixDirichlet, 3, 3), \n s = vague(Categorical, 3)\n)\n\nireturnvars = (\n A = KeepLast(),\n B = KeepLast(),\n s = KeepLast()\n)\n\nresult = infer(\n model = imodel, \n data = idata,\n constraints = hidden_markov_model_constraints(),\n initmarginals = imarginals, \n returnvars = ireturnvars, \n iterations = 20, \n free_energy = true\n);","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over A) and about the uncertainty in the roombas observations (A good posterior over B). Let's see if it worked","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for A:\")\nmean(result.posteriors[:A])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for A:\n3×3 Matrix{Float64}:\n 0.871955 0.0290008 0.0572283\n 0.0349989 0.817591 0.135675\n 0.0930457 0.153408 0.807097","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for B:\")\nmean(result.posteriors[:B])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for B:\n3×3 Matrix{Float64}:\n 0.949636 0.0974741 0.0518997\n 0.0244903 0.833632 0.0277884\n 0.0258734 0.0688939 0.920312","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"p1 = scatter(argmax.(s_data), \n title=\"Inference results\", \n label = \"Real\", \n ms = 6, \n legend=:right,\n xlabel=\"Time\" ,\n yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]),\n size=(900,550)\n )\n\np1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),\n label = \"Inferred\",\n ms = 3\n )\n\np2 = plot(result.free_energy, \n label=\"Free energy\",\n xlabel=\"Iteration Number\"\n )\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#examples-rts-vs-bifm-smoothing","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"___Credits to Martin de Quincey___","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762\nH. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"We perform Kalman smoothing in the linear state space model, represented by:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n Z_k+1 = A Z_k + B U_k \n Y_k = C Z_k + W_k\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"with observations Y_k, latent states Z_k and inputs U_k. W_k is the observation noise. A in mathrmR^n times n, B in mathrmR^n times m and C in mathrmR^d times n are the transition matrices in the model. Here n, m and d denote the dimensionality of the latent, input and output dimension, respectively.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"The corresponding probabilistic model can be represented as ","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n p(y z u)\n = p(z_0) prod_k=1^N p(y_k mid z_k) p(z_kmid z_k-1 u_k-1) p(u_k-1) \n = mathcalN(z_0 mid mu_z_0 Sigma_z_0) left( prod_k=1^N mathcalN(y_k mid C z_k Sigma_W) delta(z_k - (Az_k-1 + Bu_k-1)) mathcalN(u_k-1 mid mu_i_k-1 Sigma_u_k-1) right)\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Import-packages","page":"RTS vs BIFM Smoothing","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Data-generation","page":"RTS vs BIFM Smoothing","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)\n \n # define noise levels\n input_noise = 500.0\n output_noise = 50.0\n\n # create random generator for reproducibility\n rng = MersenneTwister(seed)\n\n # generate matrices, input statistics and noise matrices\n A = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat)) # size (dim_lat x dim_lat)\n B = rand(dim_lat, dim_in) # size (dim_lat x dim_in)\n C = rand(dim_out, dim_lat) # size (dim_out x dim_lat)\n μu = rand(dim_in) .* collect(1:dim_in) # size (dim_in x 1)\n Σu = input_noise .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in)))) # size (dim_in x dim_in)\n Σy = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out)))) # size (dim_out x dim_out)\n Wu = inv(Σu)\n Wy = inv(Σy)\n \n # return parameters\n return A, B, C, μu, Σu, Σy, Wu, Wy\n\nend;","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)\n \n # create random data generator\n rng = StableRNG(seed)\n \n # preallocate space for variables\n z = Vector{Vector{Float64}}(undef, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n u = rand(rng, MvNormal(μu, Σu), nr_samples)'\n \n # set initial value of latent states\n z_prev = zeros(size(A,1))\n \n # generate data\n for i in 1:nr_samples\n\n # generate new latent state\n z[i] = A * z_prev + B * u[i,:]\n\n # generate new observation\n y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))\n \n # generate new observation\n z_prev .= z[i]\n \n end\n \n # return generated data\n return z, y, u\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# specify settings\nnr_samples = 200\ndim_out = 3\ndim_in = 3\ndim_lat = 25\n\n# generate parameters\nA, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);\n \n# generate data\ndata_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);\n\n# visualise data\np = Plots.plot(xlabel = \"sample\", ylabel = \"observations\")\n# plot each dimension independently\nfor i in 1:dim_out\n Plots.scatter!(p, getindex.(data_y, i), label = \"y_$i\", alpha = 0.5, ms = 2)\nend\np","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Model-specification","page":"RTS vs BIFM Smoothing","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n \n # fetch dimensionality\n dim_lat = size(A, 1)\n dim_out = size(C, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # hidden states (random variable)\n u = randomvar(nr_samples) # inputs (random variable)\n y = datavar(Vector{Float64}, nr_samples) # outputs (observed variables)\n \n # set initial hidden state\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n \n # update last/previous hidden state\n z_prev = z_prior\n\n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n \n # specify updated hidden state\n z[i] ~ A * z_prev + B * u[i]\n \n # specify observation\n y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n\n # fetch dimensionality\n dim_lat = size(A, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # latent states\n yt = randomvar(nr_samples) # latent observations\n y = datavar(Vector{Float64}, nr_samples) # actual observations\n u = randomvar(nr_samples) # inputs\n \n # set priors\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n z_tmp ~ BIFMHelper(z_prior) where { q = MeanField() }\n \n # update last/previous hidden state\n z_prev = z_tmp\n \n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n\n # specify observation\n yt[i] ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }\n y[i] ~ MvNormalMeanPrecision(yt[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \n # set final value\n z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Probabilistic-inference","page":"RTS vs BIFM Smoothing","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_RTS(data_y, A, B, C, μu, Wu, Wy)\n \n # In this task the inference is unstable and can diverge\n meta = @meta begin \n *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)\n end\n \n result = infer(\n model = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast()),\n meta = meta\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_RTS (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)\n result = infer(\n model = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast())\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_BIFM (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Experiments-for-200-observations","page":"RTS vs BIFM Smoothing","title":"Experiments for 200 observations","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)\nz_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\n\nmz_RTS = mean.(z_RTS)\nmz_BIFM = mean.(z_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:5\n Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\n\nrdata_u = collect(eachrow(data_u))\nmu_RTS = mean.(u_RTS)\nmu_BIFM = mean.(u_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:1\n Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Benchmark","page":"RTS vs BIFM Smoothing","title":"Benchmark","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation\n# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`\nrun_benchmark = false\n\nif run_benchmark\n trials_range = 30\n trials_n = 500\n trials_RTS = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n\n\n @showprogress for k = 1 : trials_range\n\n # generate parameters\n local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);\n \n # generate data|\n local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);\n\n # run inference\n trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n\n end\n\n m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9\n q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9\n m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9\n q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;\n\n p = Plots.plot(ylabel = \"duration [sec]\", xlabel = \"latent state dimension\", title = \"Benchmark\", yscale = :log)\n p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = \"blue\", label = \"mean (RTS)\")\n p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = \"orange\", label = \"mean (BIFM)\")\n Plots.savefig(p, \"../pics/rts_bifm_benchmark.png\")\n p\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"manuals/meta-specification/#user-guide-meta-specification","page":"Meta specification","title":"Meta Specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.","category":"page"},{"location":"manuals/meta-specification/#General-syntax","page":"Meta specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts either regular Julia function or a single begin ... end block:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function MyModelMeta(arg1, arg2)\n Node(y,x) -> MetaObject(arg1, arg2)\nend\n\nmy_meta = @meta begin \n Node(y,x) -> MetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order 5 can be specified as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function ARmodel_meta(num_order)\n AR() -> ARMeta(Univariate, num_order, ARsafe())\nend\n\nmy_meta = ARmodel_meta(5)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"num_order = 5\n\nmy_meta = @meta begin \n AR() -> ARMeta(Multivariate, num_order, ARsafe())\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Both syntax variations provide the same meta specification and there is no preference given to one over the other. ","category":"page"},{"location":"manuals/meta-specification/#Options-specification","page":"Meta specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta [ warn = false ] begin \n ...\nend\n\n@meta [ warn = false ] function MyModelMeta()\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"List of available options:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/meta specification","category":"page"},{"location":"manuals/meta-specification/#Meta-specification","page":"Meta specification","title":"Meta specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"First, let's start with an example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"You can have a list of as many meta specification entries as possible for different nodes:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))\n AR() -> ARMeta(Multivariate, 5, ARsafe())\n MyCustomNode() -> MyCustomMetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model(arguments...)\n ...\nend\n\nmy_meta = @meta begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); meta = my_meta)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"inferred_result = infer(\n model = my_model(arguments...),\n meta = my_meta,\n ...\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model()\n ...\n\n y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }\n\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.","category":"page"},{"location":"manuals/meta-specification/#Create-your-own-meta","page":"Meta specification","title":"Create your own meta","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for your custom node\nstruct MyCustomMeta\n arg1 \n arg2 \nend\n\n# apply the new meta structure to your node\n@meta function model_meta(arg1, arg2)\n MyCustomNode() -> MyCustomMeta(arg1,arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"or create different meta structures for a node, e.g. AR node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for the AR node\nstruct MyARMeta\n arg1\n arg2\nend\n\n# apply the new meta structure to the AR node\n@meta function model_meta(arg1, arg2)\n AR() -> MyARMeta(arg1, arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.","category":"page"},{"location":"manuals/meta-specification/#Example","page":"Meta specification","title":"Example","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"beginaligned\n x sim mathrmNormal(25 05)\n y sim mathrmNormal(2*x 20)\nendaligned","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"where y is observable data and x is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"using RxInfer\n\n#create data\ny_data = 4.0 \n\n#make model\n@model function gaussian_model()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\n#do inference\ninference_result = infer(\n model = gaussian_model(),\n data = (y = y_data,)\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean m clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#create your new meta structure for Normal node\nstruct MetaConstrainedMeanNormal{T}\n lower_limit :: T\n upper_limit :: T\nend\n\n#define rules with meta for the Normal node\n@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))\nend\n\n@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#make model\n@model function gaussian_model_with_meta()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\ncustom_meta = @meta begin\n NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)\nend\n\n#do inference\ninference_result = inference(\n model = gaussian_model(),\n data = (y = y_data,),\n meta = custom_meta\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution","page":"Overview","title":"Inference execution","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"Belief Propagation\nVariational Message Passing","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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.","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-static","page":"Overview","title":"Automatic inference specification on static datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-realtime","page":"Overview","title":"Automatic inference specification on real-time datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-manual-specification","page":"Overview","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#examples-chance-constrained-active-inference","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, \"Chance-constrained active inference\") and discussion with John Boik.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Plots, Distributions, StatsFuns, RxInfer","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Chance-Constraint-Node-Definition","page":"Chance-Constrained Active Inference","title":"Chance-Constraint Node Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not \"overflow\" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"struct ChanceConstraint end \n\n# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol\n@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Function to compute normalizing constant and central moments of a truncated Gaussian distribution\nfunction truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)\n V = clamp(V, tiny, huge)\n StdG = Distributions.Normal(m, sqrt(V))\n TrG = Distributions.Truncated(StdG, a, b)\n \n Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a) # safe mass for standard Gaussian\n \n if Z < tiny\n # Invalid region; return undefined mean and variance of truncated distribution\n Z = 0.0\n m_tr = 0.0\n V_tr = 0.0\n else\n m_tr = Distributions.mean(TrG)\n V_tr = Distributions.var(TrG)\n end\n \n return (Z, m_tr, V_tr)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@rule ChanceConstraint(:out, Marginalisation) (\n m_out::UnivariateNormalDistributionsFamily, # Require inbound message\n q_lo::PointMass, \n q_hi::PointMass, \n q_epsilon::PointMass, \n q_atol::PointMass) = begin \n\n # Extract parameters\n lo = mean(q_lo)\n hi = mean(q_hi)\n epsilon = mean(q_epsilon)\n atol = mean(q_atol)\n \n (m_bw, V_bw) = mean_var(m_out)\n (xi_bw, W_bw) = (m_bw, 1. /V_bw) # check division by zero\n (m_tilde, V_tilde) = (m_bw, V_bw)\n \n # Compute statistics (and normalizing constant) of q in safe region G\n # Phi_G is called the \"safe mass\" \n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)\n\n xi_fw = xi_bw\n W_fw = W_bw\n if epsilon <= 1.0 - Phi_G # If constraint is active\n # Initialize statistics of uncorrected belief\n m_tilde = m_bw\n V_tilde = V_bw\n for i = 1:100 # Iterate at most this many times\n (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G\n (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G\n\n # Compute moments of non-G region as a mixture of left and right truncations\n Phi_nG = Phi_lG + Phi_rG\n m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG\n V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2\n\n # Compute moments of corrected belief as a mixture of G and non-G regions\n m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG\n V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2\n # Re-compute statistics (and normalizing constant) of corrected belief\n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)\n if (1.0 - Phi_G) < (1.0 + atol)*epsilon\n break # Break the loop if the belief is sufficiently corrected\n end\n end\n \n # Convert moments of corrected belief to canonical form\n W_tilde = inv(V_tilde)\n xi_tilde = W_tilde * m_tilde\n\n # Compute canonical parameters of forward message\n xi_fw = xi_tilde - xi_bw\n W_fw = W_tilde - W_bw\n end\n\n return NormalWeightedMeanPrecision(xi_fw, W_fw)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Definition-of-the-Environment","page":"Chance-Constrained Active Inference","title":"Definition of the Environment","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile\n\nfunction initializeWorld()\n x_0 = 0.0 # Initial elevation\n \n x_t_last = x_0\n function execute(t::Int64, a_t::Float64)\n x_t = x_t_last + a_t + wind(t) # Update elevation\n \n x_t_last = x_t # Reset state\n \n return x_t\n end\n\n x_t = x_0 # Predefine outcome variable\n observe() = x_t # State is fully observed\n\n return (execute, observe)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Generative-Model-for-Regulator","page":"Chance-Constrained Active Inference","title":"Generative Model for Regulator","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@model function regulator_model(; T, lo, hi, epsilon, atol)\n # Fully observed state\n x_t = datavar(Float64)\n\n # Control prior statistics\n m_u = datavar(Float64, T)\n v_u = datavar(Float64, T) \n \n # Random variables\n u = randomvar(T) # Control\n x = randomvar(T) # Elevation\n \n # Loop over horizon\n x_k_last = x_t\n for k = 1:T\n u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior\n x[k] ~ x_k_last + u[k] # Transition model\n x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state\n pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency\n x_k_last = x[k]\n end\n \n return (u, x)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Reactive-Agent-Definition","page":"Chance-Constrained Active Inference","title":"Reactive Agent Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"function initializeAgent()\n # Set control prior statistics\n m_u = zeros(T)\n v_u = lambda^(-1)*ones(T)\n \n function compute(x_t::Float64)\n model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)\n data_t = (m_u = m_u, v_u = v_u, x_t = x_t)\n \n result = infer(\n model = model_t, \n data = data_t,\n iterations = n_its)\n\n # Extract policy from inference results\n pol = mode.(result.posteriors[:u][end])\n\n return pol\n end\n\n pol = zeros(T) # Predefine policy variable\n act() = pol[1]\n\n return (compute, act)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Action-Perception-Cycle","page":"Chance-Constrained Active Inference","title":"Action-Perception Cycle","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Simulation parameters\nN = 160 # Total simulation time\nT = 1 # Lookahead time horizon\nlambda = 1.0 # Control prior precision\nlo = 1.0 # Chance region lower bound\nhi = Inf # Chance region upper bound\nepsilon = 0.01 # Allowed chance violation\natol = 0.01 # Convergence tolerance for chance constraints\nn_its = 10; # Number of inference iterations","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(execute, observe) = initializeWorld() # Let there be a world\n(compute, act) = initializeAgent() # Let there be an agent\n\na = Vector{Float64}(undef, N) # Actions\nx = Vector{Float64}(undef, N) # States\nfor t = 1:N\n a[t] = act()\n execute(t, a[t])\n x[t] = observe()\n compute(x[t])\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Results","page":"Chance-Constrained Active Inference","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Results show that the agent does not allow the wind to push it all the way to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"p1 = plot(1:N, wind.(1:N), color=\"blue\", label=\"Wind\", ylabel=\"Velocity\", lw=2)\nplot!(p1, 1:N, a, color=\"red\", label=\"Control\", lw=2)\np2 = plot(1:N, x, color=\"black\", lw=2, label=\"Agent\", ylabel=\"Elevation\")\nplot(p1, p2, layout=(2,1))","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#examples-gamma-mixture-model","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Load-packages","page":"Gamma Mixture Model","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"using RxInfer, Random, StatsPlots","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# create custom structure for model parameters for simplicity\nstruct GammaMixtureModelParameters\n nmixtures # number of mixtures\n priors_as # tuple of priors for variable a\n priors_bs # tuple of priors for variable b\n prior_s # prior of variable s\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Model-specification","page":"Gamma Mixture Model","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)\n\n # fetch information from struct\n nmixtures = parameters.nmixtures\n priors_as = parameters.priors_as\n priors_bs = parameters.priors_bs\n prior_s = parameters.prior_s\n\n # set prior on global selection variable\n s ~ Dirichlet(probvec(prior_s))\n\n # allocate vectors of random variables\n as = randomvar(nmixtures)\n bs = randomvar(nmixtures)\n\n # set priors on variables of mixtures\n for i in 1:nmixtures\n as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))\n bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))\n end\n\n # introduce random variables for local selection variables and data\n z = randomvar(nobservations)\n y = datavar(Float64, nobservations)\n\n # convert vector to tuples for proper functioning of GammaMixture node\n tas = tuple(as...)\n tbs = tuple(bs...)\n\n # specify local selection variable and data generating process\n for i in 1:nobservations\n z[i] ~ Categorical(s)\n y[i] ~ GammaMixture(z[i], tas, tbs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"constraints = @constraints begin \n\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n\n q(as) = q(as[begin])..q(as[end])\n q(bs) = q(bs[begin])..q(bs[end])\n \n q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Constraints:\n marginals form:\n q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n q(as) = q(as[(begin)..(end)])\n q(bs) = q(bs[(begin)..(end)])\nOptions:\n warn = true","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify seed and number of data points\nrng = MersenneTwister(43)\nn_samples = 2500\n\n# specify parameters of mixture model that generates the data\n# Note that mixture components have exactly the same means\nmixtures = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]\nnmixtures = length(mixtures)\nmixing = rand(rng, nmixtures)\nmixing = mixing ./ sum(mixing)\nmixture = MixtureModel(mixtures, mixing)\n\n# generate data set\ndataset = rand(rng, mixture, n_samples);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify priors of probabilistic model\n# NOTE: As the means of the mixtures \"collide\", we specify informative prior for selector variable\nnmixtures = 2\ngpriors = GammaMixtureModelParameters(\n nmixtures, # number of mixtures\n [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ], # priors on variables a\n [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ], # priors on variables b\n Dirichlet(1e3*mixing) # prior on variable s\n)\n\ngmodel = gamma_mixture_model(length(dataset), gpriors)\ngdata = (y = dataset, )\nginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))\ngreturnvars = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())\n\ngoptions = (\n \n default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently\n)\n\ngresult = infer(\n model = gmodel, \n data = gdata,\n constraints = constraints,\n options = (limit_stack_depth = 100,),\n initmarginals = ginitmarginals,\n returnvars = greturnvars,\n free_energy = true,\n iterations = 250, \n showprogress = true\n);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# extract inferred parameters\n_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])\n_dists = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))\n_mixing = mean(gresult.posteriors[:s])\n\n# create model from inferred parameters\n_mixture = MixtureModel(_dists, _mixing);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# report on outcome of inference\nprintln(\"Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))\")\nprintln(\"Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))\")\nprintln(\"========\")\nprintln(\"Generated mixing: $(mixing)\")\nprintln(\"Inferred mixing: $(_mixing)\")","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Generated means: 0.3333333333333333 and 0.33333333333333337\nInferred means: 0.33822470398804994 and 0.33305534672666653\n========\nGenerated mixing: [0.18923488676601088, 0.8107651132339891]\nInferred mixing: [0.11395888467453213, 0.8860411153254679]","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# plot results\np1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np1 = plot!(mixture, label=false, title=\"Generated mixtures\", linewidth=3.0)\n\np2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np2 = plot!(_mixture, label=false, title=\"Inferred mixtures\", linewidth=3.0)\n\n# evaluate the convergence of the algorithm by monitoring the BFE\np3 = plot(gresult.free_energy, label=false, xlabel=\"iterations\", title=\"Bethe FE\")\n\nplot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#examples-gaussian-mixture","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Load-packages","page":"Gaussian Mixture","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Univariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Univariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Consider the data set of length N observed below.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_univariate_data(nr_samples; rng = MersenneTwister(123))\n\n # data generating parameters\n class = [1/3, 2/3]\n mean1, mean2 = -10, 10\n precision = 1.777\n\n # generate data\n z = rand(rng, Categorical(class), nr_samples)\n y = zeros(nr_samples)\n for k in 1:nr_samples\n y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_univariate = generate_univariate_data(100)\nhistogram(data_univariate, bins=50, label=\"data\", normed=true)\nxlims!(minimum(data_univariate), maximum(data_univariate))\nylims!(0, Inf)\nylabel!(\"relative occurrence [%]\")\nxlabel!(\"y\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m w z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(w_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmBeta(s mid alpha_s beta_s) \n p(m_k) = mathcalN(m_k mid mu_k sigma_k^2) p(w_k) = Gamma(w_k mid alpha_k beta_k) \n p(z_n mid s) = mathrmBer(z_n mid s) \n p(y_n mid m w z_n) = prod_k=1^K mathcalNleft(y_n mid m_k w_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions w = w_1 w_2 ldots w_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Here we implement the following model with uninformative values for the hyperparameters as","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function univariate_gaussian_mixture_model(nr_samples)\n \n s ~ Beta(1.0, 1.0)\n \n m1 ~ Normal(mean = -2.0, var = 1e3)\n w1 ~ Gamma(shape = 0.01, rate = 0.01)\n \n m2 ~ Normal(mean = 2.0, var = 1e3)\n w2 ~ Gamma(shape = 0.01, rate = 0.01)\n \n z = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n \n for n in 1:nr_samples\n z[n] ~ Bernoulli(s)\n y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m w mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m w mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(w_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmBeta(s mid hatalpha_s hatbeta_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatsigma^2_k) \n q(w_k) = Gamma (w_k mid hatalpha_k hatbeta_k) \n q(z_n) = mathrmBer(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"results_univariate = infer(\n model = univariate_gaussian_mixture_model(length(data_univariate)), \n constraints = MeanField(),\n data = (y = data_univariate,), \n initmarginals = (\n s = vague(Beta), \n m1 = NormalMeanVariance(-2.0, 1e3), \n m2 = NormalMeanVariance(2.0, 1e3), \n w1 = vague(GammaShapeRate), \n w2 = vague(GammaShapeRate)\n ), \n iterations = 10, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m2, m1, s, w2, w1, z)\n Free Energy: | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.\n277, 135.277, 135.277, 135.277, 135.277]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen as a function of the iterations","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L\"posterior $m_1$\")\nmp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L\"posterior $m_2$\")\nmp = plot!(mp, [ -10 ], seriestype = :hline, label = L\"true $m_1$\")\nmp = plot!(mp, [ 10 ], seriestype = :hline, label = L\"true $m_2$\")\n\nwp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L\"posterior $w_1$\", legend = :bottomright, ylim = (-1, 3))\nwp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L\"posterior $w_2$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_1$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_2$\")\n\nswp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L\"posterior $s$\")\nswp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L\"true $s$\")\n\nfep = plot(results_univariate.free_energy, label = \"Free Energy\", legend = :topright)\n\nplot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))\nxlabel!(\"iteration\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Multivariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Multivariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The above example can also be extended to the multivariate case. Consider the data set below","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))\n\n L = 50.0\n nr_mixtures = 6\n\n probvec = normalize!(ones(nr_mixtures), 1)\n\n switch = Categorical(probvec)\n\n gaussians = map(1:nr_mixtures) do index\n angle = 2π / nr_mixtures * (index - 1)\n basis_v = L * [ 1.0, 0.0 ]\n R = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]\n mean = R * basis_v \n covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))\n return MvNormal(mean, covariance)\n end\n\n z = rand(rng, switch, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n\n for n in 1:nr_samples\n y[n] = rand(rng, gaussians[z[n]])\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_multivariate = generate_multivariate_data(500)\n\nsdim(n) = (a) -> map(d -> d[n], a) # helper function\nscatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)\nxlabel!(L\"y_1\")\nylabel!(L\"y_2\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification-2","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m W z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(W_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmDir(s mid alpha_s) \n p(m_k) = mathcalN(m_k mid mu_k Sigma_k) p(W_k) = mathcalW(W_k mid V_k nu_k) \n p(z_n mid s) = mathrmCat(z_n mid s) \n p(y_n mid m W z_n) = prod_k=1^K mathcalNleft(y_n mid m_k W_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions W = W_1 W_2 ldots W_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)\n \n z = randomvar(nr_samples)\n m = randomvar(nr_mixtures)\n w = randomvar(nr_mixtures)\n y = datavar(Vector{Float64}, nr_samples)\n \n for k in 1:nr_mixtures \n m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])\n w[k] ~ Wishart(3, 1e2*diagm(ones(2)))\n end\n \n s ~ Dirichlet(ones(nr_mixtures))\n \n means = tuple(m...)\n precs = tuple(w...)\n \n for n in 1:nr_samples\n z[n] ~ Categorical(s) \n y[n] ~ NormalMixture(z[n], means, precs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference-2","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m W mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m W mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(W_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmDir(s mid hatalpha_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatSigma_k) \n q(w_k) = mathcalW(W_k mid hatV_k hatnu_k) \n q(z_n) = mathrmCat(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"rng = MersenneTwister(121)\nm = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]\nresults_multivariate = infer(\n model = multivariate_gaussian_mixture_model(\n 6, \n length(data_multivariate), \n m,\n [diagm(1e2 * ones(2)) for k in 1:6]\n ), \n data = (y = data_multivariate,), \n constraints = MeanField(),\n initmarginals = (\n s = vague(Dirichlet, 6), \n m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], \n w = Wishart(3, diagm(1e2 * ones(2)))\n ), \n iterations = 50, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m, w, s, z)\n Free Energy: | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49 … 3894.49, 3894.49, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results-2","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title=\"Data\", xlims=(-75, 75), ylims=(-75, 75))\np_result = plot(xlims = (-75, 75), ylims = (-75, 75), title=\"Inference result\", legend=false, colorbar = false)\nfor (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])\n gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))\n global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title=\"Inference result\", legend=false, levels = 7, colorbar = false)\nend\np_fe = plot(results_multivariate.free_energy, label = \"Free Energy\")\n\nplot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#examples-kalman-filtering-and-smoothing","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We then solve an identification problem which does not have an analytical solution.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Utimately, we show how RxInfer.jl can deal with missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Gaussian-Linear-Dynamical-System","page":"Kalman filtering and smoothing","title":"Gaussian Linear Dynamical System","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"LGSSM can be described with the following equations:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n p(x_ix_i - 1) = mathcalN(x_iA * x_i - 1 mathcalP)\n p(y_ix_i) = mathcalN(y_iB * x_i mathcalQ)\nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"where x_i are hidden states, y_i are noisy observations, A, B are state transition and observational matrices, mathcalP and mathcalQ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(rng, A, B, Q, P)\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(B * x[i], P))\n x_prev = x[i]\n end\n \n return x, y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Seed for reproducibility\nseed = 1234\n\nrng = MersenneTwister(1234)\n\n# We will model 2-dimensional observations with rotation matrix `A`\n# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`\n# are known and fixed for all time-steps\nθ = π / 35\nA = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\nB = diageye(2)\nQ = diageye(2)\nP = 25.0 .* diageye(2)\n\n# Number of observations\nn = 300;","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x, y = generate_data(rng, A, B, Q, P);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\npx = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To create a model we use GraphPPL package and @model macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rotate_ssm(n, x0, A, B, Q, P)\n \n # We create constvar references for better efficiency\n cA = constvar(A)\n cB = constvar(B)\n cQ = constvar(Q)\n cP = constvar(P)\n \n # `x` is a sequence of hidden states\n x = randomvar(n)\n # `y` is a sequence of \"clamped\" observations\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n x_prev = x_prior\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)\n y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)\n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference we also specify prior for out first hidden state:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. \n# infer(..., options = (limit_stack_depth = 500, ))`\nresult = infer(\n model = rotate_ssm(length(y), x0, A, B, Q, P), \n data = (y = y,),\n free_energy = true\n);\n\nxmarginals = result.posteriors[:x]\nlogevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\n\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :teal)\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :violet)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"logevidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"1-element Vector{Float64}:\n -1882.2434870099778","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We may be also interested in performance of our resulting Belief Propagation algorithm:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@benchmark infer(\n model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), \n data = (y = $y,)\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"BenchmarkTools.Trial: 140 samples with 1 evaluation.\n Range (min … max): 27.308 ms … 79.422 ms ┊ GC (min … max): 0.00% … 9.37%\n Time (median): 33.728 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 35.935 ms ± 7.598 ms ┊ GC (mean ± σ): 5.40% ± 9.31%\n\n ▄█▂▇▇ \n ▃▃▃▃███████▄▃▃▃▁▃▁▃▅▃▃▄▃▃▃▃▅▁▁▁▁▃▁▁▁▁▁▁▁▁▁▁▃▁▁▁▁▁▁▁▃▁▁▁▁▁▁▃ ▃\n 27.3 ms Histogram: frequency by time 71 ms <\n\n Memory estimate: 9.73 MiB, allocs estimate: 226250.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#System-Identification-Problem","page":"Kalman filtering and smoothing","title":"System Identification Problem","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Distributions, StableRNGs, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)\n\n rng = StableRNG(seed)\n\n real_x = Vector{Float64}(undef, n)\n real_w = Vector{Float64}(undef, n)\n real_y = Vector{Float64}(undef, n)\n\n for i in 1:n\n real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))\n real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))\n real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))\n\n x_i_min = real_x[i]\n w_i_min = real_w[i]\n end\n \n return real_x, real_w, real_y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-1:-y-x-w","page":"Kalman filtering and smoothing","title":"Combination 1: y = x + w","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 250\nreal_x, real_w, real_y = generate_data(+, n);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, real_x, label = \"x\")\npl = plot!(pl, real_w, label = \"w\")\n\npr = plot(title = \"Combined y = x + w\")\npr = scatter!(pr, real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x = randomvar(n)\n w = randomvar(n)\n s = randomvar(n)\n y = datavar(Float64, n)\n \n x_i_min = x0\n w_i_min = w0\n \n for i in 1:n\n x[i] ~ Normal(mean = x_i_min, precision = τ_x)\n w[i] ~ Normal(mean = w_i_min, precision = τ_w)\n s[i] ~ f(x[i], w[i])\n y[i] ~ Normal(mean = s[i], precision = τ_y)\n \n x_i_min = x[i]\n w_i_min = w[i]\n end\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin \n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y\n)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The next step is to assign priors, initialise needed messages and marginals and call the inference function:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"m_x_0, τ_x_0 = -20.0, 1.0\nm_w_0, τ_w_0 = 20.0, 1.0\n\n# We set relatively strong priors for random walk noise components\n# and sort of vague prior for the noise of the observations\na_x, b_x = 0.01, 0.01var(real_x)\na_w, b_w = 0.01, 0.01var(real_w)\na_y, b_y = 1.0, 1.0\n\n# We set relatively strong priors for messages\nxinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))\nwinit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))\n\nimessages = (x = xinit, w = winit)\nimarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))\n\nresult = infer(\n model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),\n data = (y = real_y,), \n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = imessages, \n initmarginals = imarginals, \n iterations = 50\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's examine our inference results:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"τ_x_marginals = result.posteriors[:τ_x]\nτ_w_marginals = result.posteriors[:τ_w]\nτ_y_marginals = result.posteriors[:τ_y]\n\nsmarginals = result.posteriors[:s]\nxmarginals = result.posteriors[:x]\nwmarginals = result.posteriors[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-2:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Combination 2: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Smoothed version of `min` without zero-ed derivatives\nfunction smooth_min(x, y) \n if x < y\n return x + 1e-4 * y\n else\n return y + 1e-4 * x\n end\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"smooth_min (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_meta = @meta begin \n # In this example we are going to use a simple `Linearization` method\n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 200\nmin_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, min_real_x, label = \"x\")\npl = plot!(pl, min_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, min_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_m_x_0, min_τ_x_0 = -1.0, 1.0\nmin_m_w_0, min_τ_w_0 = 1.0, 1.0\n\nmin_a_x, min_b_x = 1.0, 1.0\nmin_a_w, min_b_w = 1.0, 1.0\nmin_a_y, min_b_y = 1.0, 1.0\n\nmin_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))\nmin_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))\n\nmin_result = infer(\n model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),\n data = (y = min_real_y,), \n meta = min_meta,\n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = min_imessages, \n initmarginals = min_imarginals, \n iterations = 100\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_τ_x_marginals = min_result.posteriors[:τ_x]\nmin_τ_w_marginals = min_result.posteriors[:τ_w]\nmin_τ_y_marginals = min_result.posteriors[:τ_y]\n\nmin_smarginals = min_result.posteriors[:s]\nmin_xmarginals = min_result.posteriors[:x]\nmin_wmarginals = min_result.posteriors[:w]\n\npx1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, min_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, min_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, min_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks). ","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Online-(filtering)-identification:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Online (filtering) identification: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rx_identification(f)\n \n # We are going to continuosly update our priors\n # based on new posteriors\n m_x_0 = datavar(Float64) \n τ_x_0 = datavar(Float64)\n m_w_0 = datavar(Float64) \n τ_w_0 = datavar(Float64)\n a_x = datavar(Float64) \n b_x = datavar(Float64)\n a_y = datavar(Float64) \n b_y = datavar(Float64)\n a_w = datavar(Float64) \n b_w = datavar(Float64)\n s = randomvar()\n y = datavar(Float64)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x ~ Normal(mean = x0, precision = τ_x)\n w ~ Normal(mean = w0, precision = τ_w)\n\n s ~ f(x, w)\n y ~ Normal(mean = s, precision = τ_y)\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We impose structured mean-field assumption for this model as well:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_constraints = @constraints begin \n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ\n_y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"autoupdates = @autoupdates begin \n m_x_0, τ_x_0 = mean_precision(q(x))\n m_w_0, τ_w_0 = mean_precision(q(w))\n a_x = shape(q(τ_x)) \n b_x = rate(q(τ_x))\n a_y = shape(q(τ_y))\n b_y = rate(q(τ_y))\n a_w = shape(q(τ_w)) \n b_w = rate(q(τ_w))\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_\nx = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_\ny)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_meta = @meta begin \n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 300\nrx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, rx_real_x, label = \"x\")\npl = plot!(pl, rx_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"engine = infer(\n model = rx_identification(smooth_min),\n constraints = rx_constraints,\n data = (y = rx_real_y,),\n autoupdates = autoupdates,\n meta = rx_meta,\n returnvars = (:x, :w, :τ_x, :τ_w, :τ_y, :s),\n keephistory = 1000,\n historyvars = KeepLast(),\n initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),\n iterations = 10,\n free_energy = true, \n free_energy_diagnostics = nothing,\n autostart = true,\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInferenceEngine:\n Posteriors stream | enabled for (w, s, τ_x, τ_w, τ_y, x)\n Free Energy stream | enabled\n Posteriors history | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)\n Free Energy history | available\n Enabled events | [ ]","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_smarginals = engine.history[:s]\nrx_xmarginals = engine.history[:x]\nrx_wmarginals = engine.history[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, rx_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = \"Estimated X\")\n\npx1 = plot!(px1, rx_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = \"Estimated W\")\n\npx2 = scatter!(px2, rx_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the \"disabled\" state, does not infer anything and simply increases its variance (which is expected for the random walk).","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Handling-Missing-Data","page":"Kalman filtering and smoothing","title":"Handling Missing Data","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let us assume that the following model generates the data","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n x_t sim mathcalNleft(x_t-1 10right) \n y_t sim mathcalNleft(x_t P right) \nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation haty_t in mathrmR we sometimes will catch missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function smoothing(n, x0)\n \n P ~ Gamma(shape = 0.001, scale = 0.001)\n x_prior ~ Normal(mean = mean(x0), var = var(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ Normal(mean = x_prev, precision = 1.0)\n y[i] ~ Normal(mean = x[i], precision = P)\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We need to manually extend the set of rules to support ::Missing values","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"P = 1.0\nn = 250\n\nreal_signal = map(e -> sin(0.05 * e), collect(1:n))\nnoisy_data = real_signal + rand(Normal(0.0, sqrt(P)), n);\nmissing_indices = 100:125\nmissing_data = similar(noisy_data, Union{Float64, Missing}, )\n\ncopyto!(missing_data, noisy_data)\n\nfor index in missing_indices\n missing_data[index] = missing\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0_prior = NormalMeanVariance(0.0, 1000.0)\n\nresult = infer(\n model = smoothing(n, x0_prior), \n data = (y = missing_data,), \n constraints = constraints,\n initmarginals = (P = Gamma(0.001, 0.001), ),\n returnvars = (x = KeepLast(),),\n iterations = 20\n);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"plot(real_signal, label = \"Noisy signal\", legend = :bottomright)\nscatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = \"Missing region\")\nplot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = \"Estimated hidden state\")","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#examples-conjugate-computational-variational-message-passing-(cvi)","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#An-example:-nonlinear-dynamical-system","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"An example: nonlinear dynamical system","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position z_t at time t. Instead they have access to the observed squared distance y_t between the object and some reference point s. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# data generating process\nnr_observations = 50\nreference_point = 53\nhidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)\nmeasurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot hidden location and reference frame\np1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label=\"hidden location\")\nhline!([reference_point], linewidth=3, label=\"reference point\")\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot measurements\np2 = scatter(1:nr_observations, measurements, linewidth=3, label=\"measurements\")\nxlabel!(\"time [sec]\"), ylabel!(\"squared distance [cm2]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"beginaligned\n p(tau) = Gamma(tau mid alpha_tau beta_tau)\n p(gamma) = Gamma(gamma mid alpha_gamma beta_gamma)\n p(z_t mid z_t - 1 tau) = mathcalN(z_t mid z_t - 1 + 1 tau^-1)\n p(y_t mid z_t gamma) = mathcalN(y_t mid (z_t - s)^2 gamma^-1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"where the researchers put priors on the process and measurement noise parameters, tau and gamma, respectively. They do this, because they do not know the accuracy of their devices.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"function compute_squared_distance(z)\n (z - reference_point)^2\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function measurement_model(nr_observations)\n\n # allocate random variables and observations\n z = randomvar(nr_observations)\n y = datavar(Float64, nr_observations)\n\n # set priors on precision parameters\n τ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n γ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n \n # specify estimate of initial location\n z[1] ~ Normal(mean = 0, precision = τ)\n y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)\n\n # loop over observations\n for t in 2:nr_observations\n\n # specify state transition model\n z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)\n\n # specify non-linear observation model\n y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)\n \n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)\n compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function model_meta(...)\n f() -> CVI(args...)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"See ?CVI for more information about the args....","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In the above example, we will assume the following posterior factorization:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function measurement_constraints()\n q(z, τ, γ) = q(z)q(τ)q(γ)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function posterior_constraints() begin\n q(z, γ) = q(z)q(γ) # CVI\n q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"results = infer(\n model = measurement_model(nr_observations),\n data = (y = measurements,),\n iterations = 5,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = measurement_constraints(),\n meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),\n initmessages = (z = NormalMeanVariance(0, 5),),\n initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),\n)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Inference results:\n Posteriors | available for (z)\n Free Energy: | Real[1241.91, 429.933, 376.869, 365.774, 362.879]","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot estimates for location\np1 = plot(collect(1:nr_observations), hidden_location, label = \"hidden location\", legend=:topleft, linewidth=3, color = :red)\nplot!(map(mean, results.posteriors[:z]), label = \"estimated location (±2σ)\", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot Bethe free energy\np2 = plot(results.free_energy, linewidth=3, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size = (1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Requirements","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Requirements","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"There are several main requirements for the CVI procedure to satisfy:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The out interface of the non-linearity must be independently factorized with respect to other variables in the model.\nThe messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function model(...)\n ...\n y ~ f(x1, x2, ..., xN)\n ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity\n ... \nend\n\n@constraints function constraints_meta() begin\n q(y, z1, ..., zn) = q(y)q(z1,...,zM)\n ...\nend;\n\n@meta function model_meta(...)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer))\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note that not all exponential family distributions are implemented.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Extensions","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Extensions","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Using-a-custom-optimizer","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Using a custom optimizer","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"CVI only supports Optimisers optimizers out of the box.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Below an explanation on how to extend to it to a custom optimizer.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Suppose we have CustomDescent structure which we want to use inside CVI for optimization.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"ReactiveMP.cvi_update! incapsulates the gradient step:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"opt is used to select your optimizer structure\nλ is the current value\n∇ is a gradient value computed inside CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"struct CustomDescent \n learning_rate::Float64\nend\n\n# Must return an optimizer and its initial state\nfunction ReactiveMP.cvi_setup(opt::CustomDescent, q)\n return (opt, nothing)\nend\n\n# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)\nfunction ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)\n opt, _ = opt_and_state\n λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))\n copyto!(new_λ, λ̂)\n return opt_and_state, new_λ\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's try to apply it to a model: beginaligned p(x) = mathcalN(0 1)\n p(y_imid x) = mathcalN(y_i mid x^2 1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's generate some synthetic data for the model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# generate data\ny = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)\nhistogram(y)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Again we can create the corresponding model as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# specify non-linearity\nf(x) = x ^ 2\n\n# specify model\n@model function normal_square_model(nr_observations)\n\n # allocate observations\n y = datavar(Float64, nr_observations)\n\n # describe prior on latent state\n x ~ NormalMeanPrecision(0, 100)\n\n # transform latent state\n mean ~ f(x)\n\n # observation model\n y .~ NormalMeanVariance(mean, 1)\n\nend\n\n# specify meta\n@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"normal_square_meta (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"res = infer(\n model = normal_square_model(1000),\n data = (y = y,),\n iterations = 10,\n free_energy = true,\n initmessages = (x = NormalMeanVariance(0, 100),),\n meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))\n)\n\nmean(res.posteriors[:x][end])","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"-18.998075156688632","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working! ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note: x^2 can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"page"},{"location":"library/functional-forms/#lib-forms","page":"Built-in functional form constraints","title":"Built-in Functional Forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.","category":"page"},{"location":"library/functional-forms/#lib-forms-custom-constraints","page":"Built-in functional form constraints","title":"Custom functional forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.","category":"page"},{"location":"library/functional-forms/#lib-forms-unspecified-constraint","page":"Built-in functional form constraints","title":"UnspecifiedFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: Nothing # This is the default setting\nend","category":"page"},{"location":"library/functional-forms/#lib-forms-point-mass-constraint","page":"Built-in functional form constraints","title":"PointMassFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. ","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.PointMassFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.PointMassFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.PointMassFormConstraint","text":"PointMassFormConstraint\n\nOne of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.\n\nKeyword arguments\n\noptimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer\nstarting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point\nboundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries\n\nCustom optimizer callback interface\n\n# This is an example of the `custom_optimizer` interface\nfunction custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # should return argmin of the -logpdf(distribution)\nend\n\nCustom starting point callback interface\n\n# This is an example of the `custom_starting_point` interface\nfunction custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # built-in optimizer expects an array, even for a univariate distribution\n return [ 0.0 ] \nend\n\nCustom boundaries callback interface\n\n# This is an example of the `custom_boundaries` interface\nfunction custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # returns a tuple of `lower` and `upper` boundaries\n return (-Inf, Inf)\nend\n\nTraits\n\nis_point_mass_form_constraint = true\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = PointMass (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-sample-list-constraint","page":"Built-in functional form constraints","title":"SampleListFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000)\n # or \n q(y) :: SampleList(1000, LeftProposal())\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.SampleListFormConstraint\nRxInfer.AutoProposal\nRxInfer.LeftProposal\nRxInfer.RightProposal","category":"page"},{"location":"library/functional-forms/#RxInfer.SampleListFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.SampleListFormConstraint","text":"SampleListFormConstraint(rng, strategy, method)\n\nOne of the form constraint objects. Approximates DistProduct with a SampleList object. \n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = SampleList (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.AutoProposal","page":"Built-in functional form constraints","title":"RxInfer.AutoProposal","text":"Tries to determine the proposal distribution in the SampleList approximation automatically.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.LeftProposal","page":"Built-in functional form constraints","title":"RxInfer.LeftProposal","text":"Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.RightProposal","page":"Built-in functional form constraints","title":"RxInfer.RightProposal","text":"Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-fixed-marginal-constraint","page":"Built-in functional form constraints","title":"FixedMarginalFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints function block_updates(x_posterior = nothing) \n # `nothing` returns the computed posterior marginal\n q(x) :: Marginal(x_posterior)\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.FixedMarginalFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.FixedMarginalFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.FixedMarginalFormConstraint","text":"FixedMarginalFormConstraint\n\nOne of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.\n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = Marginal (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-composite-constraint","page":"Built-in functional form constraints","title":"CompositeFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass()\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/#examples-hierarchical-gaussian-filter","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"","category":"section"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Simple HGF model can be defined as:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n x^(j)_k sim mathcalN(x^(j)_k - 1 f_k(x^(j - 1)_k)) \n y_k sim mathcalN(x^(j)_k tau_k)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"where j is an index of layer in hierarchy, k is a time step and f_k is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with f_k = exp(kappa x + omega) variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n z_k sim mathcalN(z_k - 1 mathcaltau_z) \n x_k sim mathcalN(x_k - 1 exp(kappa z_k + omega)) \n y_k sim mathcalN(x_k mathcaltau_y)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"For simplicity we will consider tau_z, tau_y, kappa and omega known and fixed, but there are no principled limitations to make them random variables too.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"using RxInfer, BenchmarkTools, Random, Plots","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function generate_data(rng, k, w, zv, yv)\n z_prev = 0.0\n x_prev = 0.0\n\n z = Vector{Float64}(undef, n)\n v = Vector{Float64}(undef, n)\n x = Vector{Float64}(undef, n)\n y = Vector{Float64}(undef, n)\n\n for i in 1:n\n z[i] = rand(rng, Normal(z_prev, sqrt(zv)))\n v[i] = exp(k * z[i] + w)\n x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))\n y[i] = rand(rng, Normal(x[i], sqrt(yv)))\n\n z_prev = z[i]\n x_prev = x[i]\n end \n \n return z, x, y\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Seed for reproducibility\nseed = 42\n\nrng = MersenneTwister(seed)\n\n# Parameters of HGF process\nreal_k = 1.0\nreal_w = 0.0\nz_variance = abs2(0.2)\ny_variance = abs2(0.1)\n\n# Number of observations\nn = 300\n\nz, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n scatter!(px, 1:n, y, label = \"y_i\", color = :red, ms = 2, alpha = 0.2)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To create a model we use the @model macro:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# We create a single-time step of corresponding state-space process to\n# perform online learning (filtering)\n@model function hgf(real_k, real_w, z_variance, y_variance)\n \n # Priors from previous time step for `z`\n zt_min_mean = datavar(Float64)\n zt_min_var = datavar(Float64)\n \n # Priors from previous time step for `x`\n xt_min_mean = datavar(Float64)\n xt_min_var = datavar(Float64)\n\n zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)\n xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)\n\n # Higher layer is modelled as a random walk \n zt ~ NormalMeanVariance(zt_min, z_variance)\n \n # Lower layer is modelled with `GCV` node\n gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)\n \n # Noisy observations \n y = datavar(Float64)\n y ~ NormalMeanVariance(xt, y_variance)\n \n return gcvnode\nend\n\n@constraints function hgfconstraints() \n q(xt, zt, xt_min) = q(xt, xt_min)q(zt)\nend\n\n@meta function hgfmeta()\n # Lets use 31 approximation points in the Gauss Hermite cubature approximation method\n GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) \nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"hgfmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function run_inference(data, real_k, real_w, z_variance, y_variance)\n\n autoupdates = @autoupdates begin\n zt_min_mean, zt_min_var = mean_var(q(zt))\n xt_min_mean, xt_min_var = mean_var(q(xt))\n end\n\n return infer(\n model = hgf(real_k, real_w, z_variance, y_variance),\n constraints = hgfconstraints(),\n meta = hgfmeta(),\n data = (y = data, ),\n autoupdates = autoupdates,\n keephistory = length(data),\n historyvars = (\n xt = KeepLast(),\n zt = KeepLast()\n ),\n initmarginals = (\n zt = NormalMeanVariance(0.0, 5.0),\n xt = NormalMeanVariance(0.0, 5.0),\n ), \n iterations = 5,\n free_energy = true,\n autostart = true,\n callbacks = (\n after_model_creation = (model, returnval) -> begin \n gcvnode = returnval\n setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))\n end,\n )\n )\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"run_inference (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"result = run_inference(y, real_k, real_w, z_variance, y_variance);\n\nmz = result.history[:zt];\nmx = result.history[:xt];","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = \"estimated z_i\", color = :teal)\n \n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = \"estimated x_i\", color = :violet)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"plot(result.free_energy_history, label = \"Bethe Free Energy\")","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see BetheFreeEnergy converges nicely to a stable point.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"At final, lets check the overall performance of our resulting Variational Message Passing algorithm:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"BenchmarkTools.Trial: 40 samples with 1 evaluation.\n Range (min … max): 106.663 ms … 184.785 ms ┊ GC (min … max): 0.00% … 0.0\n0%\n Time (median): 125.543 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 127.181 ms ± 14.793 ms ┊ GC (mean ± σ): 1.51% ± 2.7\n2%\n\n ▂ ▂ ▅█ ▅ ▂ \n ▅█▁▁█▅▅█▁▁▁▁▅████▅█▁▁▁▅█▅▁▁▅▁▁▅▁▁▁▅▁▁▁▁▁▅▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▅ ▁\n 107 ms Histogram: frequency by time 185 ms <\n\n Memory estimate: 18.82 MiB, allocs estimate: 458387.","category":"page"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = RxInfer","category":"page"},{"location":"#RxInfer","page":"Home","title":"RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"Julia package for automatic Bayesian inference on a factor graph with reactive message passing.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.","category":"page"},{"location":"#Package-Features","page":"Home","title":"Package Features","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"User friendly syntax for specification of probabilistic models.\nAutomatic generation of message passing algorithms including\nBelief propagation\nVariational message passing\nExpectation maximization\nSupport for hybrid models combining discrete and continuous latent variables.\nSupport for hybrid distinct message passing inference algorithm under a unified paradigm.\nFactorisation and functional form constraints specification.\nEvaluation of Bethe free energy as a model performance measure.\nSchedule-free reactive message passing API.\nHigh performance.\nScalability for large models with millions of parameters and observations.\nInference procedure is differentiable.\nEasy to extend with custom nodes and message update rules.","category":"page"},{"location":"#Why-RxInfer","page":"Home","title":"Why RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a \"variational Free Energy\" cost function. For large models, manual derivation of these gradients might not be feasible, while automated \"black-box\" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.","category":"page"},{"location":"","page":"Home","title":"Home","text":"RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different \"what-if\" scenarios and enables very efficient inference in specific cases.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.","category":"page"},{"location":"#How-to-get-started?","page":"Home","title":"How to get started?","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"manuals/background.md\",\n \"manuals/comparison.md\",\n \"manuals/getting-started.md\",\n \"manuals/model-specification.md\",\n \"manuals/constraints-specification.md\",\n \"manuals/meta-specification.md\",\n \"manuals/inference-execution.md\",\n \"manuals/custom-node.md\",\n \"manuals/debugging.md\",\n \"manuals/delta-node.md\",\n \"examples/overview.md\",\n \"library/exported-methods.md\",\n \"library/functional-forms.md\",\n \"contributing/overview.md\",\n \"contributing/new-example.md\"\n]\nDepth = 2","category":"page"},{"location":"#References","page":"Home","title":"References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RxInfer: A Julia package for reactive real-time Bayesian inference - a reference paper for the RxInfer.jl framwork.\nVariational Message Passing and Local Constraint Manipulation in Factor Graphs - describes theoretical aspects of the underlying Bayesian inference method.\nReactive Message Passing for Scalable Bayesian Inference - describes implementation aspects of the Bayesian inference engine and performs benchmarks and accuracy comparison on various models.\nA Julia package for reactive variational Bayesian inference - a reference paper for the ReactiveMP.jl package, the underlying inference engine.\nThe Factor Graph Approach to Model-Based Signal Processing - an introduction to message passing and FFGs.","category":"page"},{"location":"#Ecosystem","page":"Home","title":"Ecosystem","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ReactiveMP.jl - core package for efficient and scalable for reactive message passing \nGraphPPL.jl - package for model and constraints specification\nRocket.jl - reactive programming tools","category":"page"},{"location":"#Index","page":"Home","title":"Index","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"manuals/inference/infer/#user-guide-inference","page":"Static vs Streamline inference","title":"Automatic Inference Specification","text":"","category":"section"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors. ","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"For details on manual inference specification, see the Manual Inference section.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"infer\nInferenceResult\nRxInfer.start\nRxInfer.stop\n@autoupdates\nRxInferenceEngine\nRxInferenceEvent","category":"page"},{"location":"manuals/inference/infer/#RxInfer.infer","page":"Static vs Streamline inference","title":"RxInfer.infer","text":"infer(\n model; \n data = nothing,\n datastream = nothing,\n autoupdates = nothing,\n initmarginals = nothing,\n initmessages = nothing,\n constraints = nothing,\n meta = nothing,\n options = nothing,\n returnvars = nothing, \n predictvars = nothing, \n historyvars = nothing,\n keephistory = nothing,\n iterations = nothing,\n free_energy = false,\n free_energy_diagnostics = BetheFreeEnergyDefaultChecks,\n showprogress = false,\n callbacks = nothing,\n addons = nothing,\n postprocess = DefaultPostprocess(),\n warn = true,\n events = nothing,\n uselock = false,\n autostart = true,\n catch_exception = false\n)\n\nThis function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.\n\nArguments\n\nFor more information about some of the arguments, please check below. \n\nmodel: specifies a model generator, required\ndata: NamedTuple or Dict with data, required (or datastream or predictvars)\ndatastream: A stream of NamedTuple with data, required (or data)\nautoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates\ninitmarginals = nothing: NamedTuple or Dict with initial marginals, optional\ninitmessages = nothing: NamedTuple or Dict with initial messages, optional\nconstraints = nothing: constraints specification object, optional, see @constraints\nmeta = nothing: meta specification object, optional, may be required for some models, see @meta\noptions = nothing: model creation options, optional, see ModelInferenceOptions\nreturnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information\npredictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)\nhistoryvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)\nkeephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)\niterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information\nfree_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl\nfree_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.\nshowprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)\ncatch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)\ncallbacks = nothing: inference cycle callbacks, optional, see below for more info\naddons = nothing: inject and send extra computation information along messages, see below for more info\npostprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info\nevents = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)\nuselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)\nautostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)\nwarn = true: enables/disables warnings\n\nNote on NamedTuples\n\nWhen passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.\n\nThe model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:\n\n@model function coin_toss(some_argument, some_keyword_argument = 3)\n ...\nend\n\nresult = infer(\n model = coin_toss(some_argument; some_keyword_argument = 3)\n)\n\nNote: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.\n\ndata\n\nEither data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.\n\nNote: The behavior of the data keyword argument depends on the inference setting (batch or streamline).\n\nThe data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.\n\nstreamline setting\n\nAll entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.\n\ndatastream\n\nThe datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.\n\nNote: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.\n\nFor specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as\n\ninfer(...\n initmarginals = (\n # initialize the marginal distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.\n\n- ### `initmessages`\n\nFor specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as\n\njulia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )\n\noptions\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\nreturnvars\n\nreturnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.\n\nBatch inference:\n\nAccepts a NamedTuple or Dict of return variable specifications.\nTwo specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).\nWhen iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).\nUse iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.\n\nExample:\n\nresult = infer(\n ...,\n returnvars = (\n x = KeepLast(),\n τ = KeepEach()\n )\n)\n\nShortcut for setting the same option for all variables:\n\nresult = infer(\n ...,\n returnvars = KeepLast() # or KeepEach()\n)\n\nStreamline inference:\n\nFor each symbol in returnvars, infer creates an observable stream of posterior updates.\nAgents can subscribe to these updates using the Rocket.jl package.\n\nExample:\n\nengine = infer(\n ...,\n autoupdates = my_autoupdates,\n returnvars = (:x, :τ),\n autostart = false\n)\n\npredictvars\n\npredictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.\n\nSimilar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n predictvars = (\n o = KeepLast(),\n τ = KeepEach()\n )\n)\n\nNote: The predictvars argument is exclusive for batch setting.\n\nhistoryvars\n\nhistoryvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.\n\nhistoryvars accepts a NamedTuple or Dict or return var specification. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = (\n x = KeepLast(),\n τ = KeepEach()\n ),\n keephistory = 10\n)\n\nIt is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.\n\nExample:\n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = KeepLast(),\n keephistory = 10\n)\n\nkeep_history\n\nSpecifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.\n\niterations\n\nSpecifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration. \n\nfree_energy\n\nStreamline inference:\n\nSpecifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.\n\nWhen free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.\nengine.free_energy_history: Averaged BFE history over VMP iterations.\nengine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.\nengine.free_energy_raw_history: Raw BFE history.\n\nBatch inference:\n\nSpecifies if the infer function should return Bethe Free Energy (BFE) values.\n\nOptionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.\nfree_energy_diagnostics\n\nThis settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.\n\ncatch_exception\n\nThe catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.\n\ncallbacks\n\nThe inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.\n\nresult = infer(\n ...,\n callbacks = (\n on_marginal_update = (model, name, update) -> println(\"$(name) has been updated: $(update)\"),\n after_inference = (args...) -> println(\"Inference has been completed\")\n )\n)\n\nThe callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:\n\non_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)\nbefore_model_creation: args: ()\nafter_model_creation: args: (model::FactorGraphModel, returnval)\nbefore_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nbefore_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nafter_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\nafter_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\n\nbefore_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.\n\naddons\n\nThe addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.\n\npostprocess\n\nThe postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.InferenceResult","page":"Static vs Streamline inference","title":"RxInfer.InferenceResult","text":"InferenceResult\n\nThis structure is used as a return value from the infer function. \n\nPublic Fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.\nfree_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\nerror: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.start","page":"Static vs Streamline inference","title":"RxInfer.start","text":"start(engine::RxInferenceEngine)\n\nStarts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.stop\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.stop","page":"Static vs Streamline inference","title":"RxInfer.stop","text":"stop(engine::RxInferenceEngine)\n\nStops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.start\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.@autoupdates","page":"Static vs Streamline inference","title":"RxInfer.@autoupdates","text":"@autoupdates\n\nCreates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification. \n\nEach line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.\n\nFor example:\n\n@autoupdates begin \n x = f(q(z))\nend\n\nThis structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically. \n\nAs an example consider the following model and auto-update specification:\n\n@model function kalman_filter()\n x_current_mean = datavar(Float64)\n x_current_var = datavar(Float64)\n\n x_current ~ Normal(mean = x_current_mean, var = x_current_var)\n\n x_next ~ Normal(mean = x_current, var = 1.0)\n\n y = datavar(Float64)\n y ~ Normal(mean = x_next, var = 1.0)\nend\n\nThis model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:\n\nautoupdates = @autoupdates begin\n x_current_mean, x_current_var = mean_cov(q(x_next))\nend\n\nThis structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.\n\nSee also: infer\n\n\n\n\n\n","category":"macro"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEngine","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEngine","text":"RxInferenceEngine\n\nThe return value of the rxinference function. \n\nPublic fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.\nfree_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.\nhistory: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.\nfree_energy_history: (optional) Free energy history, average over variational iterations \nfree_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)\nfree_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)\nevents: (optional) A stream of events send by the inference engine. See the events argument for the infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\n\nUse the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.\n\nSee also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEvent","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEvent","text":"RxInferenceEvent{T, D}\n\nThe RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.\n\nThe events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:\n\nusing Rocket\n\nstruct MyEventListener <: Rocket.Actor{RxInferenceEvent}\n # ... extra fields\nend\n\nfunction Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })\n model, iteration = event\n println(\"Iteration $(iteration) has been finished.\")\nend\n\nfunction Rocket.on_error!(listener::MyEventListener, err)\n # ...\nend\n\nfunction Rocket.on_complete!(listener::MyEventListener)\n # ...\nend\n\n\nand later on:\n\nengine = infer(events = Val((:after_iteration, )), ...)\n\nsubscription = subscribe!(engine.events, MyEventListener(...))\n\nSee also: infer, RxInferenceEngine\n\n\n\n\n\n","category":"type"},{"location":"examples/advanced_examples/overview/#examples-advanced_examples-overview","page":"Overview","title":"Advanced examples","text":"","category":"section"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Advanced examples contain more complex inference problems.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.\nAdvanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.\nAssessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.\nChance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.\nConjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.\nGlobal Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.\nSolve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.\nInfinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.\nNonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors","category":"page"},{"location":"manuals/constraints-specification/#user-guide-constraints-specification","page":"Constraints specification","title":"Constraints Specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"using RxInfer","category":"page"},{"location":"manuals/constraints-specification/#General-syntax","page":"Constraints specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"\n# `functional` style\n@constraints function create_my_constraints(arg1, arg2)\n ...\nend\n\n# `block` style\nmyconstraints = @constraints begin \n ...\nend\n","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In the first case it returns a function that return constraints upon calling, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(mean_field)\n q(x) :: PointMass\n\n if mean_field\n q(x, y) = q(x)q(y)\n end\nend\n\nmyconstraints = make_constraints(true)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"and in the second case it evaluates automatically and returns constraints object directly.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints begin \n q(x) :: PointMass\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/#Options-specification","page":"Constraints specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints [ warn = false ] begin \n ...\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"List of available options:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/constraints specification","category":"page"},{"location":"manuals/constraints-specification/#Marginal-and-messages-form-constraints","page":"Constraints specification","title":"Marginal and messages form constraints","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"The following constraint:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"mathrmapproximate q(x) = fracoverrightarrowmu(x)overleftarrowmu(x)int overrightarrowmu(x)overleftarrowmu(x) mathrmdxmathrmasPointMass","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\n μ(x) :: SampleList(1000)\n # it is possible to assign different form constraints on the same variable \n # both for the marginal and for the messages \nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro understands \"stacked\" form constraints. For example the following form constraint","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\nNot all combinations of \"stacked\" form constraints are compatible between each other.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.","category":"page"},{"location":"manuals/constraints-specification/#Factorisation-constraints-on-posterior-distribution-q()","page":"Constraints specification","title":"Factorisation constraints on posterior distribution q()","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"For example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) = q(x[begin])..q(x[end])\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables x_i.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\n@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"It is possible to write more complex factorisation constraints, for example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(k)\n q(x) = q(x[begin:k])q(x[k+1:end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end]. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model function my_model(arguments...)\n ...\nend\n\nconstraints = @constraints begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); constraints = constraints)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument. ","category":"page"},{"location":"contributing/overview/#contributing-overview","page":"Overview","title":"Contributing","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.","category":"page"},{"location":"contributing/overview/#Reporting-bugs","page":"Overview","title":"Reporting bugs","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.","category":"page"},{"location":"contributing/overview/#Nightly-Julia-status","page":"Overview","title":"Nightly Julia status","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"(Image: PkgEval)","category":"page"},{"location":"contributing/overview/#Suggesting-features","page":"Overview","title":"Suggesting features","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome new feature proposals. However, before submitting a feature request, consider a few things:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.\nIf you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.","category":"page"},{"location":"contributing/overview/#Contributing-code","page":"Overview","title":"Contributing code","text":"","category":"section"},{"location":"contributing/overview/#Installing-RxInfer","page":"Overview","title":"Installing RxInfer","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] dev git@github.com:your_username/RxInfer.jl.git","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nIt is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.","category":"page"},{"location":"contributing/overview/#Core-dependencies","page":"Overview","title":"Core dependencies","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.","category":"page"},{"location":"contributing/overview/#Committing-code","page":"Overview","title":"Committing code","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well. ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.","category":"page"},{"location":"contributing/overview/#Style-conventions","page":"Overview","title":"Style conventions","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Use 4 spaces for indentation\nType names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..\nFunction names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..\nVariable names and function arguments use snake_case\nThe name of a method that modifies its argument(s) must end in !","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nRxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.","category":"page"},{"location":"contributing/overview/#Unit-tests","page":"Overview","title":"Unit tests","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The tests can be evaluated by running following command in the Julia REPL:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] test RxInfer","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"In addition tests can be evaluated by running following command in the RxInfer root directory:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make test","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make devtest to use local dev-ed versions of the core packages.","category":"page"},{"location":"contributing/overview/#Makefile","page":"Overview","title":"Makefile","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl uses Makefile for most common operations:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make help: Shows help snippet\nmake test: Run tests, supports extra arguments\nmake test test_args=\"distributions:normal_mean_variance\" would run tests only from distributions/test_normal_mean_variance.jl\nmake test test_args=\"distributions:normal_mean_variance models:lgssm\" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl\nmake test dev=true would run tests while using dev-ed versions of core packages\nmake devtest: Alias for the make test dev=true ...\nmake docs: Compile documentation\nmake devdocs: Same as make docs, but uses dev-ed versions of core packages\nmake examples: Run all examples and put them in the docs/ folder if successfull \nmake devexamples: Same as make examples, but uses dev-ed versions of core packages\nmake lint: Check codestyle\nmake format: Check and fix codestyle ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nCore packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.","category":"page"},{"location":"contributing/new-release/#contributing-new-release","page":"Publishing a new release","title":"Publishing a new release","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.","category":"page"},{"location":"contributing/new-release/#Start-the-release-process","page":"Publishing a new release","title":"Start the release process","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"In order to start the release process a person with the associated permissions should: ","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Open a commit page on GitHub\nWrite the @JuliaRegistrator register comment for the commit:","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"(Image: Release comment)","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#examples-solve-gp-regression-by-sde","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"In this notebook, we solve a GP regression problem by using \"Stochastic Differential Equation\" (SDE). This method is well described in the dissertation \"Stochastic differential equation methods for spatio-temporal Gaussian process regression.\" by Arno Solin and \"Sequential Inference for Latent Temporal Gaussian Process Models\" by Jouni Hartikainen. The idea of the method is as follows.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Suppose a function f(x) follows a zero-mean Gaussian Process beginaligned f(x) sim mathcalGP(0 k(xx)) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"When the dimensionality of x is 1, we can consider f(x) as a stochastic process over time, i.e. f(t). For a certain classses of covariance functions, f(t) is a solution to an m-th order linear stochastic differential equation (SDE) beginaligned a_0 f(t) + a_1 fracd f(t)dt + dots + a_m fracd^m f(t)dt^m = w(t) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where w(t) is a zero-mean white noise process with spectral density Q_c. If we define a vector-valued function mathbff(t) = (f(t) ddt f(t)dots d^m-1dt^m-1f(t)), then we can rewrite the above SDE under the companion form","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracd mathbff(t)dt = mathbfF mathbff(t) + mathbfL w(t) quad (1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfF and mathbfL are defined based on the choice of covariance functions. From (1), we have the following state-space model: beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) quad(2a) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) quad(2b) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfA_k = exp(mathbfFDelta t_k), with Delta t_k = t_k+1 - t_k, is called the discrete-time state transition matrix, and mathbfQ_k the process noise covariance matrix. For the computation of mathbfQ_k, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state f_0 sim mathcalN(mathbf0 mathbfP_0). For stationary covariance function, the SDE has a stationary state f_infty sim mathcalN(mathbf0 mathbfP_infty), where mathbfP_infty is the solution to beginaligned fracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0 quad (mathrmLyapunov equation) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"With this stationary condition, the process noise covariance mathbfQ_k is computed as follows beginaligned mathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"For one-dimensional problem the SDE representation of the GP is defined by the matrices mathbfF mathbfL mathbfQ_c mathbfP_0 and mathbfH. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"using RxInfer, Random, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Create-state-space-model-for-GP-regression","page":"Solve GP regression by SDE","title":"Create state space model for GP regression","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Here we create a state-space model beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) \nendaligned where y_k is the noisy observation of the function f at time t_k, and sigma^2_noise is the noise variance and assumed to be known.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"@model function gp_regression(n, P∞, A, Q, H, σ²_noise)\n f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)\n f = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n \n f_prev = f_0\n\n for i=1:n\n f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])\n y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)\n f_prev = f[i]\n end\n return f, y\nend","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Generate-data","page":"Solve GP regression by SDE","title":"Generate data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Random.seed!(10)\nn = 100\nσ²_noise = 0.04;\nt = collect(range(-2, 2, length=n)); #timeline\nf_true = sinc.(t); # true process\nf_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process\n\npos = sort(randperm(75)[1:2:75]); \nt_obser = t[pos]; # time where we observe data\n\ny_data = Array{Union{Float64,Missing}}(missing, n)\nfor i in pos \n y_data[i] = f_noisy[i]\nend\n\nθ = [1., 1.]; # store [l, σ²]\nΔt = [t[1]]; # time difference\nappend!(Δt, t[2:end] - t[1:end-1]);","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Let's-visualize-our-data","page":"Solve GP regression by SDE","title":"Let's visualize our data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"plot(t, f_true, label=\"True process f(t)\")\nscatter!(t_obser, y_data[pos], label = \"Noisy observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-3/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-3/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"The Matern is a stationary covariance function and defined as follows beginaligned k(tau) = sigma^2 frac2^1-nuGamma(nu) left(fracsqrt2nutaul right)^nu K_nuleft(fracsqrt2nutaul right) endaligned where beginaligned sigma^2 textthe magnitude scale hyperparameter\nl textthe characteristic length-scale\nnu textthe smoothness hyperparameter\nK_nu() textthe modified Bessel function of the second kind endaligned When we say the Matern-3/2, we mean nu=32. The matrices for the state space model are computed as follows beginaligned mathbfF = beginpmatrix 0 1\n-lambda^2 -2lambda endpmatrix quad quad mathbfL = beginpmatrix 0 1 endpmatrix quad quad mathbfP_infty = beginpmatrix sigma^2 0 0 lambda^2sigma^2 endpmatrix quad quad mathbfH = beginpmatrix 1 0 endpmatrix quad quad Q_c = 4lambda^3sigma^2 endaligned where lambda = fracsqrt3l From these matrices we can define mathbfA_k and mathbfQ_k.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(3)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 1.];\nH = [1., 0.];\nF = [0. 1.; -λ^2 -2λ]\nP∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_32 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-5/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-5/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfF = beginpmatrix\n0 1 0\n0 0 1 \n-lambda^3 -3lambda^2 -3lambda\nendpmatrix quad quad mathbfL = beginpmatrix\n0 0 1\nendpmatrix quad quad mathbfH = beginpmatrix\n1 0 0\nendpmatrix quad quad Q_c = frac163 sigma^2 lambda^5 \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where lambda = sqrt5 l. To find mathbfP_infty, we solve the Lyapunov equation","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"of which the solution is","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nvec(mathbfP_infty) = (mathbfI otimes mathbfF + mathbfFotimesmathbfI)^-1 vec(-mathbfLQ_cmathbfL^T)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where vec() is the vectorization operator and otimes denotes the Kronecker product. Now we can find mathbfA_k and mathbfQ_k ","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfA_k = exp(mathbfFDelta t_k) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(5)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 0., 1.];\nH = [1., 0., 0.];\nF = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]\nQc = 16/3 * θ[2] * λ^5;\n\nI = diageye(3) ; \nvec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); \nP∞ = reshape(vec_P,3,3);\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_52 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Result","page":"Solve GP regression by SDE","title":"Result","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"slicedim(dim) = (a) -> map(e -> e[dim], a)\n\nplot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M32\", title = \"Matern-3/2\", legend =false, lw = 2)\nplot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M52\",legend = :bottomleft, title = \"GPRegression by SSM\", lw = 2)\nplot!(t, f_true,label=\"true process\", lw = 2)\nscatter!(t_obser, f_noisy[pos], label=\"Observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"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. ","category":"page"},{"location":"contributing/new-documentation/#guide-docs-contributing","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.\nIdentify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.\nFork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.\nMake Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.\nSubmit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.\nReview and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.\nMerging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.","category":"page"},{"location":"contributing/new-documentation/#Use-[LiveServer.jl](https://github.com/tlienart/LiveServer.jl)","page":"Contributing to the documentation","title":"Use LiveServer.jl","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"To use LiveServer.jl, simply follow these steps[1]","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"[1]: Make sure to install the LiveServer and Documenter in your current working environment.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Make sure to import the required packages ","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> using LiveServer, Documenter","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"After importing the required packages, you can start the live server with the following command:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> servedocs()","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#examples-bayesian-linear-regression-tutorial","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The first part uses a regular Bayesian Linear Regression on a simple application of fuel consumption for a car with synthetic data.\nThe second part is an adaptation of a tutorial from NumPyro and uses Hierarchical Bayesian linear regression on the OSIC pulmonary fibrosis progression dataset from Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-1.-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 1. Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-known-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He records the speed and fuel consumption for the urban road which is the xdata and ydata.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b)\n Free Energy: | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184\n.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821\n, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a\\mid y)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0,Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b)\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b\\mid y)\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"a = results.posteriors[:a]\nb = results.posteriors[:b]\n\nprintln(\"Real a: \", 0.5, \" | Estimated a: \", mean_var(a), \" | Error: \", abs(mean(a) - 0.5))\nprintln(\"Real b: \", 25.0, \" | Estimated b: \", mean_var(b), \" | Error: \", abs(mean(b) - 25.0))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err\nor: 0.001490188462705988\nReal b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error\n: 0.18735789804394898","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-unknown-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with unknown noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. beginaligned p(y_n mid a b s) = mathcalN(y_n mid ax_n + b s)\np(s) = mathcalIG(smidalpha theta)\np(a) = mathcalN(a mid m_a v_a) \np(b) = mathcalN(b mid m_b v_b) endaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_unknown_noise(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n s ~ InverseGamma(1.0, 1.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = s)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)\n\nscatter(x_data_un, y_data_un, title = \"Dateset with unknown noise (mountain road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_unknown_noise = infer(\n model = linear_regression_unknown_noise(length(x_data_un)), \n data = (y = y_data_un, x = x_data_un), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast(), s = KeepLast()), \n iterations = 20,\n constraints = MeanField(),\n initmarginals = (s = vague(InverseGamma), ),\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, s)\n Free Energy: | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125\n.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56\n, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"plot(results_unknown_noise.free_energy, title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Below he visualizes the obtained posterior distributions for parameters:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(a)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(b)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25.0 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(b)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25.0 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L\"Prior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(s)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 200 ], label=L\"True $s$\", c = 3)\npsb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L\"Posterior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(s)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 200 ], label=L\"True $s$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$s$\", ylabel=L\"$p(s)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He sees that in the presence of more noise the inference result is more uncertain about the actual values for a and b parameters.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John samples a and b and plot many possible regression lines on the same plot:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"as = rand(results_unknown_noise.posteriors[:a], 100)\nbs = rand(results_unknown_noise.posteriors[:b], 100)\np = scatter(x_data_un, y_data_un, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)\nend\n\nplot(p, size = (900, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"From this plot John can see that many lines do fit the data well and there is no definite \"best\" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Multivariate-linear-regression","page":"Bayesian Linear Regression Tutorial","title":"Multivariate linear regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_multivariate(dim, nr_samples)\n a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))\n b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))\n W ~ InverseWishart(dim + 2, 100 * diageye(dim))\n\n # Here is a small trick to make the example work\n # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`\n x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n z = randomvar(nr_samples)\n\n z .~ x .* a .+ b\n y .~ MvNormal(mean = z, covariance = W)\n\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"After received all the measurement records, he plots the measurements and performance index:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dim_mv = 6\nnr_samples_mv = 50\nrng_mv = StableRNG(42)\na_mv = randn(rng_mv, dim_mv)\nb_mv = 10 * randn(rng_mv, dim_mv)\nv_mv = 100 * rand(rng_mv, dim_mv)\n\nx_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft)\n\nplt = palette(:tab10)\n\ndata_set_label = [\"\"]\n\nfor k in 1:dim_mv\n global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\nxlabel!(L\"$x$\")\nylabel!(L\"$y$\")\np","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Before this data can be used to perform inference, John needs to change its format slightly.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)\ny_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_mv = infer(\n model = linear_regression_multivariate(dim_mv, nr_samples_mv),\n data = (y = y_data_mv_processed, x = x_data_mv_processed),\n initmarginals = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),\n initmessages = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),\n returnvars = (a = KeepLast(), b = KeepLast(), W = KeepLast()),\n free_energy = true,\n iterations = 50,\n constraints = MeanField()\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, W)\n Free Energy: | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7\n22, 712.341, 700.865, 690.782, 682.505 … 664.434, 664.434, 664.434, 664.4\n34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft, xlabel=L\"$x$\", ylabel=L\"$y$\")\n\n# how many lines to plot\nr = 50\n\ni_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))\ni_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))\n\nplt = palette(:tab10)\n\nfor k in 1:dim_mv\n x_mv_k = x_data_mv[k]\n y_mv_k = y_data_mv[k]\n\n for i in 1:r\n global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])\n end\n\n global p = scatter!(p, x_mv_k, y_mv_k, label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\n\n# truncate the init step\nf = plot(results_mv.free_energy[2:end], title =\"Bethe free energy convergence\", label = nothing, xlabel = \"Iteration\", ylabel = \"Bethe free energy [nats]\") \n\nplot(p, f, size = (1000, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_a_mv = results_mv.posteriors[:a]\n\nps_a = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $a_{%$k}$\", xlabel=L\"$a_{%$k}$\", ylabel=L\"$p(a_{%$k})$\", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])\n\n local m_a_mv_k = mean(i_a_mv)[k]\n local v_a_mv_k = std(i_a_mv)[k, k]\n \n _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(a_{%$k})$\", c=2,)\n _p = vline!(_p, [ a_mv[k] ], label=L\"True $a_{%$k}$\", c = 3)\n \n push!(ps_a, _p)\nend\n\nplot(ps_a...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_b_mv = results_mv.posteriors[:b]\n\nps_b = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $b_{%$k}$\", xlabel=L\"$b_{%$k}$\", ylabel=L\"$p(b_{%$k})$\", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])\n local m_b_mv_k = mean(i_b_mv)[k]\n local v_b_mv_k = std(i_b_mv)[k, k]\n\n _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(b_{%$k})$\", c=2,)\n _p = vline!(_p, [ b_mv[k] ], label=L\"Real $b_{%$k}$\", c = 3)\n \n push!(ps_b, _p)\nend\n\nplot(ps_b...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L\"True $s_d$\")\nscatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L\"$\\mathrm{E}[s_d] \\pm \\sigma$\")\nplot!(; xlabel=L\"Dimension $d$\", ylabel=\"Variance\", title=\"Estimated variance of the noise\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-2.-Hierarchical-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 2. Hierarchical Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# https://www.machinelearningplus.com/linear-regression-in-julia/\n# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Understanding-the-Task","page":"Bayesian Linear Regression Tutorial","title":"Understanding the Task","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's explore the data and delve deeper into the problem involved.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dataset = CSV.read(\"../data/hbr/osic_pulmonary_fibrosis.csv\", DataFrame);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"describe(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"7×7 DataFrame\n Row │ variable mean min median max \n ⋯\n │ Symbol Union… Any Union… Any \n ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ Patient ID00007637202177411956430 ID004266\n372 ⋯\n 2 │ Weeks 31.8618 -5 28.0 133\n 3 │ FVC 2690.48 827 2641.0 6399\n 4 │ Percent 77.6727 28.8776 75.6769 153.145\n 5 │ Age 67.1885 49 68.0 88 \n ⋯\n 6 │ Sex Female Male\n 7 │ SmokingStatus Currently smokes Never sm\noke\n 3 columns om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"first(dataset, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5×7 DataFrame\n Row │ Patient Weeks FVC Percent Age Sex Sm\noki ⋯\n │ String31 Int64 Int64 Float64 Int64 String7 St\nrin ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ ID00007637202177411956430 -4 2315 58.2536 79 Male Ex\n-sm ⋯\n 2 │ ID00007637202177411956430 5 2214 55.7121 79 Male Ex\n-sm\n 3 │ ID00007637202177411956430 7 2061 51.8621 79 Male Ex\n-sm\n 4 │ ID00007637202177411956430 9 2144 53.9507 79 Male Ex\n-sm\n 5 │ ID00007637202177411956430 11 2069 52.0634 79 Male Ex\n-sm ⋯\n 1 column om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart(dataset, patient_id; line_kws = true)\n info = patientinfo(dataset, patient_id)\n x = info[!, \"Weeks\"]\n y = info[!, \"FVC\"]\n\n p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)\n p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = \"Weeks\", ylabel = \"FVC\")\n \n if line_kws\n # Use the `GLM.jl` package to estimate linear regression\n linearFormulae = @formula(FVC ~ Weeks)\n linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))\n linearPredicted = predict(linearRegressor)\n p = plot!(p, x, linearPredicted, color = :red, lw = 3)\n end\n\n return p\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart(dataset, \"ID00007637202177411956430\")\np2 = patientchart(dataset, \"ID00009637202177434476278\")\np3 = patientchart(dataset, \"ID00010637202177584971671\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modelling:-Bayesian-Hierarchical-Linear-Regression-with-Partial-Pooling","page":"Bayesian Linear Regression Tutorial","title":"Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the \"pooled model.\" On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the \"unpooled model,\" where each patient has completely separate regression lines.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In this analysis, we will adopt a middle ground approach known as \"Partial pooling.\" Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Mathematically, the model is described by the following equations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n mu_alpha sim mathcalN(mathrmmean = 00 mathrmvariance = 2500000) \n sigma_alpha sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mu_beta sim mathcalN(mathrmmean = 00 mathrmvariance = 90) \n sigma_beta sim mathcalGamma(mathrmshape = 175 mathrmscale = 136) \n alpha_i sim mathcalN(mathrmmean = mu_alpha mathrmprecision = sigma_alpha) \n beta sim mathcalN(mathrmmean = mu_beta mathrmprecision = sigma_beta) \n sigma sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mathrmFVC_ij sim mathcalN(mathrmmean = alpha_i + t beta_i mathrmprecision = sigma)\n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Implementing this model in RxInfer is pretty straightforward:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled(patient_codes, weeks)\n μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β ~ Normal(mean = 0.0, var = 9.0) # Prior for the mean of β (slope)\n σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)\n σ_β ~ Gamma(shape = 1.75, scale = 1.36) # Prior for the precision of β (slope)\n\n n_codes = length(patient_codes) # Total number of data points\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution\n β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the standard deviation of the error term\n \n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes) # Observed FVC measurements\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@constraints function partially_pooled_constraints()\n # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent\n q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)\n # Assume that `μ_α`, `σ_α`, `α` are jointly independent\n q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)\n # Assume that `μ_β`, `σ_β`, `β` are jointly independent\n q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)\n # Assume that `FVC_est`, `σ` are jointly independent\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inference-in-the-model","page":"Bayesian Linear Regression Tutorial","title":"Inference in the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patient_ids = dataset[!, \"Patient\"] # get the column of all patients\npatient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));\npatient_code_column = map(patient -> patient_code_encoder[patient], patient_ids)\n\ndataset[!, :PatientCode] = patient_code_column\n\nfirst(patient_code_encoder, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5-element Vector{Pair{InlineStrings.String31, Int64}}:\n \"ID00197637202246865691526\" => 85\n \"ID00388637202301028491611\" => 160\n \"ID00341637202287410878488\" => 142\n \"ID00020637202178344345685\" => 9\n \"ID00305637202281772703145\" => 127","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_inference(dataset)\n\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n\n results = infer(\n model = partially_pooled(patient_codes, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n σ = vague(Gamma),\n σ_α = vague(Gamma),\n σ_β = vague(Gamma),\n ),\n returnvars = KeepLast(),\n iterations = 100\n )\n \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference_results = partially_pooled_inference(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Checking-the-model","page":"Bayesian Linear Regression Tutorial","title":"Checking the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspecting-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspecting the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)\n local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Looks like our model learned personalized alphas and betas for each patient!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Visualizing-FVC-decline-curves-for-some-patients","page":"Bayesian Linear Regression Tutorial","title":"Visualizing FVC decline curves for some patients","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)\n info = patientinfo(dataset, patient_id)\n patient_code_id = encoder[patient_id]\n\n patient_α = results.posteriors[:α][patient_code_id]\n patient_β = results.posteriors[:β][patient_code_id]\n\n estimated_σ = inv(mean(results.posteriors[:σ]))\n \n predict_weeks = range(-12, 134)\n\n predicted = map(predict_weeks) do week\n pm = mean(patient_α) + mean(patient_β) * week\n pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ\n return pm, sqrt(pv)\n end\n \n p = patientchart(dataset, patient_id; kwargs...)\n \n return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart_bayesian (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\")\np2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\")\np3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The results match our expectations perfectly! Let's highlight the observations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.\nThe model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.\nAdditionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Computing-the-modified-Laplace-Log-Likelihood-and-RMSE","page":"Bayesian Linear Regression Tutorial","title":"Computing the modified Laplace Log Likelihood and RMSE","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n sigma_mathrmclipped = max(sigma 70) \n delta = min(vert mathrmFVC_mathrmtrue - mathrmFVC_mathrmpredvert 1000) \n mathrmmetric = -fracsqrt2deltasigma_mathrmclipped - mathrmln(sqrt2sigma_mathrmclipped) \n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function FVC_predict(results)\n return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s\n return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"FVC_predict (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function compute_rmse(results, dataset)\n FVC_predicted = FVC_predict(results)\n return mean((dataset[!, \"FVC\"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)\nend\n\nfunction compute_laplace_log_likelihood(results, dataset)\n FVC_predicted = FVC_predict(results)\n sigma_c = std.(FVC_predicted)\n sigma_c[sigma_c .< 70] .= 70\n delta = abs.(mean.(FVC_predicted) .- dataset[!, \"FVC\"])\n delta[delta .> 1000] .= 1000\n return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"compute_laplace_log_likelihood (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.0313266260767\nLaplace Log Likelihood: -6.15689374755478","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Add-layer-to-model-hierarchy:-Smoking-Status","page":"Bayesian Linear Regression Tutorial","title":"Add layer to model hierarchy: Smoking Status","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We can enhance the model by incorporating the column \"SmokingStatus\" as a pooling level, where model parameters will be partially pooled within the groups \"Never smoked,\" \"Ex-smoker,\" and \"Currently smokes.\" To achieve this, we need to:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Encode the \"SmokingStatus\" column. Map the patient encoding to the corresponding \"SmokingStatus\" encodings. Refine and retrain the model with the additional hierarchical structure.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"combine(groupby(dataset, \"SmokingStatus\"), nrow)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"3×2 DataFrame\n Row │ SmokingStatus nrow\n │ String31 Int64\n─────┼─────────────────────────\n 1 │ Ex-smoker 1038\n 2 │ Never smoked 429\n 3 │ Currently smokes 82","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, \"SmokingStatus\"]))))\nsmoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id\n smoking_status = first(unique(patientinfo(dataset, patient_id)[!, \"SmokingStatus\"]))\n return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]\nend)\n\nsmoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)\n μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)\n σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n σ_β_global ~ Gamma(shape = 1.75, scale = 1.36) # Corresponds to half-normal with scale 3.0\n\n n_codes = length(patient_codes) # Total number of data points\n n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern\n μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern\n \n for i in 1:n_smoking_statuses\n μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)\n μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)\n end\n \n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)\n β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n\n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes)\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\n \nend\n\n@constraints function partially_pooled_with_smooking_constraints()\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)\n q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)\n q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)\n q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smooking_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n \n return infer(\n model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_with_smooking_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n σ = Gamma(1.75, 45.54),\n σ_α_global = Gamma(1.75, 45.54),\n σ_β_global = Gamma(1.75, 1.36),\n ),\n returnvars = KeepLast(),\n iterations = 100,\n )\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspect-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspect the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)\n local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)\n local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])\n local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α_global)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β_global)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n local p5 = plot(title = \"q(μ_α_smoking_status)...\", legend = false)\n local p6 = plot(title = \"q(μ_β_smoking_status)...\", legend = false)\n \n foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) \n foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)\n \n plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Interpret-smoking-status-model-parameters","page":"Bayesian Linear Regression Tutorial","title":"Interpret smoking status model parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Dict{InlineStrings.String31, Int64} with 3 entries:\n \"Currently smokes\" => 3\n \"Ex-smoker\" => 1\n \"Never smoked\" => 2","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]\n\nprintln(\"Trend for\")\nforeach(pairs(smoking_id_mapping)) do (key, id)\n println(\" $key: $(mean(posteriors_μ_β_smoking_status[id]))\")\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Trend for\n Currently smokes: 1.8157457671008241\n Ex-smoker: -4.56516461765951\n Never smoked: -4.446729680170274","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Let's look at these curves for individual patients to help interpret these model results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Never smoked\np1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\") \n# Ex-smoker\np2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\") \n# Currently smokes\np3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\") \n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Review-patients-that-currently-smoke","page":"Bayesian Linear Regression Tutorial","title":"Review patients that currently smoke","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"When plotting each patient with the smoking status \"Currently smokes,\" we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Depending on the purpose of the model, we can proceed in different ways:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.\nHowever, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the \"Currently smokes\" group's parameters closer to the global parameters, or even consider merging the group with \"Ex-smokers.\" Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"let \n local plots = []\n\n for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==(\"Currently smokes\"), dataset)[!, \"Patient\"]))\n push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))\n end\n\n plot(plots..., size = (1200, 1200))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modified-Laplace-Log-Likelihood-and-RMSE-for-model-with-Smoking-Status-Level","page":"Bayesian Linear Regression Tutorial","title":"Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We calculate the metrics for the updated model and compare to the original model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.7845980866563\nLaplace Log Likelihood: -6.165346437287973","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#References","page":"Bayesian Linear Regression Tutorial","title":"References","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#examples-probit-model-(ep)","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable x_t with the discrete variable y_t. The model is defined as:","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"beginaligned\n u = 01 \n x_0 sim mathcalN(0 100) \n x_t sim mathcalN(x_t-1+ u 001) \n y_t sim mathrmBer(Phi(x_t))\nendaligned","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Import-packages","page":"Probit Model (EP)","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"using RxInfer, StableRNGs, Random, Plots\nusing StatsFuns: normcdf","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Data-generation","page":"Probit Model (EP)","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n \n # hyper parameters\n u = 0.1\n\n # allocate space for data\n data_x = zeros(nr_samples + 1)\n data_y = zeros(nr_samples)\n \n # initialize data\n data_x[1] = -2\n \n # generate data\n for k = 2:nr_samples + 1\n \n # calculate new x\n data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)\n \n # calculate y\n data_y[k-1] = normcdf(data_x[k]) > rand(rng)\n \n end\n \n # return data\n return data_x, data_y\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"n = 40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"data_x, data_y = generate_data(n);","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"p = plot(xlabel = \"t\", ylabel = \"x, y\")\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\")","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Model-specification","page":"Probit Model (EP)","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"@model function probit_model(nr_samples::Int64)\n \n # allocate space for variables\n x = randomvar(nr_samples + 1)\n y = datavar(Float64, nr_samples)\n \n # specify uninformative prior\n x[1] ~ Normal(mean = 0.0, precision = 0.01)\n \n # create model \n for k = 2:nr_samples + 1\n x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)\n y[k - 1] ~ Probit(x[k]) where {\n # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge\n # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations\n pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) \n }\n end\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Inference","page":"Probit Model (EP)","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"result = infer(\n model = probit_model(length(data_y)), \n data = (y = data_y, ), \n iterations = 5, \n returnvars = (x = KeepLast(),),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"Inference results:\n Posteriors | available for (x)\n Free Energy: | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Results","page":"Probit Model (EP)","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"mx = result.posteriors[:x]\n\np = plot(xlabel = \"t\", ylabel = \"x, y\", legend = :bottomright)\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\", lw = 2)\np = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label=\"x (inferred mean)\")\n\nf = plot(xlabel = \"t\", ylabel = \"BFE\")\nf = plot!(result.free_energy, label = \"Bethe Free Energy\")\n\nplot(p, f, size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#examples-advanced-tutorial","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This tutorial is also available in the documentation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#General-model-specification-syntax","page":"Advanced Tutorial","title":"General model specification syntax","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We use the @model macro from the RxInfer.jl package to create a probabilistic model p(s y) and we also specify extra constraints on the variational family of distributions mathcalQ, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `@model` macro accepts a regular Julia function\n@model function test_model1(s_mean, s_precision)\n \n # We use the `randomvar` function to create \n # a random variable in our model\n s = randomvar()\n \n # the `tilde` operator creates a functional dependency\n # between variables in our model and can be read as \n # `sampled from` or `is modeled by`\n s ~ Normal(mean = s_mean, precision = s_precision)\n \n # We use the `datavar` function to create \n # observed data variables in our models\n # We also need to specify the type of our data \n # In this example it is `Float64`\n y = datavar(Float64)\n \n y ~ Normal(mean = s, precision = 1.0)\n \n # It is possible to return something from the model specification (including variables and nodes)\n return \"Hello world\"\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"modelgenerator = test_model1(0.0, 1.0)\n\nmodel, returnval = create_model(modelgenerator)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(FactorGraphModel(), \"Hello world\")","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(): returns an array of factor nodes in a corresponding factor graph\ngetrandom(): returns an array of random variables in the model\ngetdata(): returns an array of data inputs in the model\ngetconstant(): returns an array of constant values in the model","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(model)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"FactorNodesCollection(nodes: 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getrandom(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :s","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getdata(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :y","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getconstant(model) .|> getconst","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 1.0","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model2(n)\n \n if n <= 1\n error(\"`n` argument must be greater than one.\")\n end\n \n # `randomvar(n)` creates a dense sequence of \n # random variables\n s = randomvar(n)\n \n # `datavar(Float64, n)` creates a dense sequence of \n # observed data variables of type `Float64`\n y = datavar(Float64, n)\n \n s[1] ~ Normal(mean = 0.0, precision = 0.1)\n y[1] ~ Normal(mean = s[1], precision = 1.0)\n \n for i in 2:n\n s[i] ~ Normal(mean = s[i - 1], precision = 1.0)\n y[i] ~ Normal(mean = s[i], precision = 1.0)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, _ = create_model(test_model2(10));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of factor nodes in generated Factor Graph\ngetnodes(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"20","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of random variables\ngetrandom(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of data inputs\ngetdata(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of constant values\ngetconstant(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"21","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use complex expressions inside the functional dependency expressions","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# s = randomvar() here is optional\n# `~` creates random variables automatically\ns ~ NormalMeanPrecision(0.0, 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example model which will throw an error:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function error_model1()\n s = 1.0\n s ~ NormalMeanPrecision(0.0, 1.0)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Creates constant reference in a model with a prespecified value\nc = constvar(0.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)\n \n s = randomvar(n)\n \n y = datavar(Vector{Float64}, n)\n \n # Here we create constant references\n # for constant matrices in our model \n # to make inference more memory efficient\n cA = constvar(A)\n cP = constvar(P)\n cQ = constvar(Q)\n \n s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)\n y[1] ~ MvNormal(mean = s[1], covariance = cQ)\n \n for i in 2:n\n s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)\n y[i] ~ MvNormal(mean = s[i], covariance = cQ)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n\n # In this example `ynode` refers to the corresponding \n # `GaussianMeanVariance` node created in the factor graph\n ynode, y ~ GaussianMeanVariance(0.0, 1.0)\n \n return ynode, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Probabilistic-inference-in-RxInfer.jl","page":"Advanced Tutorial","title":"Probabilistic inference in RxInfer.jl","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Observables","page":"Advanced Tutorial","title":"Observables","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Observables are lazy push-based collections and they deliver their values over time.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Timer that emits a new value every second and has an initial one second delay \nobservable = timer(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerObservable(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"actor = (value) -> println(value)\nsubscription1 = subscribe!(observable, actor)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We always need to unsubscribe from some observables\nunsubscribe!(subscription1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We can modify our observables\nmodified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Int64, MapProxy(Int64))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscription2 = subscribe!(modified, (value) -> println(value))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(subscription2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n \n # We assume that the outcome of each coin flip \n # is modeled by a Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during the inference step\n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can call the inference function to run inference in such model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"p = 0.75 # Bias of a coin\n\ndataset = float.(rand(Bernoulli(p), 500));\n\nresult = infer(\n model = coin_toss_model(length(dataset)),\n data = (y = dataset, )\n)\n\nprintln(\"Inferred bias: \", mean_var(result.posteriors[:θ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inferred bias: (0.7662082514734774, 0.00035124150362241923)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can see that the inferred bias is quite close to the actual value we used in the dataset generation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getmarginal(x): for a single random variable x\ngetmarginals(xs): for a dense sequence of random variables sx","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = create_model(coin_toss_model(length(dataset)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# As soon as we have a new value for the marginal posterior over the `θ` variable\n# we simply print the first two statistics of it\nθ_subscription = subscribe!(getmarginal(θ), (marginal) -> println(\"New update: mean(θ) = \", mean(marginal), \", std(θ) = \", std(marginal)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To pass data to our model we use update! function","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"New update: mean(θ) = 0.7662082514734774, std(θ) = 0.01874143814178675","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It is necessary to always unsubscribe from running observables\nunsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them\n# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing\nupdate!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `keep` actor simply keeps all incoming updates in an internal storage, ordered\nθvalues = keep(Marginal)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"KeepActor{Marginal}(Marginal[])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `getmarginal` always emits last cached value as its first value\nsubscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=390.0, β=119.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"2-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=390.0, β=119.0))\n Marginal(Beta{Float64}(α=390.0, β=119.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `buffer` actor keeps very last incoming update in an internal storage and can also store \n# an array of updates for a sequence of random variables\nθbuffer = buffer(Marginal, 1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=390.0, β=119.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=390.0, β=119.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Reactive-Online-Inference","page":"Advanced Tutorial","title":"Reactive Online Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function online_coin_toss_model()\n \n # We create datavars for the prior \n # over `θ` variable\n θ_a = datavar(Float64)\n θ_b = datavar(Float64)\n \n θ ~ Beta(θ_a, θ_b)\n \n y = datavar(Float64)\n y ~ Bernoulli(θ)\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"autoupdates = @autoupdates begin \n θ_a, θ_b = params(q(θ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(θ_a,θ_b = params(q(θ)),)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"rxresult = infer(\n model = online_coin_toss_model(),\n data = (y = dataset, ),\n autoupdates = autoupdates,\n historyvars = (θ = KeepLast(), ),\n keephistory = length(dataset),\n initmarginals = (\n θ = vague(Beta),\n ),\n autostart = true\n);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"animation = @animate for i in 1:length(dataset)\n plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = \"Online coin bias inference\", label = \"Inferred bias\", legend = :bottomright)\n hline!([ p ], label = \"Real bias\", size = (600, 200))\nend\n\ngif(animation, \"../pics/online-coin-bias-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Variational-inference","page":"Advanced Tutorial","title":"Variational inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions q in mathcalQ. Often this involves assuming some factorization over q. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_a for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"There are several options to specify the mean-field factorisation constraint. ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use local structured factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-constraints-macro","page":"Advanced Tutorial","title":"RxInfer.jl constraints macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints6 = @constraints begin\n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: where blocks have higher priority over constraints specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Inference","page":"Advanced Tutorial","title":"Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To run inference in this model we again need to create a synthetic dataset:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#inference-function","page":"Advanced Tutorial","title":"inference function","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Use ?inference to quickly check the documentation for the inference function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"result = infer(\n model = test_model6(length(dataset)),\n data = (y = dataset, ),\n constraints = constraints6, \n initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),\n returnvars = (μ = KeepLast(), τ = KeepLast()),\n iterations = 10,\n free_energy = true,\n showprogress = true\n)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inference results:\n Posteriors | available for (μ, τ)\n Free Energy: | Real[14763.3, 3276.03, 684.158, 646.181, 646.181, 646.\n181, 646.181, 646.181, 646.181, 646.181]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(result.posteriors[:μ]), \", std = \", std(result.posteriors[:μ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -3.0056908466725094, std = 0.014489267624899296","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(result.posteriors[:τ]), \", std = \", std(result.posteriors[:τ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 4.763281190254187, std = 0.2128077093353377","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Manual-inference","page":"Advanced Tutorial","title":"Manual inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.011708551085051e-9, w=\n0.010000001002000566))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.568551355196337, w=9.\n182098823340285))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9439.094316526523, w=314\n0.4109865644887))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14309.600684674531, w=47\n60.835837794097))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.97336150061, w=476\n3.288738549474))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980723228184, w=47\n63.291187807456))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730575227, w=47\n63.29119025181))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730582567, w=47\n63.291190254112))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730582556, w=47\n63.291190254099))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-14316.980730582549, w=47\n63.291190254099))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(GammaShapeRate{Float64}(a=501.0, b=5.0000000000462156e14))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=54622.176412349254))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=159.5337672301783))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.23384325945597))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17965197908343))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959789617599))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784220113))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784214716))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784214723))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=105.17959784214727))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(last(μ_values)), \", std = \", std(last(μ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -3.0056908466725094, std = 0.014489267624899296","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(last(τ_values)), \", std = \", std(last(τ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 4.763281190254187, std = 0.2128077093353377","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Form-constraints","page":"Advanced Tutorial","title":"Form constraints","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints7 = @constraints begin \n q(μ) :: PointMass\n \n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_i for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar()\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, PointMass(1.0))\n\nμ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(PointMass{Float64}(-3.0056908529699893))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(GammaShapeRate{Float64}(a=501.0, b=105.07462840395456))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { \n prod_constraint = ProdGeneric(),\n form_constraint = SampleListFormConstraint() \n}","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: @constraints macro specifies required prod_constraint automatically.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Free-Energy","page":"Advanced Tutorial","title":"Free Energy","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_observable = score(model, Float64, BetheFreeEnergy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Float64, ErrorIfProxy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_subscription = subscribe!(bfe_observable, (fe) -> println(\"Current BFE value: \", fe));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Reset the model with vague marginals\nsetmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Current BFE value: 658.7153120621533\nCurrent BFE value: 646.1805207523544\nCurrent BFE value: 646.1805205034352\nCurrent BFE value: 646.1805205034316\nCurrent BFE value: 646.1805205034375\nCurrent BFE value: 646.1805205034352\nCurrent BFE value: 646.1805205034343\nCurrent BFE value: 646.1805205034334\nCurrent BFE value: 646.1805205034334\nCurrent BFE value: 646.1805205034334","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It always necessary to unsubscribe and release computer resources\nunsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Meta-data-specification","page":"Advanced Tutorial","title":"Meta data specification","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of \n# the autoregressive process and its order. In addition it specifies that the message computation rules should\n# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations\n# by cost of possible numerical instabilities during an inference procedure\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }\n...\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` \n# method with `21` sigma points for approximation of non-lineariety between hierarchy layers\nxt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-@meta-macro","page":"Advanced Tutorial","title":"RxInfer.jl @meta macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@meta begin \n AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Meta specification:\n AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Creating-custom-nodes-and-message-computation-rules","page":"Advanced Tutorial","title":"Creating custom nodes and message computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-nodes","page":"Advanced Tutorial","title":"Custom nodes","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification\n@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]\n\n# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error\nstruct NormalMeanVariance end \n\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# It is also possible to use function objects as a node functional form\nfunction dot end\n\n# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them \n# out = dot(x, a)\n@node typeof(dot) Deterministic [ out, x, a ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"After that it is possible to use the newly created node during model specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n ...\n y ~ dot(x, a)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-messages-computation-rules","page":"Advanced Tutorial","title":"Custom messages computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu_z = mu_x + mu_y\nV_z = V_x + V_y\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To specify this in RxInfer.jl we use the @node and @rule macros:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@node typeof(+) Deterministic [ z, x, y ]\n\n@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin\n x_mean, x_var = mean_var(m_x)\n y_mean, y_var = mean_var(m_y)\n return NormalMeanVariance(x_mean + y_mean, x_var + y_var)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(z) = int q(z x y) mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu(z) = int f(x y z)mu(x)mu(y)mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nnu(z) = exp int log f(x y z)q(x)q(y)mathrmdxmathrmdy \nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @rule macro supports both cases with special prefixes during rule specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"m_ prefix corresponds to the incoming message on a specific edge\nq_ prefix corresponds to the posterior marginal of a specific edge","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Sum-Product rule with m_ messages used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin \n m_out_mean, m_out_cov = mean_cov(m_out)\n return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Variational rule with Mean-Field assumption with q_ posteriors used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin \n return NormalMeanPrecision(mean(q_out), mean(q_τ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin\n m, V = mean_cov(q_out_μ)\n θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))\n α = convert(typeof(θ), 1.5)\n return Gamma(α, θ)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference backend expects arguments in `@rule` macro to be in the same order\n@node NormalMeanPrecision Stochastic [ out, μ, τ ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Any rule always has access to the meta information with hidden the meta::Any variable:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin \n ...\n println(meta)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to dispatch on a specific type of a meta object:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"or","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Customizing-messages-computational-pipeline","page":"Advanced Tutorial","title":"Customizing messages computational pipeline","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Logs all outbound messages\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }\n# Initialise messages to be vague\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }\n# In principle, it is possible to approximate outbound messages with Laplace Approximation\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let us return to the coin toss model, but this time we want to print flowing messages:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model_log(n)\n\n y = datavar(Float64, n)\n\n θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage(\"θ\") }\n\n for i in 1:n\n y[i] ~ Bernoulli(θ) where { pipeline = LoggerPipelineStage(\"y[$i]\") }\n end\n \n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"θ_subscription = subscribe!(getmarginal(θ), (value) -> println(\"New posterior marginal for θ: \", value));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[θ][Beta][out]: VariationalMessage()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"coinflips = float.(rand(Bernoulli(0.5), 5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, coinflips)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[y[1]][Bernoulli][p]: VariationalMessage()\n[y[2]][Bernoulli][p]: VariationalMessage()\n[y[3]][Bernoulli][p]: VariationalMessage()\n[y[4]][Bernoulli][p]: VariationalMessage()\n[y[5]][Bernoulli][p]: VariationalMessage()\nNew posterior marginal for θ: Marginal(Beta{Float64}(α=4.0, β=10.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference is lazy and does not send messages if no one is listening for them\nupdate!(y, coinflips)","category":"page"},{"location":"manuals/custom-node/#create-node","page":"Defining a custom node and rules","title":"Creating your own custom nodes","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To create a custom node in RxInfer, 4 steps are required:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Create your custom node in RxInfer using the @node macro.\nDefine the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.\nSpecify computations for marginal distributions of the relevant variables with the @marginalrule macro.\nImplement the computation of the Free Energy in a node with the @average_energy macro.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!","category":"page"},{"location":"manuals/custom-node/#Problem-statement","page":"Defining a custom node and rules","title":"Problem statement","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin K=20 times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment x_kin01 using the Bernoulli distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_k mid pi) = mathrmBer(x_k mid pi) = pi^x_k (1-pi)^1-x_k","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"where pi in01 denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of pi which she models using the Beta distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(pi) = mathrmBeta(pi mid 4 8)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With this prior belief, the total probabilistic model that she has for this experiment is given by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_1K pi) = p(pi) prod_k=1^K p(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of pi, p(pi mid x_1K), denoting how pi is distributed after we have seen the data.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-1:-Creating-the-custom-node","page":"Defining a custom node and rules","title":"Step 1: Creating the custom node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nIn this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"First things first, let's import RxInfer:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using RxInfer","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The name of the node. (::Type)\nWhether the node is Deterministic or Stochastic.\nThe interfaces of the node and any potential aliases. (::Vector)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"# struct for Bernoulli distribution with success probability π\nstruct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution\n π :: T\n new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError(\"π must be between 0 and 1\"))\t\nend\n\n# for simplicity, let's also specify the mean of the distribution\nDistributions.mean(d::MyBernoulli) = d.π\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nYou can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of pi, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Concluding, we can create the MyBernoulli factor node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@node MyBernoulli Stochastic [out, (π, aliases = [p])]","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Cool! Step 1 is done, we have created a custom node.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-2:-Defining-rules-for-our-node","page":"Defining a custom node and rules","title":"Step 2: Defining rules for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as p(pimid x_1K), we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.","category":"page"},{"location":"manuals/custom-node/#Sum-product-message-passing-update-rules","page":"Defining a custom node and rules","title":"Sum-product message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In sum-product message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecmu(x) propto int mathrmBer(xmid pi) vecmu(pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(pi) propto sum_x in 01 mathrmBer(xmid pi) overleftarrowmu(x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain pi = fracalphaalpha + beta, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for \"the incoming message on interface π\". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(π) propto mathrmBeta(1 + x 2 - x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which gives us the following update rule:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin\n p = mean(m_out)\n Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/#Variational-message-passing-update-rules","page":"Defining a custom node and rules","title":"Variational message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecnu(x) propto exp int q(pi) ln mathrmBer(xmid pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrownu(pi) propto exp sum_x in 01 q(x) ln mathrmBer(xmid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"#rules towards out\n@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))\n\n@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin\n rho_1 = mean(log, q_π) # E[ln(x)]\n rho_2 = mean(mirrorlog, q_π) # E[log(1-x)]\n m = max(rho_1, rho_2)\n tmp = exp(rho_1 - m)\n p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))\n return Bernoulli(p)\nend\n\n#rules towards π\n@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin\n p = mean(q_out)\n return Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"node: Node\nTypically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-3:-Defining-joint-marginals-for-our-node","page":"Defining a custom node and rules","title":"Step 3: Defining joint marginals for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Fqf = - sum_ainmathcalV mathrmHq_a(s_a) - sum_ainmathcalVmathrmE_q_a(s_a)ln f_a(s_a) + sum_iinmathcalEmathrmHq_i(s_i)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here we call q_a(s_a) the joint marginals around a node and -mathrmE_q_a(s_a)ln f_a(s_a) we term the average energy.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to be able to compute the Bethe free energy, we need to first describe how to compute q_a(s_a), defined in our case as ","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"q(x_k pi) = vecmu(pi) overleftarrowmu(x_k) mathrmBer(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin\n r = mean(m_out)\n p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)\n return (out = m_out, p = p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as q(x_k pi) = q(x_k)q(pi). These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing q(pi) we need to compute the product vecmu(pi)overleftarrowmu(pi). We already know how overleftarrowmu(pi) looks like from the previous step, so we can just use the prod function.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-4:-Defining-the-average-energy-for-our-node","page":"Defining a custom node and rules","title":"Step 4: Defining the average energy for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as -mathrmE_q(x_k pi)ln p(x_k mid pi), however, because we know that we observe x_k and therefore q(x_k pi) factorizes, we can instead compute beginaligned -mathrmE_q(x_k)q(pi)ln p(x_k mid pi) = -mathrmE_q(x_k)q(pi) ln (pi^x_k (1-pi)^1 - x_k) \n= -mathrmE_q(x_k)q(pi) x_k ln(pi) + (1-x_k) ln(1-pi) \n= -mathrmE_q(x_k)x_k mathrmE_q(pi) ln(pi) - (1-mathrmE_q(x_k)x_k) mathrmE_q(pi)ln(1-pi) endaligned","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to mathrmE_q(x)1-logx.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....","category":"page"},{"location":"manuals/custom-node/#Using-our-node-in-a-model","page":"Defining a custom node and rules","title":"Using our node in a model","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Random\n\nrng = MersenneTwister(42)\nn = 500\nπ_real = 0.75\ndistribution = Bernoulli(π_real)\n\ndataset = float.(rand(rng, distribution, n))\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model_mybernoulli(n)\n\n # `datavar` creates data 'inputs' in our model\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n π ~ Beta(4.0, 8.0)\n\n # We assume that outcome of each coin flip is governed by the MyBernoulli distribution\n for i in 1:n\n y[i] ~ MyBernoulli(π)\n end\n\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Finally, we can run inference with this model and the generated dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"result_mybernoulli = infer(\n model = coin_model_mybernoulli(length(dataset)), \n data = (y = dataset, ),\n)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label=\"p(π|x)\", c=3)\nvline!([π_real], label=\"Real π\")","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model(n)\n \n y = datavar(Float64, n)\n p ~ Beta(4.0, 8.0)\n\n for i in 1:n\n y[i] ~ Bernoulli(p)\n end\n\nend\n\nresult_bernoulli = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, ),\n)\n\nif !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])\n error(\"Results are not identical\")\nelse \n println(\"Results are identical 🎉🎉🎉\")\nend\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#examples-simple-nonlinear-node","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using RxInfer, Random, StableRNGs","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here is an example of creating custom node with nonlinear function approximation with samplelist.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Custom-node-creation","page":"Simple Nonlinear Node","title":"Custom node creation","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"struct NonlinearNode end # Dummy structure just to make Julia happy\n\nstruct NonlinearMeta{R, F}\n rng :: R\n fn :: F # Nonlinear function, we assume 1 float input - 1 float output\n nsamples :: Int # Number of samples used in approximation\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@node NonlinearNode Deterministic [ out, in ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"We need to define two Sum-product message computation rules for our new custom node","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Rule for outbound message on out edge given inbound message on in edge\nRule for outbound message on in edge given inbound message on out edge\nBoth rules accept optional meta object","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `out` edge given inbound message on `in` edge\n@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin \n samples = rand(meta.rng, m_in, meta.nsamples)\n return SampleList(map(meta.fn, samples))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `in` edge given inbound message on `out` edge\n@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin \n return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Model-specification","page":"Simple Nonlinear Node","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"After we have defined our custom node with custom rules we may proceed with a model specification:","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"beginaligned\np(theta) = mathcalN(thetamu_theta sigma_theta)\np(m) = mathcalN(thetamu_m sigma_m)\np(w) = f(theta)\np(y_im w) = mathcalN(y_im w)\nendaligned","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable theta through a non-linear transformation f to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of theta. ","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@model function nonlinear_estimation(n)\n \n θ ~ Normal(mean = 0.0, variance = 100.0)\n m ~ Normal(mean = 0.0, variance = 1.0)\n \n w ~ NonlinearNode(θ)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = m, precision = w)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@constraints function nconstsraints(nsamples)\n q(θ) :: SampleList(nsamples, LeftProposal())\n q(w) :: SampleList(nsamples, RightProposal())\n \n q(θ, w, m) = q(θ)q(m)q(w)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nconstsraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@meta function nmeta(fn, nsamples)\n NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here we generate some data","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn(x) = abs(exp(x) * sin(x))","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"seed = 123\nrng = StableRNG(seed)\n\nniters = 15 # Number of VMP iterations\nnsamples = 5_000 # Number of samples in approximation\n\nn = 500 # Number of IID samples\nμ = -10.0\nθ = -1.0\nw = nonlinear_fn(θ)\n\ndata = rand(rng, NormalMeanPrecision(μ, w), n);","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"result = infer(\n model = nonlinear_estimation(n),\n meta = nmeta(nonlinear_fn, nsamples),\n constraints = nconstsraints(nsamples),\n data = (y = data, ), \n initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),\n returnvars = (θ = KeepLast(), ),\n iterations = niters, \n showprogress = true\n)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"θposterior = result.posteriors[:θ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"SampleList(Univariate, 5000)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using Plots, StatsPlots\n\nestimated = Normal(mean_std(θposterior)...)\n\nplot(estimated, title=\"Posterior for θ\", label = \"Estimated\", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))\nvline!([ θ ], label = \"Real value of θ\")","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"page"},{"location":"library/exported-methods/#lib-using-methods","page":"Exported methods","title":"Using methods from RxInfer","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"A nice explanation about how modules/packages work in Julia can be found in the official documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean as mean_from_rxinfer\nimport Distributions: mean as mean_from_distributions\n\nmean_from_rxinfer === mean_from_distributions","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"# It is easier to let Julia resolve names automatically\n# Julia will not overwrite `mean` that is coming from both packages\nusing RxInfer, Distributions ","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`","category":"page"},{"location":"library/exported-methods/#lib-list-methods","page":"Exported methods","title":"List of available methods","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"note: Note\nSome exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer #hide\nforeach(println, names(RxInfer))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/#examples-nonlinear-sensor-fusion","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"section"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers\nusing DataFrames, DelimitedFiles, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"To illustrate these noisy measurements, the engineers decided to plot them:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# fetch measurements\nbeacon_locations = readdlm(\"../data/sensor_fusion/beacons.txt\")\ndistances = readdlm(\"../data/sensor_fusion/distances.txt\")\nposition = readdlm(\"../data/sensor_fusion/position.txt\")\nnr_observations = size(distances, 1);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual location of WALL-E\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\")\n\n# plot noisy distance measurements\np2 = plot(distances, legend=:topleft, linewidth=3, label=[\"distance to beacon 1\" \"distance to beacon 2\" \"distance to beacon 3\"])\nxlabel!(\"time [sec]\"), ylabel!(\"distance [m]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time t, denoted by z_t, follows a 2-dimensional normal random walk:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(z_t mid z_t - 1) = mathcalN(z_t mid z_t-1mathrmI_2)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"where mathrmI_2 denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements y_t as a noisy set of the distances between WALL-E and the beacons, specified by s_i:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(y_t mid z_t) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixmathrmI_3 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# function to compute distance to beacons\nfunction compute_distances(z) \n distance1 = norm(z - beacon_locations[1,:])\n distance2 = norm(z - beacon_locations[2,:])\n distance3 = norm(z - beacon_locations[3,:])\n distances = [distance1, distance2, distance3]\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model(nr_observations)\n \n # specify precision matrices\n W = diageye(2)\n R = diageye(3)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], W)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":" compute_distances(z) -> CVI(..., Val(false), ...)","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)\n compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"NOTE: You can try out different meta for approximating the nonlinearity, e.g.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_linear_meta()\n compute_distances(z) -> Linearization()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_unscented_meta()\n compute_distances(z) -> Unscented()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_fast = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_accuracy = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1000, 100, StableRNG(42)),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"After running this fast inference procedure, the engineers plot the results and evaluate the performance:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_fast.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Fast (1 sample, 3 iterations)\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot beacon and actual and estimated location of WALL-E (accurate inference)\np2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_accuracy.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Accurate (1000 samples, 100 iterations)\"); p2.series_list[end][:label] = \"estimated location ±2σ\"\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, Q and R respectively. They did this by adding Wishart priors to those matrices:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(Q) = mathcalW(Q mid 3 mathrmI_2) \n p(R) = mathcalW(R mid 4 mathrmI_3) \n p(z_t mid z_t - 1 Q) = mathcalN(z_t mid z_t-1 Q^-1)\n p(y_t mid z_t R) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixR^-1 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model_wishart(nr_observations)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # set priors on precision matrices\n Q ~ Wishart(3, diageye(2))\n R ~ Wishart(4, diageye(3))\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], Q)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"meta = @meta begin \n compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"constraints = @constraints begin\n q(z, Q, R) = q(z)q(Q)q(R)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_wishart = infer(\n model = random_walk_model_wishart(nr_observations),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = constraints,\n meta = meta,\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),\n initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"They plot the new estimates and the performance over time, and luckily WALL-E is found!","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_wishart.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot bethe free energy performance\np2 = plot(results_wishart.free_energy, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"page"},{"location":"examples/problem_specific/overview/#examples-problem_specific-overview","page":"Overview","title":"Problem specific","text":"","category":"section"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Autoregressive Models: An example of Bayesian treatment of latent AR and ARMA models. Reference: Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.\nGamma Mixture Model: This example implements one of the Gamma mixture experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/ .\nGaussian Mixture: This example implements variational Bayesian inference in univariate and multivariate Gaussian mixture models with mean-field assumption.\nHierarchical Gaussian Filter: An example of online inference procedure for Hierarchical Gaussian Filter with univariate noisy observations using Variational Message Passing algorithm. Reference: Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter.\nInvertible neural networks: a tutorial: An example of variational Bayesian Inference with invertible neural networks. Reference: Bart van Erp, Hybrid Inference with Invertible Neural Networks in Factor Graphs.\nProbit Model (EP): In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model.\nRTS vs BIFM Smoothing: This example performs BIFM Kalman smoother on a factor graph using message passing and compares it with the RTS implementation.\nSimple Nonlinear Node: In this example we create a non-conjugate model and use a nonlinear link function between variables. We show how to extend the functionality of RxInfer and to create a custom factor node with arbitrary message passing update rules.\nUniversal Mixtures: Universal mixture modeling.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/#examples-coin-toss-model-(beta-bernoulli)","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"section"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"In this example, we are going to perform an exact inference for a coin toss model that can be represented as:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"beginaligned\np(theta) = mathrmBeta(thetaa b)\np(y_itheta) = mathrmBer(y_itheta)\nendaligned","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"where y_i in 0 1 is a binary observation induced by Bernoulli likelihood while theta is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of theta.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using RxInfer, Random","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"rng = MersenneTwister(42)\nn = 500\nθ_real = 0.75\ndistribution = Bernoulli(θ_real)\n\ndataset = float.(rand(rng, Bernoulli(θ_real), n));","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n θ ~ Beta(4.0, 8.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n\n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, )\n)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Beta{Float64}(α=365.0, β=147.0)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\nplot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\nvline!([θ_real], label=\"Real θ\")","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#examples-invertible-neural-networks:-a-tutorial","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Table of contents","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Introduction\nModel specification\nModel compilation\nProbabilistic inference\nParameter estimation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Introduction","page":"Invertible neural networks: a tutorial","title":"Introduction","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Load-required-packages","page":"Invertible neural networks: a tutorial","title":"Load required packages","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Before we can start, we need to import some packages:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using RxInfer\nusing Random\nusing StableRNGs\n\nusing ReactiveMP # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality\nusing LinearAlgebra # only used for some matrix specifics\nusing Plots # only used for visualisation\nusing Distributions # only used for sampling from multivariate distributions\nusing Optim # only used for parameter optimisation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-specification","page":"Invertible neural networks: a tutorial","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Alternatively, the input_dim can also be passed as an InputLayer layer as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the above AdditiveCouplingLayer layers the input bfx = x_1 x_2 ldots x_N is partitioned into chunks of unit length. These partitions are additively coupled to an output bfy = y_1 y_2 ldots y_N as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n y_1 = x_1 \n y_2 = x_2 + f_1(x_1) \n vdots \n y_N = x_N + f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Importantly, this structure can easily be converted as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n x_1 = y_1 \n x_2 = y_2 - f_1(x_1) \n vdots \n x_N = y_N - f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"f_n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow(); permute=false),\n PermutationLayer(PermutationMatrix(2)),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-compilation","page":"Invertible neural networks: a tutorial","title":"Model compilation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the current models, the layers are setup to work with the passed input dimension. This means that the function f_n is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P\nlanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa\nyerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou\nplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar\nFlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad\nditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive\nMP.PlanarFlowEmpty{1}(),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel - specifies that we are dealing with a flow model.\n3 - Number of layers.\nTuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.\nTuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions f_n.\nPermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(0.24357081234214367, -0.7202599\n849473186, 0.7012262639170591),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(-0.0928216039987209, -2.329353058120145, 0.570152767728\n4544),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361\n28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323\n52386),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Probabilistic-inference","page":"Invertible neural networks: a tutorial","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)\n\n rng = StableRNG(seed)\n \n # specify latent sampling distribution\n dist = MvNormal([1.5, 0.5], I)\n\n # sample from the latent distribution\n x = rand(rng, dist, nr_samples)\n\n # transform data\n y = zeros(Float64, size(x))\n for k = 1:nr_samples\n y[:,k] .= ReactiveMP.forward(model, x[:,k])\n end\n\n # return data\n return y, x\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# generate data\ny, x = generate_data(1000, compiled_model)\n\n# plot generated data\np1 = scatter(x[1,:], x[2,:], alpha=0.3, title=\"Original data\", size=(800,400))\np2 = scatter(y[1,:], y[2,:], alpha=0.3, title=\"Transformed data\", size=(800,400))\nplot(p1, p2, legend = false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The probabilistic model for doing inference can be described as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network(nr_samples::Int64)\n \n # initialize variables\n z_μ = randomvar()\n z_Λ = randomvar()\n x = randomvar(nr_samples)\n y_lat = randomvar(nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n\n # specify prior\n z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))\n z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)\n\n # specify transformed latent value\n y_lat[k] ~ Flow(x[k])\n\n # specify observations\n y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))\n\n end\n\n # return variables\n return z_μ, z_Λ, x, y_lat, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here the model is passed inside a meta data object of the flow node. Inference then resorts to","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"observations = [y[:,k] for k=1:size(y,2)]\n\nfmodel = invertible_neural_network(length(observations))\ndata = (y = observations, )\ninitmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))\nreturnvars = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())\n\nconstraints = @constraints begin\n q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)\nend\n\n@meta function fmeta(model)\n compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))\n Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). \n # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))\nend\n\n# First execution is slow due to Julia's initial compilation \nresult = infer(\n model = fmodel, \n data = data,\n constraints = constraints,\n meta = fmeta(model),\n initmarginals = initmarginals,\n returnvars = returnvars,\n free_energy = true,\n iterations = 10, \n showprogress = false\n)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Inference results:\n Posteriors | available for (z_μ, z_Λ, y_lat, x)\n Free Energy: | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357\n0.6, 23570.6, 23570.6, 23570.6, 23570.6]","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fe_flow = result.free_energy\nzμ_flow = result.posteriors[:z_μ]\nzΛ_flow = result.posteriors[:z_Λ]\nx_flow = result.posteriors[:x]\ny_flow = result.posteriors[:y_lat];","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"As we can see, the variational free energy decreases inside of our model.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"plot(1:10, fe_flow/size(y,2), xlabel=\"iteration\", ylabel=\"normalized variational free energy [nats/sample]\", legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"If we plot a random noisy observation and its approximated transformed uncertainty we obtain:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# pick a random observation\nid = rand(StableRNG(321), 1:size(y,2))\nrand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))\nwarped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');\n\np1 = scatter(x[1,:], x[2,:], alpha=0.1, title=\"Latent distribution\", size=(1200,500), label=\"generated data\")\ncontour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)\nscatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color=\"red\", markershape=:x, markersize=5, label=\"inferred mean\")\ncontour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, colorbar=false)\nscatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color=\"red\", label=\"transformed noisy observation\")\np2 = scatter(y[1,:], y[2,:], alpha=0.1, label=\"generated data\")\nscatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color=\"red\", marker=:x, label=\"inferred mean\")\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, label=\"random noisy observation\", colorba=false)\nscatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color=\"red\", label=\"random noisy observation\")\nplot(p1, p2, legend = true)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Parameter-estimation","page":"Invertible neural networks: a tutorial","title":"Parameter estimation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n\n # sample weights\n w = rand(rng, nr_samples, 2)\n\n # sample appraisal\n y = zeros(Float64, nr_samples)\n for k = 1:nr_samples\n y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)\n end\n\n # return data\n return y, w\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"data_y, data_x = generate_data(50);\nscatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel=\"w1\", ylabel=\"w2\", colorbar=false, legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We will then specify a possible model as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# specify flow model\nmodel = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The corresponding probabilistic model for the binary classification task can be created as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network_classifier(nr_samples::Int64)\n \n # initialize variables\n x_lat = randomvar(nr_samples)\n y_lat1 = randomvar(nr_samples)\n y_lat2 = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n x = datavar(Vector{Float64}, nr_samples)\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))\n\n # specify transformed latent value\n y_lat1[k] ~ Flow(x_lat[k])\n y_lat2[k] ~ dot(y_lat1[k], [1, 1])\n\n # specify observations\n y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }\n\n end\n\n # return variables\n return x_lat, x, y_lat1, y_lat2, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fcmodel = invertible_neural_network_classifier(length(data_y))\ndata = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )\n\n@meta function fmeta(model, params)\n compiled_model = compile(model, params)\n Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)\nend","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fmeta (generic function with 2 methods)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function f(params)\n Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure\n result = infer(\n model = fcmodel, \n data = data,\n meta = fmeta(model, params),\n free_energy = true,\n free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure\n iterations = 10, \n showprogress = false\n );\n \n result.free_energy[end]\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"uses finitediff and is slower/less accurate.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"or","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# create gradient function\ng = (x) -> ForwardDiff.gradient(f, x);\n\n# specify initial params\nparams = randn(nr_params(model))\n\n# create custom optimizer (here Adam)\noptimizer = Adam(params; λ=1e-1)\n\n# allocate space for gradient\n∇ = zeros(nr_params(model))\n\n# perform optimization\nfor it = 1:10000\n\n # backward pass\n ∇ .= ForwardDiff.gradient(f, optimizer.x)\n\n # gradient update\n ReactiveMP.update!(optimizer, ∇)\n\nend\n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Iter Function value Gradient norm \n 0 5.888958e+02 8.943663e+02\n * time: 5.91278076171875e-5\n 100 1.059826e+01 4.120090e+00\n * time: 11.980152130126953\n * Status: success\n\n * Candidate solution\n Final objective value: 1.010332e+01\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.21e-03 ≰ 0.0e+00\n |x - x'|/|x'| = 5.80e-04 ≰ 0.0e+00\n |f(x) - f(x')| = 6.28e-03 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03\n |g(x)| = 2.07e+00 ≰ 1.0e-08\n\n * Work counters\n Seconds run: 14 (vs limit Inf)\n Iterations: 113\n f(x) calls: 301\n ∇f(x) calls: 301","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"optimization results are then given as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"params = Optim.minimizer(res)\ninferred_model = compile(model, params)\ntrans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'\ntrans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])\ntrans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title=\"original data\")\np2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title=\"|> warp\")\np3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title=\"|> dot\")\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using StatsFuns: normcdf\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title=\"original labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title=\"predicted labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title=\"Classification map\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"contributing/new-example/#contributing-new-example","page":"Contributing to the examples","title":"Contributing to the examples","text":"","category":"section"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/\"subcategory\" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"After preparing the new example it is necessary to modify the examples/.meta.jl file.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"Make sure that the very first cell of the notebook contains ONLY # in it and has the markdown cell type. This is important for generating links in our documentation.\nThe path option must be set to a local path in a category sub-folder.\nThe text in the description option will be used on the Examples page in the documentation.\nSet category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).\nPlease do no use Overview as a name for the new example, the title Overview is reserved.\nUse the following template for equations, note that $$ and both \\begin and \\end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"$$\\begin{aligned}\n <latex equations here>\n\\end{aligned}$$","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.\nNotebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"variable = 0\nfor i in 1:10\n global variable = variable + i\nend","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.\nAll plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nPlease avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nUse make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.","category":"page"},{"location":"library/model-specification/#lib-model-specification","page":"Model specification","title":"Model specification in RxInfer","text":"","category":"section"},{"location":"library/model-specification/","page":"Model specification","title":"Model specification","text":"RxInfer.@model\nRxInfer.ModelGenerator\nRxInfer.create_model\nRxInfer.ModelInferenceOptions","category":"page"},{"location":"library/model-specification/#RxInfer.@model","page":"Model specification","title":"RxInfer.@model","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model description\nend\n\n@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.\n\nSupported alias in the model specification\n\na || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).\na && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\na -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\n¬a and !a: alias for NOT(a) node (Unicode \\neg, operator precedence ||, &&, -> and ! is the same as in Julia).\na + b + c: alias for (a + b) + c\na * b * c: alias for (a * b) * c\nNormal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.\nNormal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.\nMvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nGamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.\nGamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.\n\n\n\n\n\n","category":"macro"},{"location":"library/model-specification/#RxInfer.ModelGenerator","page":"Model specification","title":"RxInfer.ModelGenerator","text":"ModelGenerator\n\nModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"library/model-specification/#RxInfer.create_model","page":"Model specification","title":"RxInfer.create_model","text":"create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)\n\nCreates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.\n\nReturns a tuple of 2 values:\n\nan instance of FactorGraphModel\nreturn value from the @model macro function definition\n\n\n\n\n\n","category":"function"},{"location":"library/model-specification/#RxInfer.ModelInferenceOptions","page":"Model specification","title":"RxInfer.ModelInferenceOptions","text":"ModelInferenceOptions(; kwargs...)\n\nCreates model inference options object. The list of available options is present below.\n\nOptions\n\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\nwarn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.\n\nAdvanced options\n\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/getting-started/#user-guide-getting-started","page":"Getting started","title":"Getting started","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.","category":"page"},{"location":"manuals/getting-started/#Installation","page":"Getting started","title":"Installation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Install RxInfer through the Julia package manager:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"] add RxInfer","category":"page"},{"location":"manuals/getting-started/#Importing-RxInfer","page":"Getting started","title":"Importing RxInfer","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"To add RxInfer package (and all associated packages) into a running Julia session simply run:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more about about using in the Using methods from RxInfer section of the documentation.","category":"page"},{"location":"manuals/getting-started/#Example:-Inferring-the-bias-of-a-coin","page":"Getting started","title":"Example: Inferring the bias of a coin","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The RxInfer approach to solving inference problems consists of three phases:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.\nInference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.\nInference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.","category":"page"},{"location":"manuals/getting-started/#Coin-flip-simulation","page":"Getting started","title":"Coin flip simulation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"First let's setup our environment by importing all needed packages:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Next, let's define our dataset:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"rng = MersenneTwister(42)\nn = 10\np = 0.75\ndistribution = Bernoulli(p)\n\ndataset = float.(rand(rng, Bernoulli(p), n))","category":"page"},{"location":"manuals/getting-started/#getting-started-model-specification","page":"Getting started","title":"Model specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In 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.","category":"page"},{"location":"manuals/getting-started/#Likelihood","page":"Getting started","title":"Likelihood","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"y_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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 01.","category":"page"},{"location":"manuals/getting-started/#Prior","page":"Getting started","title":"Prior","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"theta sim Beta(a b)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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. ","category":"page"},{"location":"manuals/getting-started/#Joint-probability","page":"Getting started","title":"Joint probability","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The joint probability is given by the multiplication of the likelihood and the prior, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"P(y_1N θ) = P(θ) prod_i=1^N P(y_i θ)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Now let's see how to specify this model using GraphPPL's package syntax.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"\n# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n \n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during inference step\n return y, θ\nend\n","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create \"clamped\" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG. ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-specification","page":"Getting started","title":"Inference specification","text":"","category":"section"},{"location":"manuals/getting-started/#Automatic-inference-specification","page":"Getting started","title":"Automatic inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Once 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 inference function that supports static datasets.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"result = infer(\n model = coin_model(length(dataset)),\n data = (y = dataset, )\n)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more information about the inference function in the Static Inference documentation section.","category":"page"},{"location":"manuals/getting-started/#Manual-inference-specification","page":"Getting started","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Return variables of interests from model specification\nSubscribe on variables of interests posterior marginal updates\nPass data to the model\nUnsubscribe ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here is an example of inference procedure:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"function custom_inference(data)\n n = length(data)\n\n # `coin_model` function from `@model` macro returns a reference to the model generator object\n # we need to use the `create_model` function to get actual model object\n model, (y, θ) = create_model(coin_model(n))\n \n # Reference for future posterior marginal \n mθ = nothing\n\n # `getmarginal` function returns an observable of future posterior marginal updates\n # We use `Rocket.jl` API to subscribe on this observable\n # As soon as posterior marginal update is available we just save it in `mθ`\n subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)\n \n # `update!` function passes data to our data inputs\n update!(y, data)\n \n # It is always a good practice to unsubscribe and to \n # free computer resources held by the subscription\n unsubscribe!(subscription)\n \n # Here we return our resulting posterior marginal\n return mθ\nend","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-execution","page":"Getting started","title":"Inference execution","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = custom_inference(dataset)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title=\"Prior\", fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\np2 = plot(rθ, (x) -> pdf(θestimated, x), title=\"Posterior\", fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"dataset_100 = float.(rand(rng, Bernoulli(p), 100))\ndataset_1000 = float.(rand(rng, Bernoulli(p), 1000))\ndataset_10000 = float.(rand(rng, Bernoulli(p), 10000))\nnothing # hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated_100 = custom_inference(dataset_100)\nθestimated_1000 = custom_inference(dataset_1000)\nθestimated_10000 = custom_inference(dataset_10000)\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"p3 = plot(title = \"Posterior\", legend = :topleft)\n\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_100)\", c = 4)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_1000)\", c = 5)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_10000)\", c = 6)\n\nplot(p1, p3, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated_10000))\nprintln(\"std: \", std(θestimated_10000))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/#Where-to-go-next?","page":"Getting started","title":"Where to go next?","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.","category":"page"},{"location":"manuals/debugging/#user-guide-debugging","page":"Debugging","title":"Debugging","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want. ","category":"page"},{"location":"manuals/debugging/#Requesting-a-trace-of-messages","page":"Debugging","title":"Requesting a trace of messages","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a \"Memory Addon\". Below is an example explaining how you can extract this history and use it to fix a bug.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Consider the coin toss example from earlier in the documentation. We model the binary outcome x (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the theta parameter, with a known shape 𝑎 and rate 𝑏 parameter.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"x_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"theta sim mathrmBeta(a b)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"where x_i in 0 1 are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"using RxInfer, Random, Plots\n\nn = 4\nθ_real = 0.3\ndataset = convert.(Int64, rand(Bernoulli(θ_real), n))\n\n@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, huge)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);\n","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The model will run without errors. But when we plot the posterior distribution for theta, something's wrong. The posterior seems to be a flat distribution:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"\nrθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n addons = (AddonMemory(),)\n)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now we have access to the messages that led to the marginal posterior:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"underbraceoverrightarrowmu_θ(θ)_substack textoutgoing textmessage = sum_x_1ldotsx_n underbraceoverrightarrowmu_X_1(x_1)cdots overrightarrowmu_X_n(x_n)_substacktextincoming textmessages cdot underbracef(θx_1ldotsx_n)_substacktextnode textfunction","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Graph)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of theta we used in the code block above. So why does the posterior have this rate parameter?","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, 100)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"rθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now the posterior is visible in the plot.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#examples-active-inference-mountain-car","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#The-environmental-process-of-the-mountain","page":"Active Inference Mountain car","title":"The environmental process of the mountain","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Firstly, we specify the environmental process according to Ueltzhoeffer (2017) \"Deep active inference\". This process shows how the environment evolves after interacting with the agent.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Particularly, let's denote z_t = (phi_t dotphi_t) as the environmental state depending on the position phi_t and velocity dotphi_t of the car; a_t as the action of the environment on the car. Then the evolution of the state is described as follows ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndotphi_t = dotphi_t-1 + F_g(phi_t-1) + F_f(dotphi_t-1) + F_a(a_t)\nphi_t = phi_t-1 + dotphi_t \nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where F_g(phi_t-1) is the gravitational force of the hill landscape that depends on the car's position","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_g(phi) = begincases\n -005(2phi + 1) mathrmif phi 0 \n -005 left(1 + 5phi^2)^-frac12 + phi^2 (1 + 5phi^2)^-frac32 + frac116phi^4 right mathrmotherwise\nendcases","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_f(dotphi)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"is the friction on the car defined through the car's velocity F_f(dotphi) = -01 dotphi and F_a(a) is the engine force F_a(a) = 004 tanh(a) Since the car is on low battery, we use the tanh(cdot) function to limit the engine force to the interval [-0.04, 0.04].","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the create_physics function defines forces F_g F_f F_a; and the create_world function defines the environmental process of the mountain.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import HypergeometricFunctions: _₂F₁\n\nfunction create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)\n # Engine force as function of action\n Fa = (a::Real) -> engine_force_limit * tanh(a) \n\n # Friction force as function of velocity\n Ff = (y_dot::Real) -> -friction_coefficient * y_dot \n \n # Gravitational force (horizontal component) as function of position\n Fg = (y::Real) -> begin\n if y < 0\n 0.05*(-2*y - 1)\n else\n 0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)\n end\n end\n \n # The height of the landscape as a function of the horizontal coordinate\n height = (x::Float64) -> begin\n if x < 0\n h = x^2 + x\n else\n h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80\n end\n return 0.05*h\n end\n\n return (Fa, Ff, Fg,height)\nend;\n\nfunction create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)\n\n y_t_min = initial_position\n y_dot_t_min = initial_velocity\n \n y_t = y_t_min\n y_dot_t = y_dot_t_min\n \n execute = (a_t::Float64) -> begin\n # Compute next state\n y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)\n y_t = y_t_min + y_dot_t\n \n # Reset state for next step\n y_t_min = y_t\n y_dot_t_min = y_dot_t\n end\n \n observe = () -> begin \n return [y_t, y_dot_t]\n end\n \n return (execute, observe)\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_world (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Let's visualize the mountain landscape and the situation of the car. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"engine_force_limit = 0.04\nfriction_coefficient = 0.1\n\nFa, Ff, Fg, height = create_physics(\n engine_force_limit = engine_force_limit,\n friction_coefficient = friction_coefficient\n);\ninitial_position = -0.5\ninitial_velocity = 0.0\n\nx_target = [0.5, 0.0] \n\nvalley_x = range(-2, 2, length=400)\nvalley_y = [ height(xs) for xs in valley_x ]\nplot(valley_x, valley_y, title = \"Mountain valley\", label = \"Landscape\", color = \"black\")\nscatter!([ initial_position ], [ height(initial_position) ], label=\"initial car position\") \nscatter!([x_target[1]], [height(x_target[1])], label=\"camping site\")","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Naive-approach","page":"Active Inference Mountain car","title":"Naive approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"N_naive = 100 # Total simulation time\npi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only\n\n# Let there be a world\n(execute_naive, observe_naive) = create_world(; \n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n);\n\ny_naive = Vector{Vector{Float64}}(undef, N_naive)\nfor t = 1:N_naive\n execute_naive(pi_naive[t]) # Execute environmental process\n y_naive[t] = observe_naive() # Observe external states\nend\n\nanimation_naive = @animate for i in 1:N_naive\n plot(valley_x, valley_y, title = \"Naive policy\", label = \"Landscape\", color = \"black\", size = (800, 400))\n scatter!([y_naive[i][1]], [height(y_naive[i][1])], label=\"car\")\n scatter!([x_target[1]], [height(x_target[1])], label=\"goal\") \nend\n\n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_naive, \"../pics/ai-mountain-car-naive.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Active-inference-approach","page":"Active Inference Mountain car","title":"Active inference approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned\np_t(xsu) propto p(s_t-1) prod_k=t^t+T p(x_k mid s_k) p(s_k mid s_k-1u_k) p(u_k) p(x_k) nonumber\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where the factors are defined as","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k) = mathcalN(x_k mid x_goalV_goal) quad (mathrmtarget)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_k mid s_k-1u_k) = mathcalN(s_k mid tildeg(s_k-1)+h(u_k)gamma^-1) quad (mathrmstate transition)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k mid s_k) = mathcalN(x_k mid s_ktheta) quad (mathrmobservation)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(u_k) = mathcalN(u_k mid m_uV_u) quad (mathrmcontrol)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_t-1) = mathcalN(s_t-1 mid m_t-1V_t-1) quad (mathrmprevious state)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"x\ndenotes observations of the agent after interacting with the environment; \ns_t = (s_tdots_t)\nis the state of the car embodying its position and velocity; \nu_t\ndenotes the control state of the agent; \nh(cdot)\nis the tanh(cdot) function modeling engine control; \ntildeg(cdot)\nexecutes a linear approximation of equations (1) and (2): ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndots_t = dots_t-1 + F_g(s_t-1) + F_f(dots_t-1)\ns_t = s_t-1 + dots_t\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)\n \n # Transition function modeling transition due to gravity and friction\n g = (s_t_min::AbstractVector) -> begin \n s_t = similar(s_t_min) # Next state\n s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity\n s_t[1] = s_t_min[1] + s_t[2] # Update position\n return s_t\n end\n \n # Function for modeling engine control\n h = (u::AbstractVector) -> [0.0, Fa(u[1])] \n \n # Inverse engine force, from change in state to corresponding engine force\n h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] \n \n # Internal model perameters\n Gamma = 1e4*diageye(2) # Transition precision\n Theta = 1e-4*diageye(2) # Observation variance\n \n m_s_t_min = datavar(Vector{Float64})\n V_s_t_min = datavar(Matrix{Float64})\n\n s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)\n s_k_min = s_t_min\n \n m_u = datavar(Vector{Float64}, T)\n V_u = datavar(Matrix{Float64}, T)\n \n m_x = datavar(Vector{Float64}, T)\n V_x = datavar(Matrix{Float64}, T)\n \n u = randomvar(T)\n s = randomvar(T)\n x = randomvar(T)\n \n u_h_k = randomvar(T)\n s_g_k = randomvar(T)\n u_s_sum = randomvar(T)\n \n for k in 1:T\n u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])\n u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }\n s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }\n u_s_sum[k] ~ s_g_k[k] + u_h_k[k]\n s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)\n x[k] ~ MvNormal(mean = s[k], cov = Theta)\n x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal\n s_k_min = s[k]\n end\n \n return (s, )\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time t and gets T observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next T time step. \nInfer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state s_t and control u_t, i.e. p(s_tmid x_t) and p(u_tmid x_t).\nSlide: After updating its internal belief, the agent moves to the next time step and uses the inferred action u_t in the previous time step to interact with the environment. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next T positions based on the current action. These two function implement the Act-Execute-Observe phase.\nThe compute function infers the policy (which is a set of actions for the next T time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.\nThe slide function implements the Slide phase, which moves the agent internal model to the next time step.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"# We are going to use some private functionality from ReactiveMP, \n# in the future we should expose a proper API for this\nimport RxInfer.ReactiveMP: getrecent, messageout\n\nfunction create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)\n Epsilon = fill(huge, 1, 1) # Control prior variance\n m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors\n V_u = Matrix{Float64}[ Epsilon for k=1:T ]\n\n Sigma = 1e-4*diageye(2) # Goal prior variance\n m_x = [zeros(2) for k=1:T]\n V_x = [huge*diageye(2) for k=1:T]\n V_x[end] = Sigma # Set prior to reach goal at t=T\n\n # Set initial brain state prior\n m_s_t_min = [initial_position, initial_velocity] \n V_s_t_min = tiny * diageye(2)\n \n # Set current inference results\n result = nothing\n\n # The `infer` function is the heart of the agent\n # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing\n compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin\n m_u[1] = [ upsilon_t ] # Register action with the generative model\n V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action\n\n m_x[1] = y_hat_t # Register observation with the generative model\n V_x[1] = tiny*diageye(2) # Clamp goal prior to observation\n\n data = Dict(:m_u => m_u, \n :V_u => V_u, \n :m_x => m_x, \n :V_x => V_x,\n :m_s_t_min => m_s_t_min,\n :V_s_t_min => V_s_t_min)\n \n model = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) \n result = infer(model = model, data = data)\n end\n \n # The `act` function returns the inferred best possible action\n act = () -> begin\n if result !== nothing\n return mode(result.posteriors[:u][2])[1]\n else\n return 0.0 # Without inference result we return some 'random' action\n end\n end\n \n # The `future` function returns the inferred future states\n future = () -> begin \n if result !== nothing \n return getindex.(mode.(result.posteriors[:s]), 1)\n else\n return zeros(T)\n end\n end\n\n # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step\n # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`\n slide = () -> begin\n (s, ) = result.returnval\n \n slide_msg_idx = 3 # This index is model dependend\n (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))\n\n m_u = circshift(m_u, -1)\n m_u[end] = [0.0]\n V_u = circshift(V_u, -1)\n V_u[end] = Epsilon\n\n m_x = circshift(m_x, -1)\n m_x[end] = x_target\n V_x = circshift(V_x, -1)\n V_x[end] = Sigma\n end\n\n return (compute, act, slide, future) \nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_agent (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now it's time to see if we can help our friends arrive at the camping site by midnight?","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(execute_ai, observe_ai) = create_world(\n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n) # Let there be a world\n\nT_ai = 50\n\n(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent\n T = T_ai, \n Fa = Fa,\n Fg = Fg, \n Ff = Ff, \n engine_force_limit = engine_force_limit,\n x_target = x_target,\n initial_position = initial_position,\n initial_velocity = initial_velocity\n) \n\nN_ai = 100\n\n# Step through experimental protocol\nagent_a = Vector{Float64}(undef, N_ai) # Actions\nagent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future\nagent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations\n\nfor t=1:N_ai\n agent_a[t] = act_ai() # Invoke an action from the agent\n agent_f[t] = future_ai() # Fetch the predicted future states\n execute_ai(agent_a[t]) # The action influences hidden external states\n agent_x[t] = observe_ai() # Observe the current environmental outcome (update p)\n compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)\n slide_ai() # Prepare for next iteration\nend\n\nanimation_ai = @animate for i in 1:N_ai\n # pls - plot landscape\n pls = plot(valley_x, valley_y, title = \"Active inference results\", label = \"Landscape\", color = \"black\")\n pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label=\"car\")\n pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label=\"goal\") \n pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = \"Predicted future\", alpha = map(i -> 0.5 / i, 1:T_ai))\n \n # pef - plot engine force\n pef = plot(Fa.(agent_a[1:i]), title = \"Engine force (agents actions)\", xlim = (0, N_ai), ylim = (-0.05, 0.05))\n \n plot(pls, pef, size = (800, 400))\nend\n \n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_ai, \"../pics/ai-mountain-car-ai.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Voila! The car now is able to reach the camping site with a smart strategy.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now our friends can enjoy their trip at the camping site!. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Reference","page":"Active Inference Mountain car","title":"Reference","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We refer reader to the Thijs van de Laar (2019) \"Simulating active inference processes by message passing\" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) \"Deep active inference\".","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-free-energy","page":"Bethe Free Energy","title":"Bethe Free Energy implementation in RxInfer","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-factorized-model","page":"Bethe Free Energy","title":"Factorized model","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, y = (y_1 dots y_j dots y_m) and variables that can not be observed directly, also known as latent variables, x = (x_1 dots x_i dots x_n) We then define a model that factorizes over consituent smaller factors (functions), as f(yx) = prod_a f_a(y_ax_a)","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-vfe","page":"Bethe Free Energy","title":"Variational Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, Fq(haty) = mathbbE_q(x)leftlog fracq(x)f(y=haty x) right A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-variational-inference","page":"Bethe Free Energy","title":"Variational inference","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The goal of variational inference is to find a variational distibution that minimizes the VFE, q^*(x) = argmin_qinmathcalQ Fq(haty) This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-approximation","page":"Bethe Free Energy","title":"Bethe approximation","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, q(x) triangleq fracprod_a q_a(x_a)prod_i q_i(x_i)^d_i - 1 The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-bfe","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as F_Bq(haty) = sum_a U_aq_a(haty_a) - sum_a Hq_a + sum_i (d_i - 1) Hq_i The first term of the BFE specifies an average energy, U_aq_a(haty_a) = -mathbbE_q_a(x_a)leftlog f_a(y_a=haty_a x_a)right which internalizes the factors of the model. The last two terms specify entropies.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-further-reading","page":"Bethe Free Energy","title":"Further reading","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Pearl (1986) on the original foundations of Bayesian networks and belief propagation;\nYedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;\nDauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);\nSenoz et al. (2021) on constraint manipulation and message passing on FFGs.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"RxInfer.AbstractScoreObjective\nRxInfer.BetheFreeEnergy\nRxInfer.apply_diagnostic_check\nRxInfer.BetheFreeEnergyCheckNaNs\nRxInfer.BetheFreeEnergyCheckInfs","category":"page"},{"location":"library/bethe-free-energy/#RxInfer.AbstractScoreObjective","page":"Bethe Free Energy","title":"RxInfer.AbstractScoreObjective","text":"AbstractScoreObjective\n\nAbstract type for functional objectives that can be used in the score function. \n\nnote: Note\n\n\nscore is defined in the ReactiveMP package.\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergy","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergy","text":"BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)\n\nCreates Bethe Free Energy values stream when passed to the score function. \n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.apply_diagnostic_check","page":"Bethe Free Energy","title":"RxInfer.apply_diagnostic_check","text":"apply_diagnostic_check(check, context, stream)\n\nThis function applies a check to the stream. Accepts optional context object for custom error messages.\n\n\n\n\n\n","category":"function"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckNaNs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckNaNs","text":"BetheFreeEnergyCheckNaNs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return NaNs. Throws an error if finds NaN. \n\nSee also: BetheFreeEnergyCheckInfs\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckInfs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckInfs","text":"BetheFreeEnergyCheckInfs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return Infs. Throws an error if finds Inf. \n\nSee also: BetheFreeEnergyCheckNaNs\n\n\n\n\n\n","category":"type"},{"location":"manuals/background/#intro-background-variational-inference","page":"Background: variational inference","title":"Background: variational inference","text":"","category":"section"}] +} diff --git a/v2.16.0/siteinfo.js b/v2.16.0/siteinfo.js new file mode 100644 index 000000000..401d11097 --- /dev/null +++ b/v2.16.0/siteinfo.js @@ -0,0 +1 @@ +var DOCUMENTER_CURRENT_VERSION = "v2.16.0"; diff --git a/v2.16.1/.documenter-siteinfo.json b/v2.16.1/.documenter-siteinfo.json new file mode 100644 index 000000000..a1c09c8ef --- /dev/null +++ b/v2.16.1/.documenter-siteinfo.json @@ -0,0 +1 @@ +{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2024-01-25T11:32:30","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/v2.16.1/assets/biglogo-blacktheme.svg b/v2.16.1/assets/biglogo-blacktheme.svg new file mode 100644 index 000000000..101ebb89d --- /dev/null +++ b/v2.16.1/assets/biglogo-blacktheme.svg @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 27.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) --> +<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" + viewBox="0 0 642.5 213.6" style="enable-background:new 0 0 642.5 213.6;" xml:space="preserve"> +<style type="text/css"> + .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFFFFF;stroke-miterlimit:10;} + .st1{fill:#389826;} + .st2{fill:#9558B2;} + .st3{fill:#FFFFFF;stroke:#FFFFFF;stroke-miterlimit:10;} + .st4{fill:#CB3C33;} + .st5{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFE9E9;stroke-miterlimit:10;} + .st6{fill-rule:evenodd;clip-rule:evenodd;fill:#4063D8;stroke:#FFFFFF;stroke-miterlimit:10;} +</style> +<g id="Слой_2"> + <g id="Layer_1_00000116955105323099935610000000039006590443086520_"> + <path class="st0" d="M66.6,114.5h63c6.7-0.3,12-5.8,12-12.5c0-14.1,0.3-27.6,0.3-41.5c0-6.3,5.1-11.4,11.3-11.4h40.1 + c6.3,0,11.4,5.1,11.4,11.4v40.1c0,6.3-5.1,11.4-11.4,11.4h-35.1c-6.2,0.9-10.8,6.2-10.8,12.4v70.9c0,9.8-8,17.8-17.9,17.8H66.6 + c-9.8,0-17.8-8-17.8-17.8V130c0-6.8-5.5-12.2-12.3-12.2H9.2c-4.8,0-8.7-3.9-8.7-8.7V78.2c0-4.8,3.9-8.7,8.7-8.7h28.7 + c6,0,10.8-4.8,10.8-10.8V13c0-6.9,5.6-12.5,12.5-12.5h44c6.9,0,12.5,5.6,12.5,12.5v44c0,6.9-5.6,12.5-12.5,12.5H59.6 + c-6,0-10.8,4.8-10.8,10.8v22c0,6.7,5.5,12.2,12.2,12.2H66.6z"/> + <rect x="62" y="13.8" class="st1" width="42.3" height="42.3"/> + <rect x="155.2" y="62.4" class="st2" width="36.2" height="36.2"/> + <rect x="13.7" y="82.8" class="st3" width="21.7" height="21.7"/> + <rect x="62" y="127.7" class="st4" width="72" height="72"/> + <path class="st5" d="M213.7,130.1c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.1-9.6,10.4-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.1,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C223.6,131.6,219,130.1,213.7,130.1z"/> + <polygon class="st0" points="281.9,165.8 306.4,130.8 294,130.8 276.2,156.7 260.4,130.8 232.2,130.8 259.8,175.5 234.7,211.6 + 247.2,211.6 265.4,184.8 281.9,211.6 310,211.6 "/> + <polygon class="st0" points="342.1,211.6 342.1,130 315.8,134.3 315.8,211.6 "/> + <path class="st6" d="M329.3,124.6c3.7,0.1,7.2-1.3,9.8-3.9c2.6-2.7,4-6.3,3.9-10.1c0.1-3.7-1.3-7.3-3.9-9.9s-6.1-4.1-9.8-4 + c-3.9-0.1-7.6,1.3-10.4,4c-2.7,2.6-4.2,6.2-4.1,9.9c-0.1,3.8,1.4,7.5,4.1,10.1C321.7,123.3,325.6,124.8,329.3,124.6z"/> + <path class="st0" d="M405.2,129.3c-5.7-0.1-11.3,1.4-16.3,4.1c-4.8,2.5-8.8,6.3-11.7,10.9V130l-26.3,4.3v77.3h26.3v-55.4 + c3.6-8.1,10.4-13.3,17.6-13.3c6.6,0,11.5,5.2,11.5,12.5v56.2h26.3v-55.7c0.2-7.2-2.6-14.1-7.8-19 + C419.6,131.9,413.1,129.4,405.2,129.3z"/> + <path class="st0" d="M479.3,93.6c-9.7,0-17.8,2.8-24.3,8.3s-9.8,12.5-9.8,20.7v8.2h-9.4v8.7h9.4v72.1h26.3v-72.1h16.4v-8.7h-16.4 + v-10.3c-0.2-4.3,1.3-8.5,4.1-11.8c2.7-3.1,6.6-4.9,10.6-5c-1.4,1.9-2.1,4.2-2.1,6.6c0,2.9,1.2,5.7,3.4,7.7 + c2.2,2.1,5.1,3.3,8.1,3.2c2.8,0.1,5.6-1.1,7.6-3.1s3.2-4.8,3.1-7.7c0-4.7-2.6-8.7-7.7-11.9S487,93.6,479.3,93.6z"/> + <path class="st0" d="M527.9,129.4v8.6l0,0V129.4L527.9,129.4z"/> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M527.3,129.3c-11.7,0.2-21.6,4.2-29.7,12c-8.3,7.9-12.6,17.9-12.6,29.8c-0.2,11.4,4.6,22.4,13.2,29.9 + c7.9,7.3,17.9,11.3,29.8,12v-0.1c1.2,0.1,2.5,0.1,3.7,0.1c9.9,0,18.4-2.1,25.4-6.4s10.5-9.5,10.5-15.7c0.1-3-1.1-6-3.2-8.2 + c-2-2.2-4.9-3.3-7.9-3.3c-3.2-0.1-6.2,1.1-8.5,3.3c-2.3,2.1-3.6,5.1-3.6,8.2c-0.1,3.9,1.9,7.6,5.4,9.5c-3.3,1.5-6.9,2.3-10.5,2.2 + c-3.9,0.1-7.8-0.6-11.4-2l0,0c-9.9-3.9-15.2-13.8-16-29.5h55.9c0-12-3.8-22-11.4-29.9c-7.6-8-17.2-11.9-28.8-11.9L527.3,129.3 + M527.9,138c8.5,0.1,14.2,9.1,15.1,24.4h-15.7l0,0h-15.1c0.6-7.3,2.4-13.2,5.3-17.7C520.3,140.5,523.8,138.2,527.9,138L527.9,138" + /> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M623.6,129.4c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.2-9.6,10.3-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.2,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C633.4,130.9,629,129.4,623.6,129.4z"/> + </g> +</g> +<g id="Layer_2_00000036966862148631286250000015780344526604021166_"> +</g> +</svg> diff --git a/v2.16.1/assets/biglogo.svg b/v2.16.1/assets/biglogo.svg new file mode 100644 index 000000000..b9f3d9f8e --- /dev/null +++ b/v2.16.1/assets/biglogo.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 641.51 212.57"><defs><style>.cls-1{fill:#333;}.cls-1,.cls-6{fill-rule:evenodd;}.cls-2{fill:#389826;}.cls-3{fill:#9558b2;}.cls-4{fill:#fff;}.cls-5{fill:#cb3c33;}.cls-6{fill:#4063d8;}</style></defs><title>1 \ No newline at end of file diff --git a/v2.16.1/assets/documenter.js b/v2.16.1/assets/documenter.js new file mode 100644 index 000000000..f5311607b --- /dev/null +++ b/v2.16.1/assets/documenter.js @@ -0,0 +1,889 @@ +// Generated by Documenter.jl +requirejs.config({ + paths: { + 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', + 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', + 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', + 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', + 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', + 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', + 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', + 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min', + 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min', + 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia-repl.min', + }, + shim: { + "highlight-julia": { + "deps": [ + "highlight" + ] + }, + "katex-auto-render": { + "deps": [ + "katex" + ] + }, + "headroom-jquery": { + "deps": [ + "jquery", + "headroom" + ] + }, + "highlight-julia-repl": { + "deps": [ + "highlight" + ] + } +} +}); +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'katex', 'katex-auto-render'], function($, katex, renderMathInElement) { +$(document).ready(function() { + renderMathInElement( + document.body, + { + "delimiters": [ + { + "left": "$", + "right": "$", + "display": false + }, + { + "left": "$$", + "right": "$$", + "display": true + }, + { + "left": "\\[", + "right": "\\]", + "display": true + } + ] +} + + ); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'highlight', 'highlight-julia', 'highlight-julia-repl'], function($) { +$(document).ready(function() { + hljs.highlightAll(); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let timer = 0; +var isExpanded = true; + +$(document).on("click", ".docstring header", function () { + let articleToggleTitle = "Expand docstring"; + + debounce(() => { + if ($(this).siblings("section").is(":visible")) { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + } else { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + articleToggleTitle = "Collapse docstring"; + } + + $(this) + .find(".docstring-article-toggle-button") + .prop("title", articleToggleTitle); + $(this).siblings("section").slideToggle(); + }); +}); + +$(document).on("click", ".docs-article-toggle-button", function () { + let articleToggleTitle = "Expand docstring"; + let navArticleToggleTitle = "Expand all docstrings"; + + debounce(() => { + if (isExpanded) { + $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + + isExpanded = false; + + $(".docstring section").slideUp(); + } else { + $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + isExpanded = true; + articleToggleTitle = "Collapse docstring"; + navArticleToggleTitle = "Collapse all docstrings"; + + $(".docstring section").slideDown(); + } + + $(this).prop("title", navArticleToggleTitle); + $(".docstring-article-toggle-button").prop("title", articleToggleTitle); + }); +}); + +function debounce(callback, timeout = 300) { + if (Date.now() - timer > timeout) { + callback(); + } + + clearTimeout(timer); + + timer = Date.now(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require([], function() { +function addCopyButtonCallbacks() { + for (const el of document.getElementsByTagName("pre")) { + const button = document.createElement("button"); + button.classList.add("copy-button", "fa-solid", "fa-copy"); + button.setAttribute("aria-label", "Copy this code block"); + button.setAttribute("title", "Copy"); + + el.appendChild(button); + + const success = function () { + button.classList.add("success", "fa-check"); + button.classList.remove("fa-copy"); + }; + + const failure = function () { + button.classList.add("error", "fa-xmark"); + button.classList.remove("fa-copy"); + }; + + button.addEventListener("click", function () { + copyToClipboard(el.innerText).then(success, failure); + + setTimeout(function () { + button.classList.add("fa-copy"); + button.classList.remove("success", "fa-check", "fa-xmark"); + }, 5000); + }); + } +} + +function copyToClipboard(text) { + // clipboard API is only available in secure contexts + if (window.navigator && window.navigator.clipboard) { + return window.navigator.clipboard.writeText(text); + } else { + return new Promise(function (resolve, reject) { + try { + const el = document.createElement("textarea"); + el.textContent = text; + el.style.position = "fixed"; + el.style.opacity = 0; + document.body.appendChild(el); + el.select(); + document.execCommand("copy"); + + resolve(); + } catch (err) { + reject(err); + } finally { + document.body.removeChild(el); + } + }); + } +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addCopyButtonCallbacks); +} else { + addCopyButtonCallbacks(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'headroom', 'headroom-jquery'], function($, Headroom) { + +// Manages the top navigation bar (hides it when the user starts scrolling down on the +// mobile). +window.Headroom = Headroom; // work around buggy module loading? +$(document).ready(function () { + $("#documenter .docs-navbar").headroom({ + tolerance: { up: 10, down: 10 }, + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'minisearch'], function($, minisearch) { + +// In general, most search related things will have "search" as a prefix. +// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +let results = []; +let timer = undefined; + +let data = documenterSearchIndex["docs"].map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; +}); + +// list below is the lunr 2.1.3 list minus the intersect with names(Base) +// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) +// ideally we'd just filter the original list but it's not available as a variable +const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", +]); + +let index = new minisearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification + tokenize: (string) => string.split(/[\s\-\.]+/), + // options which will be applied during the search + searchOptions: { + boost: { title: 100 }, + fuzzy: 2, + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + tokenize: (string) => string.split(/[\s\-\.]+/), + }, +}); + +index.addAll(data); + +let filters = [...new Set(data.map((x) => x.category))]; +var modal_filters = make_modal_body_filters(filters); +var filter_results = []; + +$(document).on("keyup", ".documenter-search-input", function (event) { + // Adding a debounce to prevent disruptions from super-speed typing! + debounce(() => update_search(filter_results), 300); +}); + +$(document).on("click", ".search-filter", function () { + if ($(this).hasClass("search-filter-selected")) { + $(this).removeClass("search-filter-selected"); + } else { + $(this).addClass("search-filter-selected"); + } + + // Adding a debounce to prevent disruptions from crazy clicking! + debounce(() => get_filters(), 300); +}); + +/** + * A debounce function, takes a function and an optional timeout in milliseconds + * + * @function callback + * @param {number} timeout + */ +function debounce(callback, timeout = 300) { + clearTimeout(timer); + timer = setTimeout(callback, timeout); +} + +/** + * Make/Update the search component + * + * @param {string[]} selected_filters + */ +function update_search(selected_filters = []) { + let initial_search_body = ` +
Type something to get started!
+ `; + + let querystring = $(".documenter-search-input").val(); + + if (querystring.trim()) { + results = index.search(querystring, { + filter: (result) => { + // Filtering results + if (selected_filters.length === 0) { + return result.score >= 1; + } else { + return ( + result.score >= 1 && selected_filters.includes(result.category) + ); + } + }, + }); + + let search_result_container = ``; + let search_divider = `
`; + + if (results.length) { + let links = []; + let count = 0; + let search_results = ""; + + results.forEach(function (result) { + if (result.location) { + // Checking for duplication of results for the same page + if (!links.includes(result.location)) { + search_results += make_search_result(result, querystring); + count++; + } + + links.push(result.location); + } + }); + + let result_count = `
${count} result(s)
`; + + search_result_container = ` +
+ ${modal_filters} + ${search_divider} + ${result_count} +
+ ${search_results} +
+
+ `; + } else { + search_result_container = ` +
+ ${modal_filters} + ${search_divider} +
0 result(s)
+
+
No result found!
+ `; + } + + if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").removeClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(search_result_container); + } else { + filter_results = []; + modal_filters = make_modal_body_filters(filters, filter_results); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(initial_search_body); + } +} + +/** + * Make the modal filter html + * + * @param {string[]} filters + * @param {string[]} selected_filters + * @returns string + */ +function make_modal_body_filters(filters, selected_filters = []) { + let str = ``; + + filters.forEach((val) => { + if (selected_filters.includes(val)) { + str += `${val}`; + } else { + str += `${val}`; + } + }); + + let filter_html = ` +
+ Filters: + ${str} +
+ `; + + return filter_html; +} + +/** + * Make the result component given a minisearch result data object and the value of the search input as queryString. + * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ +function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } + + let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${result.title}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; +} + +/** + * Get selected filters, remake the filter html and lastly update the search modal + */ +function get_filters() { + let ele = $(".search-filters .search-filter-selected").get(); + filter_results = ele.map((x) => $(x).text().toLowerCase()); + modal_filters = make_modal_body_filters(filters, filter_results); + update_search(filter_results); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Modal settings dialog +$(document).ready(function () { + var settings = $("#documenter-settings"); + $("#documenter-settings-button").click(function () { + settings.toggleClass("is-active"); + }); + // Close the dialog if X is clicked + $("#documenter-settings button.delete").click(function () { + settings.removeClass("is-active"); + }); + // Close dialog if ESC is pressed + $(document).keyup(function (e) { + if (e.keyCode == 27) settings.removeClass("is-active"); + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let search_modal_header = ` +
+
+

+ + + + +

+
+
+ +
+
+`; + +let initial_search_body = ` +
Type something to get started!
+`; + +let search_modal_footer = ` +
+ + Ctrl + + / to search + + esc to close +
+`; + +$(document.body).append( + ` + + ` +); + +document.querySelector(".docs-search-query").addEventListener("click", () => { + openModal(); +}); + +document.querySelector(".close-search-modal").addEventListener("click", () => { + closeModal(); +}); + +$(document).on("click", ".search-result-link", function () { + closeModal(); +}); + +document.addEventListener("keydown", (event) => { + if ((event.ctrlKey || event.metaKey) && event.key === "/") { + openModal(); + } else if (event.key === "Escape") { + closeModal(); + } + + return false; +}); + +// Functions to open and close a modal +function openModal() { + let searchModal = document.querySelector("#search-modal"); + + searchModal.classList.add("is-active"); + document.querySelector(".documenter-search-input").focus(); +} + +function closeModal() { + let searchModal = document.querySelector("#search-modal"); + let initial_search_body = ` +
Type something to get started!
+ `; + + searchModal.classList.remove("is-active"); + document.querySelector(".documenter-search-input").blur(); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".documenter-search-input").val(""); + $(".search-modal-card-body").html(initial_search_body); +} + +document + .querySelector("#search-modal .modal-background") + .addEventListener("click", () => { + closeModal(); + }); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Manages the showing and hiding of the sidebar. +$(document).ready(function () { + var sidebar = $("#documenter > .docs-sidebar"); + var sidebar_button = $("#documenter-sidebar-button"); + sidebar_button.click(function (ev) { + ev.preventDefault(); + sidebar.toggleClass("visible"); + if (sidebar.hasClass("visible")) { + // Makes sure that the current menu item is visible in the sidebar. + $("#documenter .docs-menu a.is-active").focus(); + } + }); + $("#documenter > .docs-main").bind("click", function (ev) { + if ($(ev.target).is(sidebar_button)) { + return; + } + if (sidebar.hasClass("visible")) { + sidebar.removeClass("visible"); + } + }); +}); + +// Resizes the package name / sitename in the sidebar if it is too wide. +// Inspired by: https://github.com/davatron5000/FitText.js +$(document).ready(function () { + e = $("#documenter .docs-autofit"); + function resize() { + var L = parseInt(e.css("max-width"), 10); + var L0 = e.width(); + if (L0 > L) { + var h0 = parseInt(e.css("font-size"), 10); + e.css("font-size", (L * h0) / L0); + // TODO: make sure it survives resizes? + } + } + // call once and then register events + resize(); + $(window).resize(resize); + $(window).on("orientationchange", resize); +}); + +// Scroll the navigation bar to the currently selected menu item +$(document).ready(function () { + var sidebar = $("#documenter .docs-menu").get(0); + var active = $("#documenter .docs-menu .is-active").get(0); + if (typeof active !== "undefined") { + sidebar.scrollTop = active.offsetTop - sidebar.offsetTop - 15; + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Theme picker setup +$(document).ready(function () { + // onchange callback + $("#documenter-themepicker").change(function themepick_callback(ev) { + var themename = $("#documenter-themepicker option:selected").attr("value"); + if (themename === "auto") { + // set_theme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'); + window.localStorage.removeItem("documenter-theme"); + } else { + // set_theme(themename); + window.localStorage.setItem("documenter-theme", themename); + } + // We re-use the global function from themeswap.js to actually do the swapping. + set_theme_from_local_storage(); + }); + + // Make sure that the themepicker displays the correct theme when the theme is retrieved + // from localStorage + if (typeof window.localStorage !== "undefined") { + var theme = window.localStorage.getItem("documenter-theme"); + if (theme !== null) { + $("#documenter-themepicker option").each(function (i, e) { + e.selected = e.value === theme; + }); + } + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// update the version selector with info from the siteinfo.js and ../versions.js files +$(document).ready(function () { + // If the version selector is disabled with DOCUMENTER_VERSION_SELECTOR_DISABLED in the + // siteinfo.js file, we just return immediately and not display the version selector. + if ( + typeof DOCUMENTER_VERSION_SELECTOR_DISABLED === "boolean" && + DOCUMENTER_VERSION_SELECTOR_DISABLED + ) { + return; + } + + var version_selector = $("#documenter .docs-version-selector"); + var version_selector_select = $("#documenter .docs-version-selector select"); + + version_selector_select.change(function (x) { + target_href = version_selector_select + .children("option:selected") + .get(0).value; + window.location.href = target_href; + }); + + // add the current version to the selector based on siteinfo.js, but only if the selector is empty + if ( + typeof DOCUMENTER_CURRENT_VERSION !== "undefined" && + $("#version-selector > option").length == 0 + ) { + var option = $( + "" + ); + version_selector_select.append(option); + } + + if (typeof DOC_VERSIONS !== "undefined") { + var existing_versions = version_selector_select.children("option"); + var existing_versions_texts = existing_versions.map(function (i, x) { + return x.text; + }); + DOC_VERSIONS.forEach(function (each) { + var version_url = documenterBaseURL + "/../" + each + "/"; + var existing_id = $.inArray(each, existing_versions_texts); + // if not already in the version selector, add it as a new option, + // otherwise update the old option with the URL and enable it + if (existing_id == -1) { + var option = $( + "" + ); + version_selector_select.append(option); + } else { + var option = existing_versions[existing_id]; + option.value = version_url; + option.disabled = false; + } + }); + } + + // only show the version selector if the selector has been populated + if (version_selector_select.children("option").length > 0) { + version_selector.toggleClass("visible"); + } +}); + +}) diff --git a/v2.16.1/assets/examples/Active Inference Mountain car_4_1.png b/v2.16.1/assets/examples/Active Inference Mountain car_4_1.png new file mode 100644 index 000000000..9394d1730 Binary files /dev/null and b/v2.16.1/assets/examples/Active Inference Mountain car_4_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_12_1.png b/v2.16.1/assets/examples/Autoregressive Models_12_1.png new file mode 100644 index 000000000..5f7b543d9 Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_12_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_13_1.png b/v2.16.1/assets/examples/Autoregressive Models_13_1.png new file mode 100644 index 000000000..99416e777 Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_13_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_14_1.png b/v2.16.1/assets/examples/Autoregressive Models_14_1.png new file mode 100644 index 000000000..e4b52db2e Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_14_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_24_1.png b/v2.16.1/assets/examples/Autoregressive Models_24_1.png new file mode 100644 index 000000000..92d942e95 Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_24_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_32_1.png b/v2.16.1/assets/examples/Autoregressive Models_32_1.png new file mode 100644 index 000000000..9b30d0046 Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_32_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_36_1.png b/v2.16.1/assets/examples/Autoregressive Models_36_1.png new file mode 100644 index 000000000..047100331 Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_36_1.png differ diff --git a/v2.16.1/assets/examples/Autoregressive Models_6_1.png b/v2.16.1/assets/examples/Autoregressive Models_6_1.png new file mode 100644 index 000000000..309eadff5 Binary files /dev/null and b/v2.16.1/assets/examples/Autoregressive Models_6_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_10_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_10_1.png new file mode 100644 index 000000000..4ecb12eef Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_10_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_12_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_12_1.png new file mode 100644 index 000000000..21f2cf9b8 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_12_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_14_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_14_1.png new file mode 100644 index 000000000..d35fb5850 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_14_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_15_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_15_1.png new file mode 100644 index 000000000..8068d76e2 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_15_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_16_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_16_1.png new file mode 100644 index 000000000..2dd3fcb12 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_16_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_17_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_17_1.png new file mode 100644 index 000000000..ddcc56f62 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_17_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_18_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_18_1.png new file mode 100644 index 000000000..514faf4c9 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_18_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_21_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_21_1.png new file mode 100644 index 000000000..157bce417 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_21_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_24_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_24_1.png new file mode 100644 index 000000000..8846a531d Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_24_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_25_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_25_1.png new file mode 100644 index 000000000..da8387995 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_25_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_26_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_26_1.png new file mode 100644 index 000000000..0b3299f1c Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_26_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_27_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_27_1.png new file mode 100644 index 000000000..dc2785db5 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_27_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_34_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_34_1.png new file mode 100644 index 000000000..e935ce86c Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_34_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_40_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_40_1.png new file mode 100644 index 000000000..a7f23a09f Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_40_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_42_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_42_1.png new file mode 100644 index 000000000..3249d9b3c Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_42_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_4_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_4_1.png new file mode 100644 index 000000000..3851d2ea5 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_4_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_51_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_51_1.png new file mode 100644 index 000000000..df1ae996a Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_51_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_54_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_54_1.png new file mode 100644 index 000000000..8da279955 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_54_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_55_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_55_1.png new file mode 100644 index 000000000..ca615bf2c Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_55_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_7_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_7_1.png new file mode 100644 index 000000000..564b04161 Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_7_1.png differ diff --git a/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_8_1.png b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_8_1.png new file mode 100644 index 000000000..b86dc84cd Binary files /dev/null and b/v2.16.1/assets/examples/Bayesian Linear Regression Tutorial_8_1.png differ diff --git a/v2.16.1/assets/examples/Chance Constraints_11_1.png b/v2.16.1/assets/examples/Chance Constraints_11_1.png new file mode 100644 index 000000000..b7b9be536 Binary files /dev/null and b/v2.16.1/assets/examples/Chance Constraints_11_1.png differ diff --git a/v2.16.1/assets/examples/Coin Toss Model_7_1.png b/v2.16.1/assets/examples/Coin Toss Model_7_1.png new file mode 100644 index 000000000..180821d61 Binary files /dev/null and b/v2.16.1/assets/examples/Coin Toss Model_7_1.png differ diff --git a/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png b/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png new file mode 100644 index 000000000..d90df26c0 Binary files /dev/null and b/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png differ diff --git a/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png b/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png new file mode 100644 index 000000000..14f524963 Binary files /dev/null and b/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png differ diff --git a/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png b/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png new file mode 100644 index 000000000..2e19804fb Binary files /dev/null and b/v2.16.1/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png differ diff --git a/v2.16.1/assets/examples/GP Regression by SSM_10_1.png b/v2.16.1/assets/examples/GP Regression by SSM_10_1.png new file mode 100644 index 000000000..be25d53d3 Binary files /dev/null and b/v2.16.1/assets/examples/GP Regression by SSM_10_1.png differ diff --git a/v2.16.1/assets/examples/GP Regression by SSM_5_1.png b/v2.16.1/assets/examples/GP Regression by SSM_5_1.png new file mode 100644 index 000000000..3246e6256 Binary files /dev/null and b/v2.16.1/assets/examples/GP Regression by SSM_5_1.png differ diff --git a/v2.16.1/assets/examples/Gamma Mixture_10_1.png b/v2.16.1/assets/examples/Gamma Mixture_10_1.png new file mode 100644 index 000000000..bd8ce343b Binary files /dev/null and b/v2.16.1/assets/examples/Gamma Mixture_10_1.png differ diff --git a/v2.16.1/assets/examples/Gaussian Mixture_12_1.png b/v2.16.1/assets/examples/Gaussian Mixture_12_1.png new file mode 100644 index 000000000..fc21b9942 Binary files /dev/null and b/v2.16.1/assets/examples/Gaussian Mixture_12_1.png differ diff --git a/v2.16.1/assets/examples/Gaussian Mixture_4_1.png b/v2.16.1/assets/examples/Gaussian Mixture_4_1.png new file mode 100644 index 000000000..aedf37236 Binary files /dev/null and b/v2.16.1/assets/examples/Gaussian Mixture_4_1.png differ diff --git a/v2.16.1/assets/examples/Gaussian Mixture_7_1.png b/v2.16.1/assets/examples/Gaussian Mixture_7_1.png new file mode 100644 index 000000000..338fe2092 Binary files /dev/null and b/v2.16.1/assets/examples/Gaussian Mixture_7_1.png differ diff --git a/v2.16.1/assets/examples/Gaussian Mixture_9_1.png b/v2.16.1/assets/examples/Gaussian Mixture_9_1.png new file mode 100644 index 000000000..64adeef14 Binary files /dev/null and b/v2.16.1/assets/examples/Gaussian Mixture_9_1.png differ diff --git a/v2.16.1/assets/examples/Global Parameter Optimisation_14_1.png b/v2.16.1/assets/examples/Global Parameter Optimisation_14_1.png new file mode 100644 index 000000000..70f61d1cf Binary files /dev/null and b/v2.16.1/assets/examples/Global Parameter Optimisation_14_1.png differ diff --git a/v2.16.1/assets/examples/Global Parameter Optimisation_18_1.png b/v2.16.1/assets/examples/Global Parameter Optimisation_18_1.png new file mode 100644 index 000000000..eac50a682 Binary files /dev/null and b/v2.16.1/assets/examples/Global Parameter Optimisation_18_1.png differ diff --git a/v2.16.1/assets/examples/Global Parameter Optimisation_22_1.png b/v2.16.1/assets/examples/Global Parameter Optimisation_22_1.png new file mode 100644 index 000000000..c24630442 Binary files /dev/null and b/v2.16.1/assets/examples/Global Parameter Optimisation_22_1.png differ diff --git a/v2.16.1/assets/examples/Global Parameter Optimisation_28_1.png b/v2.16.1/assets/examples/Global Parameter Optimisation_28_1.png new file mode 100644 index 000000000..08b8ef056 Binary files /dev/null and b/v2.16.1/assets/examples/Global Parameter Optimisation_28_1.png differ diff --git a/v2.16.1/assets/examples/Global Parameter Optimisation_32_1.png b/v2.16.1/assets/examples/Global Parameter Optimisation_32_1.png new file mode 100644 index 000000000..cf55c8da0 Binary files /dev/null and b/v2.16.1/assets/examples/Global Parameter Optimisation_32_1.png differ diff --git a/v2.16.1/assets/examples/Global Parameter Optimisation_35_1.png b/v2.16.1/assets/examples/Global Parameter Optimisation_35_1.png new file mode 100644 index 000000000..fddb20942 Binary files /dev/null and b/v2.16.1/assets/examples/Global Parameter Optimisation_35_1.png differ diff --git a/v2.16.1/assets/examples/Hidden Markov Model_4_1.png b/v2.16.1/assets/examples/Hidden Markov Model_4_1.png new file mode 100644 index 000000000..a15a96215 Binary files /dev/null and b/v2.16.1/assets/examples/Hidden Markov Model_4_1.png differ diff --git a/v2.16.1/assets/examples/Hidden Markov Model_9_1.png b/v2.16.1/assets/examples/Hidden Markov Model_9_1.png new file mode 100644 index 000000000..32d9bbc46 Binary files /dev/null and b/v2.16.1/assets/examples/Hidden Markov Model_9_1.png differ diff --git a/v2.16.1/assets/examples/Hierarchical Gaussian Filter_10_1.png b/v2.16.1/assets/examples/Hierarchical Gaussian Filter_10_1.png new file mode 100644 index 000000000..6a3b9c9dc Binary files /dev/null and b/v2.16.1/assets/examples/Hierarchical Gaussian Filter_10_1.png differ diff --git a/v2.16.1/assets/examples/Hierarchical Gaussian Filter_5_1.png b/v2.16.1/assets/examples/Hierarchical Gaussian Filter_5_1.png new file mode 100644 index 000000000..2d74bff5a Binary files /dev/null and b/v2.16.1/assets/examples/Hierarchical Gaussian Filter_5_1.png differ diff --git a/v2.16.1/assets/examples/Hierarchical Gaussian Filter_9_1.png b/v2.16.1/assets/examples/Hierarchical Gaussian Filter_9_1.png new file mode 100644 index 000000000..9821f6bc9 Binary files /dev/null and b/v2.16.1/assets/examples/Hierarchical Gaussian Filter_9_1.png differ diff --git a/v2.16.1/assets/examples/Infinite Data Stream_11_1.png b/v2.16.1/assets/examples/Infinite Data Stream_11_1.png new file mode 100644 index 000000000..dba34e4ef Binary files /dev/null and b/v2.16.1/assets/examples/Infinite Data Stream_11_1.png differ diff --git a/v2.16.1/assets/examples/Invertible Neural Network Tutorial_10_1.png b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_10_1.png new file mode 100644 index 000000000..009e76bec Binary files /dev/null and b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_10_1.png differ diff --git a/v2.16.1/assets/examples/Invertible Neural Network Tutorial_14_1.png b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_14_1.png new file mode 100644 index 000000000..95edfacc0 Binary files /dev/null and b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_14_1.png differ diff --git a/v2.16.1/assets/examples/Invertible Neural Network Tutorial_15_1.png b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_15_1.png new file mode 100644 index 000000000..ab077a912 Binary files /dev/null and b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_15_1.png differ diff --git a/v2.16.1/assets/examples/Invertible Neural Network Tutorial_17_1.png b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_17_1.png new file mode 100644 index 000000000..201b882c0 Binary files /dev/null and b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_17_1.png differ diff --git a/v2.16.1/assets/examples/Invertible Neural Network Tutorial_23_1.png b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_23_1.png new file mode 100644 index 000000000..a639d283d Binary files /dev/null and b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_23_1.png differ diff --git a/v2.16.1/assets/examples/Invertible Neural Network Tutorial_24_1.png b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_24_1.png new file mode 100644 index 000000000..b38e5ab4e Binary files /dev/null and b/v2.16.1/assets/examples/Invertible Neural Network Tutorial_24_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_10_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_10_1.png new file mode 100644 index 000000000..404cd2073 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_10_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_15_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_15_1.png new file mode 100644 index 000000000..387f83e00 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_15_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_20_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_20_1.png new file mode 100644 index 000000000..0332168c8 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_20_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_23_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_23_1.png new file mode 100644 index 000000000..3997d6305 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_23_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_25_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_25_1.png new file mode 100644 index 000000000..baae896e0 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_25_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_30_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_30_1.png new file mode 100644 index 000000000..0ca63d89e Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_30_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_33_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_33_1.png new file mode 100644 index 000000000..230f9e497 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_33_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_39_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_39_1.png new file mode 100644 index 000000000..4142ddba6 Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_39_1.png differ diff --git a/v2.16.1/assets/examples/Kalman filtering and smoothing_6_1.png b/v2.16.1/assets/examples/Kalman filtering and smoothing_6_1.png new file mode 100644 index 000000000..868c31a7a Binary files /dev/null and b/v2.16.1/assets/examples/Kalman filtering and smoothing_6_1.png differ diff --git a/v2.16.1/assets/examples/Nonlinear Sensor Fusion_12_1.png b/v2.16.1/assets/examples/Nonlinear Sensor Fusion_12_1.png new file mode 100644 index 000000000..b2722f776 Binary files /dev/null and b/v2.16.1/assets/examples/Nonlinear Sensor Fusion_12_1.png differ diff --git a/v2.16.1/assets/examples/Nonlinear Sensor Fusion_17_1.png b/v2.16.1/assets/examples/Nonlinear Sensor Fusion_17_1.png new file mode 100644 index 000000000..4d1e2bd3c Binary files /dev/null and b/v2.16.1/assets/examples/Nonlinear Sensor Fusion_17_1.png differ diff --git a/v2.16.1/assets/examples/Nonlinear Sensor Fusion_4_1.png b/v2.16.1/assets/examples/Nonlinear Sensor Fusion_4_1.png new file mode 100644 index 000000000..6be9531bf Binary files /dev/null and b/v2.16.1/assets/examples/Nonlinear Sensor Fusion_4_1.png differ diff --git a/v2.16.1/assets/examples/Predicting Bike Rental Demand_17_1.png b/v2.16.1/assets/examples/Predicting Bike Rental Demand_17_1.png new file mode 100644 index 000000000..49ebabbfb Binary files /dev/null and b/v2.16.1/assets/examples/Predicting Bike Rental Demand_17_1.png differ diff --git a/v2.16.1/assets/examples/Predicting Bike Rental Demand_18_1.png b/v2.16.1/assets/examples/Predicting Bike Rental Demand_18_1.png new file mode 100644 index 000000000..ed7f08607 Binary files /dev/null and b/v2.16.1/assets/examples/Predicting Bike Rental Demand_18_1.png differ diff --git a/v2.16.1/assets/examples/Probit Model (EP)_6_1.png b/v2.16.1/assets/examples/Probit Model (EP)_6_1.png new file mode 100644 index 000000000..b9b15d04b Binary files /dev/null and b/v2.16.1/assets/examples/Probit Model (EP)_6_1.png differ diff --git a/v2.16.1/assets/examples/Probit Model (EP)_9_1.png b/v2.16.1/assets/examples/Probit Model (EP)_9_1.png new file mode 100644 index 000000000..baf1f1c80 Binary files /dev/null and b/v2.16.1/assets/examples/Probit Model (EP)_9_1.png differ diff --git a/v2.16.1/assets/examples/RTS vs BIFM Smoothing_11_1.png b/v2.16.1/assets/examples/RTS vs BIFM Smoothing_11_1.png new file mode 100644 index 000000000..35cf1d760 Binary files /dev/null and b/v2.16.1/assets/examples/RTS vs BIFM Smoothing_11_1.png differ diff --git a/v2.16.1/assets/examples/RTS vs BIFM Smoothing_12_1.png b/v2.16.1/assets/examples/RTS vs BIFM Smoothing_12_1.png new file mode 100644 index 000000000..8e760b4b4 Binary files /dev/null and b/v2.16.1/assets/examples/RTS vs BIFM Smoothing_12_1.png differ diff --git a/v2.16.1/assets/examples/RTS vs BIFM Smoothing_5_1.png b/v2.16.1/assets/examples/RTS vs BIFM Smoothing_5_1.png new file mode 100644 index 000000000..4eeffb7bb Binary files /dev/null and b/v2.16.1/assets/examples/RTS vs BIFM Smoothing_5_1.png differ diff --git a/v2.16.1/assets/examples/Simple Nonlinear Node_14_1.png b/v2.16.1/assets/examples/Simple Nonlinear Node_14_1.png new file mode 100644 index 000000000..ae77e0037 Binary files /dev/null and b/v2.16.1/assets/examples/Simple Nonlinear Node_14_1.png differ diff --git a/v2.16.1/assets/examples/Tiny Benchmark_11_1.png b/v2.16.1/assets/examples/Tiny Benchmark_11_1.png new file mode 100644 index 000000000..97ee402ca Binary files /dev/null and b/v2.16.1/assets/examples/Tiny Benchmark_11_1.png differ diff --git a/v2.16.1/assets/examples/Tiny Benchmark_7_1.png b/v2.16.1/assets/examples/Tiny Benchmark_7_1.png new file mode 100644 index 000000000..36c08b460 Binary files /dev/null and b/v2.16.1/assets/examples/Tiny Benchmark_7_1.png differ diff --git a/v2.16.1/assets/examples/Universal Mixtures_10_1.png b/v2.16.1/assets/examples/Universal Mixtures_10_1.png new file mode 100644 index 000000000..fd23f884a Binary files /dev/null and b/v2.16.1/assets/examples/Universal Mixtures_10_1.png differ diff --git a/v2.16.1/assets/examples/Universal Mixtures_13_1.png b/v2.16.1/assets/examples/Universal Mixtures_13_1.png new file mode 100644 index 000000000..cf2c5244c Binary files /dev/null and b/v2.16.1/assets/examples/Universal Mixtures_13_1.png differ diff --git a/v2.16.1/assets/examples/Universal Mixtures_3_1.png b/v2.16.1/assets/examples/Universal Mixtures_3_1.png new file mode 100644 index 000000000..cec0904cc Binary files /dev/null and b/v2.16.1/assets/examples/Universal Mixtures_3_1.png differ diff --git a/v2.16.1/assets/examples/Universal Mixtures_9_1.png b/v2.16.1/assets/examples/Universal Mixtures_9_1.png new file mode 100644 index 000000000..a6c946c8b Binary files /dev/null and b/v2.16.1/assets/examples/Universal Mixtures_9_1.png differ diff --git a/v2.16.1/assets/examples/pics/ai-mountain-car-ai.gif b/v2.16.1/assets/examples/pics/ai-mountain-car-ai.gif new file mode 100644 index 000000000..87f6cc774 Binary files /dev/null and b/v2.16.1/assets/examples/pics/ai-mountain-car-ai.gif differ diff --git a/v2.16.1/assets/examples/pics/ai-mountain-car-naive.gif b/v2.16.1/assets/examples/pics/ai-mountain-car-naive.gif new file mode 100644 index 000000000..80fdf4e1c Binary files /dev/null and b/v2.16.1/assets/examples/pics/ai-mountain-car-naive.gif differ diff --git a/v2.16.1/assets/examples/pics/hblr-matrix-completion.jpeg b/v2.16.1/assets/examples/pics/hblr-matrix-completion.jpeg new file mode 100644 index 000000000..be0f78e1c Binary files /dev/null and b/v2.16.1/assets/examples/pics/hblr-matrix-completion.jpeg differ diff --git a/v2.16.1/assets/examples/pics/infinite-data-stream-inference.gif b/v2.16.1/assets/examples/pics/infinite-data-stream-inference.gif new file mode 100644 index 000000000..03ba8b472 Binary files /dev/null and b/v2.16.1/assets/examples/pics/infinite-data-stream-inference.gif differ diff --git a/v2.16.1/assets/examples/pics/infinite-data-stream.gif b/v2.16.1/assets/examples/pics/infinite-data-stream.gif new file mode 100644 index 000000000..67d9c4555 Binary files /dev/null and b/v2.16.1/assets/examples/pics/infinite-data-stream.gif differ diff --git a/v2.16.1/assets/examples/pics/online-coin-bias-inference.gif b/v2.16.1/assets/examples/pics/online-coin-bias-inference.gif new file mode 100644 index 000000000..3c8c35641 Binary files /dev/null and b/v2.16.1/assets/examples/pics/online-coin-bias-inference.gif differ diff --git a/v2.16.1/assets/examples/pics/pipeline.png b/v2.16.1/assets/examples/pics/pipeline.png new file mode 100644 index 000000000..d8302e166 Binary files /dev/null and b/v2.16.1/assets/examples/pics/pipeline.png differ diff --git a/v2.16.1/assets/examples/pics/posterior.png b/v2.16.1/assets/examples/pics/posterior.png new file mode 100644 index 000000000..4fa49edff Binary files /dev/null and b/v2.16.1/assets/examples/pics/posterior.png differ diff --git a/v2.16.1/assets/examples/pics/rts_bifm_benchmark.png b/v2.16.1/assets/examples/pics/rts_bifm_benchmark.png new file mode 100644 index 000000000..51a066062 Binary files /dev/null and b/v2.16.1/assets/examples/pics/rts_bifm_benchmark.png differ diff --git a/v2.16.1/assets/examples/pics/sp.png b/v2.16.1/assets/examples/pics/sp.png new file mode 100644 index 000000000..dedc65431 Binary files /dev/null and b/v2.16.1/assets/examples/pics/sp.png differ diff --git a/v2.16.1/assets/examples/pics/vmp.png b/v2.16.1/assets/examples/pics/vmp.png new file mode 100644 index 000000000..0561f27e3 Binary files /dev/null and b/v2.16.1/assets/examples/pics/vmp.png differ diff --git a/v2.16.1/assets/header.css b/v2.16.1/assets/header.css new file mode 100644 index 000000000..155b10a3b --- /dev/null +++ b/v2.16.1/assets/header.css @@ -0,0 +1,138 @@ + +@media all and (max-width: 560px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar { + min-height: 1rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + min-height: 1rem !important; + margin-left: 0.5rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: visible !important; + display: block !important; + margin: 0.5rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + visibility: hidden; + display: none; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a { + visibility: hidden; + display: none; + } + + html:not(.theme--documenter-dark) body #documenter .docs-main { + margin-top: 2rem !important; + } +} + +@media all and (max-width: 1055px) and (min-width: 561px){ + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + width: 80% !important; + } +} + +@media all and (min-width: 1056px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 18rem; + } + +} + +html.theme--documenter-dark header.navigation { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container { + border-bottom: 1px solid #5e6d6f; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: white; + transition: color 100ms; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +html header.navigation { + background-color: white !important; +} + +html header.navigation div.container { + border-bottom: 1px solid #dbdbdb; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: #222; + transition: color 100ms; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +header.navigation { + z-index: 3; +} + +header.navigation div.container nav.navbar ul.navbar-nav { + margin-left: 4rem; + min-height: 3.25rem; + width: 70%; + display: flex; + align-self: auto; + flex-direction: row; + justify-content: space-around; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + align-self: stretch; + align-content: space-around; + justify-content: center; + display: flex; + flex-direction: column; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: hidden; + display: none; +} \ No newline at end of file diff --git a/v2.16.1/assets/header.js b/v2.16.1/assets/header.js new file mode 100644 index 000000000..7f15cae83 --- /dev/null +++ b/v2.16.1/assets/header.js @@ -0,0 +1,97 @@ + +// We add a simple `onload` hook to inject the custom header for our `HTML`-generated pages +window.onload = function() { + //
+ const header = document.createElement('header') + header.classList.add("navigation") + header.appendChild((() => { + const container = document.createElement('div') + container.classList.add('container') + container.appendChild((() => { + const nav = document.createElement('nav') + nav.classList.add("navbar") + + nav.appendChild((() => { + const ul = document.createElement("ul") + ul.classList.add("navbar-nav") + + ul.appendChild((() => { + const smalllink = document.createElement('li') + smalllink.classList.add('small-item') + smalllink.appendChild((() => { + const a = document.createElement('a') + a.classList.add("nav-link") + a.href = 'http://www.rxinfer.ml' + a.innerHTML = 'RxInfer.jl' + a.title = 'RxInfer.jl' + return a + })()) + return smalllink + })()) + + const items = [ + { title: "Home", link: "http://www.rxinfer.ml", icon: [ "fas", "fa-diagram-project" ] }, + { title: "Get Started", link: "https://reactivebayes.github.io/RxInfer.jl/stable/manuals/getting-started/" }, + { title: "Documentation", link: "https://reactivebayes.github.io/RxInfer.jl/stable/" }, + { title: "Examples", link: "https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/" }, + { title: "Papers", link: "https://reactivebayes.github.io/publication/" }, + { title: "Team", link: "https://reactivebayes.github.io/team/" }, + // { title: "Contact", link: "http://www.rxinfer.ml/contact/" }, the redirect is broken for now + { title: "GitHub", link: "https://github.com/reactivebayes/RxInfer.jl", icon: [ "fab", "fa-github" ] }, + ] + + items.forEach((item) => { + ul.appendChild(((item) => { + const li = document.createElement("li") + li.classList.add("nav-item") + li.appendChild((() => { + const a = document.createElement("a") + + if (item.icon !== undefined) { + a.appendChild((() => { + const i = document.createElement("i") + i.classList.add(...(item.icon)) + return i + })()) + } + + a.classList.add("nav-link") + a.href = item.link + a.title = item.title + + a.appendChild((() => { + const span = document.createElement("span") + span.innerHTML = ` ${item.title}` + return span + })()) + + return a + })()) + return li + })(item)) + }) + return ul + })()) + return nav + })()) + return container + })()) + + const documenterTarget = document.querySelector('#documenter'); + + documenterTarget.parentNode.insertBefore(header, documenterTarget); + + // Edit broken links in the examples, see issue #70 + const editOnGithubLinkTarget = document.querySelector('.docs-edit-link'); + + if (editOnGithubLinkTarget) { + const link = editOnGithubLinkTarget.href; + if (link.includes('docs/src/examples')) { + const fixedLink = link.replace('docs/src/', '').replace('.md', '.ipynb'); + editOnGithubLinkTarget.href = fixedLink; + console.log('Fixed link for the example: ', fixedLink) + } + } + +} + diff --git a/v2.16.1/assets/img/bp-message.svg b/v2.16.1/assets/img/bp-message.svg new file mode 100644 index 000000000..259b70803 --- /dev/null +++ b/v2.16.1/assets/img/bp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.16.1/assets/img/coin-flip.png b/v2.16.1/assets/img/coin-flip.png new file mode 100644 index 000000000..2ed0f04c0 Binary files /dev/null and b/v2.16.1/assets/img/coin-flip.png differ diff --git a/v2.16.1/assets/img/coin-flip.svg b/v2.16.1/assets/img/coin-flip.svg new file mode 100644 index 000000000..a85960c12 --- /dev/null +++ b/v2.16.1/assets/img/coin-flip.svg @@ -0,0 +1,794 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/assets/img/debugging_graph.png b/v2.16.1/assets/img/debugging_graph.png new file mode 100644 index 000000000..b97ef1a06 Binary files /dev/null and b/v2.16.1/assets/img/debugging_graph.png differ diff --git a/v2.16.1/assets/img/debugging_messages.png b/v2.16.1/assets/img/debugging_messages.png new file mode 100644 index 000000000..8ec84e778 Binary files /dev/null and b/v2.16.1/assets/img/debugging_messages.png differ diff --git a/v2.16.1/assets/img/release_comment.png b/v2.16.1/assets/img/release_comment.png new file mode 100644 index 000000000..743fe9614 Binary files /dev/null and b/v2.16.1/assets/img/release_comment.png differ diff --git a/v2.16.1/assets/img/vmp-message.svg b/v2.16.1/assets/img/vmp-message.svg new file mode 100644 index 000000000..475cd7f49 --- /dev/null +++ b/v2.16.1/assets/img/vmp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.16.1/assets/logo-dark.svg b/v2.16.1/assets/logo-dark.svg new file mode 100644 index 000000000..63b4f65fa --- /dev/null +++ b/v2.16.1/assets/logo-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + diff --git a/v2.16.1/assets/logo.svg b/v2.16.1/assets/logo.svg new file mode 100644 index 000000000..b799e5beb --- /dev/null +++ b/v2.16.1/assets/logo.svg @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/v2.16.1/assets/theme.css b/v2.16.1/assets/theme.css new file mode 100644 index 000000000..1b060cdef --- /dev/null +++ b/v2.16.1/assets/theme.css @@ -0,0 +1,27 @@ +html body #documenter .docs-main { + margin-top: 4rem; +} + +html body #documenter .docs-sidebar.visible { + margin-top: 0px !important; +} + +html div.light-biglogo { + display: block; +} + +html.theme--documenter-dark div.light-biglogo { + display: none; +} + +html div.dark-biglogo { + display: none; +} + +html.theme--documenter-dark div.dark-biglogo { + display: block; +} + +#documenter .docs-main article.content img { + width: 100%; +} diff --git a/v2.16.1/assets/themes/documenter-dark.css b/v2.16.1/assets/themes/documenter-dark.css new file mode 100644 index 000000000..9f5449f4b --- /dev/null +++ b/v2.16.1/assets/themes/documenter-dark.css @@ -0,0 +1,7 @@ +html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:.4em;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus,html.theme--documenter-dark .pagination-ellipsis:focus,html.theme--documenter-dark .file-cta:focus,html.theme--documenter-dark .file-name:focus,html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .button:focus,html.theme--documenter-dark .is-focused.pagination-previous,html.theme--documenter-dark .is-focused.pagination-next,html.theme--documenter-dark .is-focused.pagination-link,html.theme--documenter-dark .is-focused.pagination-ellipsis,html.theme--documenter-dark .is-focused.file-cta,html.theme--documenter-dark .is-focused.file-name,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-focused.button,html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active,html.theme--documenter-dark .pagination-ellipsis:active,html.theme--documenter-dark .file-cta:active,html.theme--documenter-dark .file-name:active,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .button:active,html.theme--documenter-dark .is-active.pagination-previous,html.theme--documenter-dark .is-active.pagination-next,html.theme--documenter-dark .is-active.pagination-link,html.theme--documenter-dark .is-active.pagination-ellipsis,html.theme--documenter-dark .is-active.file-cta,html.theme--documenter-dark .is-active.file-name,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .is-active.button{outline:none}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-ellipsis[disabled],html.theme--documenter-dark .file-cta[disabled],html.theme--documenter-dark .file-name[disabled],html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark fieldset[disabled] .pagination-previous,fieldset[disabled] html.theme--documenter-dark .pagination-next,html.theme--documenter-dark fieldset[disabled] .pagination-next,fieldset[disabled] html.theme--documenter-dark .pagination-link,html.theme--documenter-dark fieldset[disabled] .pagination-link,fieldset[disabled] html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark fieldset[disabled] .pagination-ellipsis,fieldset[disabled] html.theme--documenter-dark .file-cta,html.theme--documenter-dark fieldset[disabled] .file-cta,fieldset[disabled] html.theme--documenter-dark .file-name,html.theme--documenter-dark fieldset[disabled] .file-name,fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark fieldset[disabled] .select select,html.theme--documenter-dark .select fieldset[disabled] select,html.theme--documenter-dark fieldset[disabled] .textarea,html.theme--documenter-dark fieldset[disabled] .input,html.theme--documenter-dark fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] html.theme--documenter-dark .button,html.theme--documenter-dark fieldset[disabled] .button{cursor:not-allowed}html.theme--documenter-dark .tabs,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .breadcrumb,html.theme--documenter-dark .file,html.theme--documenter-dark .button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after,html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}html.theme--documenter-dark .admonition:not(:last-child),html.theme--documenter-dark .tabs:not(:last-child),html.theme--documenter-dark .pagination:not(:last-child),html.theme--documenter-dark .message:not(:last-child),html.theme--documenter-dark .level:not(:last-child),html.theme--documenter-dark .breadcrumb:not(:last-child),html.theme--documenter-dark .block:not(:last-child),html.theme--documenter-dark .title:not(:last-child),html.theme--documenter-dark .subtitle:not(:last-child),html.theme--documenter-dark .table-container:not(:last-child),html.theme--documenter-dark .table:not(:last-child),html.theme--documenter-dark .progress:not(:last-child),html.theme--documenter-dark .notification:not(:last-child),html.theme--documenter-dark .content:not(:last-child),html.theme--documenter-dark .box:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .modal-close,html.theme--documenter-dark .delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before,html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before{height:2px;width:50%}html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{height:50%;width:2px}html.theme--documenter-dark .modal-close:hover,html.theme--documenter-dark .delete:hover,html.theme--documenter-dark .modal-close:focus,html.theme--documenter-dark .delete:focus{background-color:rgba(10,10,10,0.3)}html.theme--documenter-dark .modal-close:active,html.theme--documenter-dark .delete:active{background-color:rgba(10,10,10,0.4)}html.theme--documenter-dark .is-small.modal-close,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.modal-close,html.theme--documenter-dark .is-small.delete,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}html.theme--documenter-dark .is-medium.modal-close,html.theme--documenter-dark .is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}html.theme--documenter-dark .is-large.modal-close,html.theme--documenter-dark .is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}html.theme--documenter-dark .control.is-loading::after,html.theme--documenter-dark .select.is-loading::after,html.theme--documenter-dark .loader,html.theme--documenter-dark .button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdee0;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}html.theme--documenter-dark .hero-video,html.theme--documenter-dark .modal-background,html.theme--documenter-dark .modal,html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}html.theme--documenter-dark .navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#ecf0f1 !important}a.has-text-light:hover,a.has-text-light:focus{color:#cfd9db !important}.has-background-light{background-color:#ecf0f1 !important}.has-text-dark{color:#282f2f !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#111414 !important}.has-background-dark{background-color:#282f2f !important}.has-text-primary{color:#375a7f !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#28415b !important}.has-background-primary{background-color:#375a7f !important}.has-text-primary-light{color:#f1f5f9 !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#cddbe9 !important}.has-background-primary-light{background-color:#f1f5f9 !important}.has-text-primary-dark{color:#4d7eb2 !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#7198c1 !important}.has-background-primary-dark{background-color:#4d7eb2 !important}.has-text-link{color:#1abc9c !important}a.has-text-link:hover,a.has-text-link:focus{color:#148f77 !important}.has-background-link{background-color:#1abc9c !important}.has-text-link-light{color:#edfdf9 !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c0f6ec !important}.has-background-link-light{background-color:#edfdf9 !important}.has-text-link-dark{color:#15987e !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#1bc5a4 !important}.has-background-link-dark{background-color:#15987e !important}.has-text-info{color:#024c7d !important}a.has-text-info:hover,a.has-text-info:focus{color:#012d4b !important}.has-background-info{background-color:#024c7d !important}.has-text-info-light{color:#ebf7ff !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#b9e2fe !important}.has-background-info-light{background-color:#ebf7ff !important}.has-text-info-dark{color:#0e9dfb !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#40b1fc !important}.has-background-info-dark{background-color:#0e9dfb !important}.has-text-success{color:#008438 !important}a.has-text-success:hover,a.has-text-success:focus{color:#005122 !important}.has-background-success{background-color:#008438 !important}.has-text-success-light{color:#ebfff3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#b8ffd6 !important}.has-background-success-light{background-color:#ebfff3 !important}.has-text-success-dark{color:#00eb64 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#1fff7e !important}.has-background-success-dark{background-color:#00eb64 !important}.has-text-warning{color:#ad8100 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#7a5b00 !important}.has-background-warning{background-color:#ad8100 !important}.has-text-warning-light{color:#fffaeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#ffedb8 !important}.has-background-warning-light{background-color:#fffaeb !important}.has-text-warning-dark{color:#d19c00 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#ffbf05 !important}.has-background-warning-dark{background-color:#d19c00 !important}.has-text-danger{color:#9e1b0d !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#6f1309 !important}.has-background-danger{background-color:#9e1b0d !important}.has-text-danger-light{color:#fdeeec !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#fac3bd !important}.has-background-danger-light{background-color:#fdeeec !important}.has-text-danger-dark{color:#ec311d !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#f05c4c !important}.has-background-danger-dark{background-color:#ec311d !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#282f2f !important}.has-background-grey-darker{background-color:#282f2f !important}.has-text-grey-dark{color:#343c3d !important}.has-background-grey-dark{background-color:#343c3d !important}.has-text-grey{color:#5e6d6f !important}.has-background-grey{background-color:#5e6d6f !important}.has-text-grey-light{color:#8c9b9d !important}.has-background-grey-light{background-color:#8c9b9d !important}.has-text-grey-lighter{color:#dbdee0 !important}.has-background-grey-lighter{background-color:#dbdee0 !important}.has-text-white-ter{color:#ecf0f1 !important}.has-background-white-ter{background-color:#ecf0f1 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}html.theme--documenter-dark{/*! + Theme: a11y-dark + Author: @ericwbailey + Maintainer: @ericwbailey + + Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css +*/}html.theme--documenter-dark html{background-color:#1f2424;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark article,html.theme--documenter-dark aside,html.theme--documenter-dark figure,html.theme--documenter-dark footer,html.theme--documenter-dark header,html.theme--documenter-dark hgroup,html.theme--documenter-dark section{display:block}html.theme--documenter-dark body,html.theme--documenter-dark button,html.theme--documenter-dark input,html.theme--documenter-dark optgroup,html.theme--documenter-dark select,html.theme--documenter-dark textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}html.theme--documenter-dark code,html.theme--documenter-dark pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark body{color:#fff;font-size:1em;font-weight:400;line-height:1.5}html.theme--documenter-dark a{color:#1abc9c;cursor:pointer;text-decoration:none}html.theme--documenter-dark a strong{color:currentColor}html.theme--documenter-dark a:hover{color:#1dd2af}html.theme--documenter-dark code{background-color:rgba(255,255,255,0.05);color:#ececec;font-size:.875em;font-weight:normal;padding:.1em}html.theme--documenter-dark hr{background-color:#282f2f;border:none;display:block;height:2px;margin:1.5rem 0}html.theme--documenter-dark img{height:auto;max-width:100%}html.theme--documenter-dark input[type="checkbox"],html.theme--documenter-dark input[type="radio"]{vertical-align:baseline}html.theme--documenter-dark small{font-size:.875em}html.theme--documenter-dark span{font-style:inherit;font-weight:inherit}html.theme--documenter-dark strong{color:#f2f2f2;font-weight:700}html.theme--documenter-dark fieldset{border:none}html.theme--documenter-dark pre{-webkit-overflow-scrolling:touch;background-color:#282f2f;color:#fff;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}html.theme--documenter-dark pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}html.theme--documenter-dark table td,html.theme--documenter-dark table th{vertical-align:top}html.theme--documenter-dark table td:not([align]),html.theme--documenter-dark table th:not([align]){text-align:inherit}html.theme--documenter-dark table th{color:#f2f2f2}html.theme--documenter-dark .box{background-color:#343c3d;border-radius:8px;box-shadow:none;color:#fff;display:block;padding:1.25rem}html.theme--documenter-dark a.box:hover,html.theme--documenter-dark a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #1abc9c}html.theme--documenter-dark a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #1abc9c}html.theme--documenter-dark .button{background-color:#282f2f;border-color:#4c5759;border-width:1px;color:#375a7f;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}html.theme--documenter-dark .button strong{color:inherit}html.theme--documenter-dark .button .icon,html.theme--documenter-dark .button .icon.is-small,html.theme--documenter-dark .button #documenter .docs-sidebar form.docs-search>input.icon,html.theme--documenter-dark #documenter .docs-sidebar .button form.docs-search>input.icon,html.theme--documenter-dark .button .icon.is-medium,html.theme--documenter-dark .button .icon.is-large{height:1.5em;width:1.5em}html.theme--documenter-dark .button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}html.theme--documenter-dark .button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button:hover,html.theme--documenter-dark .button.is-hovered{border-color:#8c9b9d;color:#f2f2f2}html.theme--documenter-dark .button:focus,html.theme--documenter-dark .button.is-focused{border-color:#8c9b9d;color:#17a689}html.theme--documenter-dark .button:focus:not(:active),html.theme--documenter-dark .button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button:active,html.theme--documenter-dark .button.is-active{border-color:#343c3d;color:#f2f2f2}html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;color:#fff;text-decoration:underline}html.theme--documenter-dark .button.is-text:hover,html.theme--documenter-dark .button.is-text.is-hovered,html.theme--documenter-dark .button.is-text:focus,html.theme--documenter-dark .button.is-text.is-focused{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .button.is-text:active,html.theme--documenter-dark .button.is-text.is-active{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .button.is-text[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}html.theme--documenter-dark .button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#1abc9c;text-decoration:none}html.theme--documenter-dark .button.is-ghost:hover,html.theme--documenter-dark .button.is-ghost.is-hovered{color:#1abc9c;text-decoration:underline}html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:hover,html.theme--documenter-dark .button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus,html.theme--documenter-dark .button.is-white.is-focused{border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus:not(:active),html.theme--documenter-dark .button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-hovered{background-color:#000}html.theme--documenter-dark .button.is-white.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-white.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:hover,html.theme--documenter-dark .button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus,html.theme--documenter-dark .button.is-black.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus:not(:active),html.theme--documenter-dark .button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-black.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:hover,html.theme--documenter-dark .button.is-light.is-hovered{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus,html.theme--documenter-dark .button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus:not(:active),html.theme--documenter-dark .button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light.is-active{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:#ecf0f1;box-shadow:none}html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-outlined.is-focused{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-dark,html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover,html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus:not(:active),html.theme--documenter-dark .content kbd.button:focus:not(:active),html.theme--documenter-dark .button.is-dark.is-focused:not(:active),html.theme--documenter-dark .content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark[disabled],html.theme--documenter-dark .content kbd.button[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark,fieldset[disabled] html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:#282f2f;box-shadow:none}html.theme--documenter-dark .button.is-dark.is-inverted,html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted:hover,html.theme--documenter-dark .content kbd.button.is-inverted:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-dark.is-inverted[disabled],html.theme--documenter-dark .content kbd.button.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-loading::after,html.theme--documenter-dark .content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined,html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-outlined.is-focused{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus:not(:active),html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus:not(:active),html.theme--documenter-dark .button.is-primary.is-focused:not(:active),html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary[disabled],html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;box-shadow:none}html.theme--documenter-dark .button.is-primary.is-inverted,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}html.theme--documenter-dark .button.is-primary.is-inverted[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:hover,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-light.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e8eef5;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:active,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-light.is-active,html.theme--documenter-dark .docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#dfe8f1;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:hover,html.theme--documenter-dark .button.is-link.is-hovered{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus,html.theme--documenter-dark .button.is-link.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus:not(:active),html.theme--documenter-dark .button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link.is-active{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:#1abc9c;box-shadow:none}html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-link.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-outlined.is-focused{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:hover,html.theme--documenter-dark .button.is-link.is-light.is-hovered{background-color:#e2fbf6;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:active,html.theme--documenter-dark .button.is-link.is-light.is-active{background-color:#d7f9f3;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:hover,html.theme--documenter-dark .button.is-info.is-hovered{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus,html.theme--documenter-dark .button.is-info.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus:not(:active),html.theme--documenter-dark .button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info.is-active{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:#024c7d;box-shadow:none}html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-info.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;color:#024c7d}html.theme--documenter-dark .button.is-info.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-outlined.is-focused{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:hover,html.theme--documenter-dark .button.is-info.is-light.is-hovered{background-color:#def2fe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:active,html.theme--documenter-dark .button.is-info.is-light.is-active{background-color:#d2edfe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:hover,html.theme--documenter-dark .button.is-success.is-hovered{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus,html.theme--documenter-dark .button.is-success.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus:not(:active),html.theme--documenter-dark .button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success.is-active{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:#008438;box-shadow:none}html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-success.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;color:#008438}html.theme--documenter-dark .button.is-success.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-outlined.is-focused{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:hover,html.theme--documenter-dark .button.is-success.is-light.is-hovered{background-color:#deffec;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:active,html.theme--documenter-dark .button.is-success.is-light.is-active{background-color:#d1ffe5;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:hover,html.theme--documenter-dark .button.is-warning.is-hovered{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus,html.theme--documenter-dark .button.is-warning.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus:not(:active),html.theme--documenter-dark .button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning.is-active{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:#ad8100;box-shadow:none}html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-warning.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-outlined.is-focused{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-focused{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:hover,html.theme--documenter-dark .button.is-warning.is-light.is-hovered{background-color:#fff7de;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:active,html.theme--documenter-dark .button.is-warning.is-light.is-active{background-color:#fff3d1;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:hover,html.theme--documenter-dark .button.is-danger.is-hovered{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus,html.theme--documenter-dark .button.is-danger.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus:not(:active),html.theme--documenter-dark .button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger.is-active{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;box-shadow:none}html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-danger.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-outlined.is-focused{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:hover,html.theme--documenter-dark .button.is-danger.is-light.is-hovered{background-color:#fce3e0;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:active,html.theme--documenter-dark .button.is-danger.is-light.is-active{background-color:#fcd8d5;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}html.theme--documenter-dark .button.is-small:not(.is-rounded),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:3px}html.theme--documenter-dark .button.is-normal{font-size:1rem}html.theme--documenter-dark .button.is-medium{font-size:1.25rem}html.theme--documenter-dark .button.is-large{font-size:1.5rem}html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .button{background-color:#8c9b9d;border-color:#5e6d6f;box-shadow:none;opacity:.5}html.theme--documenter-dark .button.is-fullwidth{display:flex;width:100%}html.theme--documenter-dark .button.is-loading{color:transparent !important;pointer-events:none}html.theme--documenter-dark .button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}html.theme--documenter-dark .button.is-static{background-color:#282f2f;border-color:#5e6d6f;color:#dbdee0;box-shadow:none;pointer-events:none}html.theme--documenter-dark .button.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}html.theme--documenter-dark .buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .buttons .button{margin-bottom:0.5rem}html.theme--documenter-dark .buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}html.theme--documenter-dark .buttons:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .buttons:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:3px}html.theme--documenter-dark .buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}html.theme--documenter-dark .buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}html.theme--documenter-dark .buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}html.theme--documenter-dark .buttons.has-addons .button:last-child{margin-right:0}html.theme--documenter-dark .buttons.has-addons .button:hover,html.theme--documenter-dark .buttons.has-addons .button.is-hovered{z-index:2}html.theme--documenter-dark .buttons.has-addons .button:focus,html.theme--documenter-dark .buttons.has-addons .button.is-focused,html.theme--documenter-dark .buttons.has-addons .button:active,html.theme--documenter-dark .buttons.has-addons .button.is-active,html.theme--documenter-dark .buttons.has-addons .button.is-selected{z-index:3}html.theme--documenter-dark .buttons.has-addons .button:focus:hover,html.theme--documenter-dark .buttons.has-addons .button.is-focused:hover,html.theme--documenter-dark .buttons.has-addons .button:active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-selected:hover{z-index:4}html.theme--documenter-dark .buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .buttons.is-centered{justify-content:center}html.theme--documenter-dark .buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}html.theme--documenter-dark .buttons.is-right{justify-content:flex-end}html.theme--documenter-dark .buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:1rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1.25rem}}html.theme--documenter-dark .container{flex-grow:1;margin:0 auto;position:relative;width:auto}html.theme--documenter-dark .container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){html.theme--documenter-dark .container{max-width:992px}}@media screen and (max-width: 1215px){html.theme--documenter-dark .container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){html.theme--documenter-dark .container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){html.theme--documenter-dark .container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){html.theme--documenter-dark .container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}html.theme--documenter-dark .content li+li{margin-top:0.25em}html.theme--documenter-dark .content p:not(:last-child),html.theme--documenter-dark .content dl:not(:last-child),html.theme--documenter-dark .content ol:not(:last-child),html.theme--documenter-dark .content ul:not(:last-child),html.theme--documenter-dark .content blockquote:not(:last-child),html.theme--documenter-dark .content pre:not(:last-child),html.theme--documenter-dark .content table:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .content h1,html.theme--documenter-dark .content h2,html.theme--documenter-dark .content h3,html.theme--documenter-dark .content h4,html.theme--documenter-dark .content h5,html.theme--documenter-dark .content h6{color:#f2f2f2;font-weight:600;line-height:1.125}html.theme--documenter-dark .content h1{font-size:2em;margin-bottom:0.5em}html.theme--documenter-dark .content h1:not(:first-child){margin-top:1em}html.theme--documenter-dark .content h2{font-size:1.75em;margin-bottom:0.5714em}html.theme--documenter-dark .content h2:not(:first-child){margin-top:1.1428em}html.theme--documenter-dark .content h3{font-size:1.5em;margin-bottom:0.6666em}html.theme--documenter-dark .content h3:not(:first-child){margin-top:1.3333em}html.theme--documenter-dark .content h4{font-size:1.25em;margin-bottom:0.8em}html.theme--documenter-dark .content h5{font-size:1.125em;margin-bottom:0.8888em}html.theme--documenter-dark .content h6{font-size:1em;margin-bottom:1em}html.theme--documenter-dark .content blockquote{background-color:#282f2f;border-left:5px solid #5e6d6f;padding:1.25em 1.5em}html.theme--documenter-dark .content ol{list-style-position:outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ol:not([type]){list-style-type:decimal}html.theme--documenter-dark .content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}html.theme--documenter-dark .content ol.is-lower-roman:not([type]){list-style-type:lower-roman}html.theme--documenter-dark .content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}html.theme--documenter-dark .content ol.is-upper-roman:not([type]){list-style-type:upper-roman}html.theme--documenter-dark .content ul{list-style:disc outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ul ul{list-style-type:circle;margin-top:0.5em}html.theme--documenter-dark .content ul ul ul{list-style-type:square}html.theme--documenter-dark .content dd{margin-left:2em}html.theme--documenter-dark .content figure{margin-left:2em;margin-right:2em;text-align:center}html.theme--documenter-dark .content figure:not(:first-child){margin-top:2em}html.theme--documenter-dark .content figure:not(:last-child){margin-bottom:2em}html.theme--documenter-dark .content figure img{display:inline-block}html.theme--documenter-dark .content figure figcaption{font-style:italic}html.theme--documenter-dark .content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}html.theme--documenter-dark .content sup,html.theme--documenter-dark .content sub{font-size:75%}html.theme--documenter-dark .content table{width:100%}html.theme--documenter-dark .content table td,html.theme--documenter-dark .content table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .content table th{color:#f2f2f2}html.theme--documenter-dark .content table th:not([align]){text-align:inherit}html.theme--documenter-dark .content table thead td,html.theme--documenter-dark .content table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .content table tfoot td,html.theme--documenter-dark .content table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .content table tbody tr:last-child td,html.theme--documenter-dark .content table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .content .tabs li+li{margin-top:0}html.theme--documenter-dark .content.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}html.theme--documenter-dark .content.is-normal{font-size:1rem}html.theme--documenter-dark .content.is-medium{font-size:1.25rem}html.theme--documenter-dark .content.is-large{font-size:1.5rem}html.theme--documenter-dark .icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}html.theme--documenter-dark .icon.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}html.theme--documenter-dark .icon.is-medium{height:2rem;width:2rem}html.theme--documenter-dark .icon.is-large{height:3rem;width:3rem}html.theme--documenter-dark .icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}html.theme--documenter-dark .icon-text .icon{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .icon-text .icon:not(:last-child){margin-right:.25em}html.theme--documenter-dark .icon-text .icon:not(:first-child){margin-left:.25em}html.theme--documenter-dark div.icon-text{display:flex}html.theme--documenter-dark .image,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{display:block;position:relative}html.theme--documenter-dark .image img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}html.theme--documenter-dark .image img.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}html.theme--documenter-dark .image.is-fullwidth,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}html.theme--documenter-dark .image.is-square,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square,html.theme--documenter-dark .image.is-1by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}html.theme--documenter-dark .image.is-5by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}html.theme--documenter-dark .image.is-4by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}html.theme--documenter-dark .image.is-3by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}html.theme--documenter-dark .image.is-5by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}html.theme--documenter-dark .image.is-16by9,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}html.theme--documenter-dark .image.is-2by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}html.theme--documenter-dark .image.is-3by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}html.theme--documenter-dark .image.is-4by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}html.theme--documenter-dark .image.is-3by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}html.theme--documenter-dark .image.is-2by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}html.theme--documenter-dark .image.is-3by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}html.theme--documenter-dark .image.is-9by16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}html.theme--documenter-dark .image.is-1by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}html.theme--documenter-dark .image.is-1by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}html.theme--documenter-dark .image.is-16x16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}html.theme--documenter-dark .image.is-24x24,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}html.theme--documenter-dark .image.is-32x32,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}html.theme--documenter-dark .image.is-48x48,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}html.theme--documenter-dark .image.is-64x64,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}html.theme--documenter-dark .image.is-96x96,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}html.theme--documenter-dark .image.is-128x128,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}html.theme--documenter-dark .notification{background-color:#282f2f;border-radius:.4em;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}html.theme--documenter-dark .notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .notification strong{color:currentColor}html.theme--documenter-dark .notification code,html.theme--documenter-dark .notification pre{background:#fff}html.theme--documenter-dark .notification pre code{background:transparent}html.theme--documenter-dark .notification>.delete{right:.5rem;position:absolute;top:0.5rem}html.theme--documenter-dark .notification .title,html.theme--documenter-dark .notification .subtitle,html.theme--documenter-dark .notification .content{color:currentColor}html.theme--documenter-dark .notification.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .notification.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .notification.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .notification.is-dark,html.theme--documenter-dark .content kbd.notification{background-color:#282f2f;color:#fff}html.theme--documenter-dark .notification.is-primary,html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .notification.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.notification.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .notification.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .notification.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .notification.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .notification.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .notification.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .notification.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .notification.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .notification.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .notification.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .notification.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}html.theme--documenter-dark .progress::-webkit-progress-bar{background-color:#343c3d}html.theme--documenter-dark .progress::-webkit-progress-value{background-color:#dbdee0}html.theme--documenter-dark .progress::-moz-progress-bar{background-color:#dbdee0}html.theme--documenter-dark .progress::-ms-fill{background-color:#dbdee0;border:none}html.theme--documenter-dark .progress.is-white::-webkit-progress-value{background-color:#fff}html.theme--documenter-dark .progress.is-white::-moz-progress-bar{background-color:#fff}html.theme--documenter-dark .progress.is-white::-ms-fill{background-color:#fff}html.theme--documenter-dark .progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-black::-webkit-progress-value{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-moz-progress-bar{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-ms-fill{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-light::-webkit-progress-value{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-moz-progress-bar{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-ms-fill{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light:indeterminate{background-image:linear-gradient(to right, #ecf0f1 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-dark::-webkit-progress-value,html.theme--documenter-dark .content kbd.progress::-webkit-progress-value{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-moz-progress-bar,html.theme--documenter-dark .content kbd.progress::-moz-progress-bar{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-ms-fill,html.theme--documenter-dark .content kbd.progress::-ms-fill{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark:indeterminate,html.theme--documenter-dark .content kbd.progress:indeterminate{background-image:linear-gradient(to right, #282f2f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-primary::-webkit-progress-value,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-moz-progress-bar,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-ms-fill,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary:indeterminate,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #375a7f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-link::-webkit-progress-value{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-moz-progress-bar{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-ms-fill{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link:indeterminate{background-image:linear-gradient(to right, #1abc9c 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-info::-webkit-progress-value{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-moz-progress-bar{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-ms-fill{background-color:#024c7d}html.theme--documenter-dark .progress.is-info:indeterminate{background-image:linear-gradient(to right, #024c7d 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-success::-webkit-progress-value{background-color:#008438}html.theme--documenter-dark .progress.is-success::-moz-progress-bar{background-color:#008438}html.theme--documenter-dark .progress.is-success::-ms-fill{background-color:#008438}html.theme--documenter-dark .progress.is-success:indeterminate{background-image:linear-gradient(to right, #008438 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-warning::-webkit-progress-value{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-moz-progress-bar{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-ms-fill{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ad8100 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-danger::-webkit-progress-value{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-moz-progress-bar{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-ms-fill{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger:indeterminate{background-image:linear-gradient(to right, #9e1b0d 30%, #343c3d 30%)}html.theme--documenter-dark .progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#343c3d;background-image:linear-gradient(to right, #fff 30%, #343c3d 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}html.theme--documenter-dark .progress:indeterminate::-webkit-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-moz-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-ms-fill{animation-name:none}html.theme--documenter-dark .progress.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}html.theme--documenter-dark .progress.is-medium{height:1.25rem}html.theme--documenter-dark .progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}html.theme--documenter-dark .table{background-color:#343c3d;color:#fff}html.theme--documenter-dark .table td,html.theme--documenter-dark .table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .table td.is-white,html.theme--documenter-dark .table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .table td.is-black,html.theme--documenter-dark .table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .table td.is-light,html.theme--documenter-dark .table th.is-light{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .table td.is-dark,html.theme--documenter-dark .table th.is-dark{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .table td.is-primary,html.theme--documenter-dark .table th.is-primary{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-link,html.theme--documenter-dark .table th.is-link{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .table td.is-info,html.theme--documenter-dark .table th.is-info{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .table td.is-success,html.theme--documenter-dark .table th.is-success{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .table td.is-warning,html.theme--documenter-dark .table th.is-warning{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .table td.is-danger,html.theme--documenter-dark .table th.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .table td.is-narrow,html.theme--documenter-dark .table th.is-narrow{white-space:nowrap;width:1%}html.theme--documenter-dark .table td.is-selected,html.theme--documenter-dark .table th.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-selected a,html.theme--documenter-dark .table td.is-selected strong,html.theme--documenter-dark .table th.is-selected a,html.theme--documenter-dark .table th.is-selected strong{color:currentColor}html.theme--documenter-dark .table td.is-vcentered,html.theme--documenter-dark .table th.is-vcentered{vertical-align:middle}html.theme--documenter-dark .table th{color:#f2f2f2}html.theme--documenter-dark .table th:not([align]){text-align:left}html.theme--documenter-dark .table tr.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table tr.is-selected a,html.theme--documenter-dark .table tr.is-selected strong{color:currentColor}html.theme--documenter-dark .table tr.is-selected td,html.theme--documenter-dark .table tr.is-selected th{border-color:#fff;color:currentColor}html.theme--documenter-dark .table thead{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table thead td,html.theme--documenter-dark .table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .table tfoot{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tfoot td,html.theme--documenter-dark .table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .table tbody{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tbody tr:last-child td,html.theme--documenter-dark .table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .table.is-bordered td,html.theme--documenter-dark .table.is-bordered th{border-width:1px}html.theme--documenter-dark .table.is-bordered tr:last-child td,html.theme--documenter-dark .table.is-bordered tr:last-child th{border-bottom-width:1px}html.theme--documenter-dark .table.is-fullwidth{width:100%}html.theme--documenter-dark .table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#2d3435}html.theme--documenter-dark .table.is-narrow td,html.theme--documenter-dark .table.is-narrow th{padding:0.25em 0.5em}html.theme--documenter-dark .table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#282f2f}html.theme--documenter-dark .table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}html.theme--documenter-dark .tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .tags .tag,html.theme--documenter-dark .tags .content kbd,html.theme--documenter-dark .content .tags kbd,html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}html.theme--documenter-dark .tags .tag:not(:last-child),html.theme--documenter-dark .tags .content kbd:not(:last-child),html.theme--documenter-dark .content .tags kbd:not(:last-child),html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}html.theme--documenter-dark .tags:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .tags:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .tags.are-medium .tag:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .content kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .content .tags.are-medium kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}html.theme--documenter-dark .tags.are-large .tag:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .content kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .content .tags.are-large kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}html.theme--documenter-dark .tags.is-centered{justify-content:center}html.theme--documenter-dark .tags.is-centered .tag,html.theme--documenter-dark .tags.is-centered .content kbd,html.theme--documenter-dark .content .tags.is-centered kbd,html.theme--documenter-dark .tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}html.theme--documenter-dark .tags.is-right{justify-content:flex-end}html.theme--documenter-dark .tags.is-right .tag:not(:first-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:first-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}html.theme--documenter-dark .tags.is-right .tag:not(:last-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:last-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}html.theme--documenter-dark .tags.has-addons .tag,html.theme--documenter-dark .tags.has-addons .content kbd,html.theme--documenter-dark .content .tags.has-addons kbd,html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}html.theme--documenter-dark .tags.has-addons .tag:not(:first-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:first-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}html.theme--documenter-dark .tags.has-addons .tag:not(:last-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:last-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}html.theme--documenter-dark .tag:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#282f2f;border-radius:.4em;color:#fff;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}html.theme--documenter-dark .tag:not(body) .delete,html.theme--documenter-dark .content kbd:not(body) .delete,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}html.theme--documenter-dark .tag.is-white:not(body),html.theme--documenter-dark .content kbd.is-white:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .tag.is-black:not(body),html.theme--documenter-dark .content kbd.is-black:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .tag.is-light:not(body),html.theme--documenter-dark .content kbd.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .tag.is-dark:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-dark:not(body),html.theme--documenter-dark .content .docstring>section>kbd:not(body){background-color:#282f2f;color:#fff}html.theme--documenter-dark .tag.is-primary:not(body),html.theme--documenter-dark .content kbd.is-primary:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){background-color:#375a7f;color:#fff}html.theme--documenter-dark .tag.is-primary.is-light:not(body),html.theme--documenter-dark .content kbd.is-primary.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .tag.is-link:not(body),html.theme--documenter-dark .content kbd.is-link:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#1abc9c;color:#fff}html.theme--documenter-dark .tag.is-link.is-light:not(body),html.theme--documenter-dark .content kbd.is-link.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .tag.is-info:not(body),html.theme--documenter-dark .content kbd.is-info:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#024c7d;color:#fff}html.theme--documenter-dark .tag.is-info.is-light:not(body),html.theme--documenter-dark .content kbd.is-info.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .tag.is-success:not(body),html.theme--documenter-dark .content kbd.is-success:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#008438;color:#fff}html.theme--documenter-dark .tag.is-success.is-light:not(body),html.theme--documenter-dark .content kbd.is-success.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .tag.is-warning:not(body),html.theme--documenter-dark .content kbd.is-warning:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ad8100;color:#fff}html.theme--documenter-dark .tag.is-warning.is-light:not(body),html.theme--documenter-dark .content kbd.is-warning.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .tag.is-danger:not(body),html.theme--documenter-dark .content kbd.is-danger:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .tag.is-danger.is-light:not(body),html.theme--documenter-dark .content kbd.is-danger.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .tag.is-normal:not(body),html.theme--documenter-dark .content kbd.is-normal:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}html.theme--documenter-dark .tag.is-medium:not(body),html.theme--documenter-dark .content kbd.is-medium:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}html.theme--documenter-dark .tag.is-large:not(body),html.theme--documenter-dark .content kbd.is-large:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}html.theme--documenter-dark .tag:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .content kbd:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}html.theme--documenter-dark .tag:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .content kbd:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}html.theme--documenter-dark .tag:not(body) .icon:first-child:last-child,html.theme--documenter-dark .content kbd:not(body) .icon:first-child:last-child,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}html.theme--documenter-dark .tag.is-delete:not(body),html.theme--documenter-dark .content kbd.is-delete:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before,html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}html.theme--documenter-dark .tag.is-delete:not(body):hover,html.theme--documenter-dark .content kbd.is-delete:not(body):hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):hover,html.theme--documenter-dark .tag.is-delete:not(body):focus,html.theme--documenter-dark .content kbd.is-delete:not(body):focus,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#1d2122}html.theme--documenter-dark .tag.is-delete:not(body):active,html.theme--documenter-dark .content kbd.is-delete:not(body):active,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#111414}html.theme--documenter-dark .tag.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:not(body),html.theme--documenter-dark .content kbd.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}html.theme--documenter-dark a.tag:hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:hover{text-decoration:underline}html.theme--documenter-dark .title,html.theme--documenter-dark .subtitle{word-break:break-word}html.theme--documenter-dark .title em,html.theme--documenter-dark .title span,html.theme--documenter-dark .subtitle em,html.theme--documenter-dark .subtitle span{font-weight:inherit}html.theme--documenter-dark .title sub,html.theme--documenter-dark .subtitle sub{font-size:.75em}html.theme--documenter-dark .title sup,html.theme--documenter-dark .subtitle sup{font-size:.75em}html.theme--documenter-dark .title .tag,html.theme--documenter-dark .title .content kbd,html.theme--documenter-dark .content .title kbd,html.theme--documenter-dark .title .docstring>section>a.docs-sourcelink,html.theme--documenter-dark .subtitle .tag,html.theme--documenter-dark .subtitle .content kbd,html.theme--documenter-dark .content .subtitle kbd,html.theme--documenter-dark .subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}html.theme--documenter-dark .title{color:#fff;font-size:2rem;font-weight:500;line-height:1.125}html.theme--documenter-dark .title strong{color:inherit;font-weight:inherit}html.theme--documenter-dark .title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}html.theme--documenter-dark .title.is-1{font-size:3rem}html.theme--documenter-dark .title.is-2{font-size:2.5rem}html.theme--documenter-dark .title.is-3{font-size:2rem}html.theme--documenter-dark .title.is-4{font-size:1.5rem}html.theme--documenter-dark .title.is-5{font-size:1.25rem}html.theme--documenter-dark .title.is-6{font-size:1rem}html.theme--documenter-dark .title.is-7{font-size:.75rem}html.theme--documenter-dark .subtitle{color:#8c9b9d;font-size:1.25rem;font-weight:400;line-height:1.25}html.theme--documenter-dark .subtitle strong{color:#8c9b9d;font-weight:600}html.theme--documenter-dark .subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}html.theme--documenter-dark .subtitle.is-1{font-size:3rem}html.theme--documenter-dark .subtitle.is-2{font-size:2.5rem}html.theme--documenter-dark .subtitle.is-3{font-size:2rem}html.theme--documenter-dark .subtitle.is-4{font-size:1.5rem}html.theme--documenter-dark .subtitle.is-5{font-size:1.25rem}html.theme--documenter-dark .subtitle.is-6{font-size:1rem}html.theme--documenter-dark .subtitle.is-7{font-size:.75rem}html.theme--documenter-dark .heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}html.theme--documenter-dark .number{align-items:center;background-color:#282f2f;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#1f2424;border-color:#5e6d6f;border-radius:.4em;color:#dbdee0}html.theme--documenter-dark .select select::-moz-placeholder,html.theme--documenter-dark .textarea::-moz-placeholder,html.theme--documenter-dark .input::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select::-webkit-input-placeholder,html.theme--documenter-dark .textarea::-webkit-input-placeholder,html.theme--documenter-dark .input::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:-moz-placeholder,html.theme--documenter-dark .textarea:-moz-placeholder,html.theme--documenter-dark .input:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select:-ms-input-placeholder,html.theme--documenter-dark .textarea:-ms-input-placeholder,html.theme--documenter-dark .input:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:hover,html.theme--documenter-dark .textarea:hover,html.theme--documenter-dark .input:hover,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:hover,html.theme--documenter-dark .select select.is-hovered,html.theme--documenter-dark .is-hovered.textarea,html.theme--documenter-dark .is-hovered.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#8c9b9d}html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{border-color:#1abc9c;box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#8c9b9d;border-color:#282f2f;box-shadow:none;color:#fff}html.theme--documenter-dark .select select[disabled]::-moz-placeholder,html.theme--documenter-dark .textarea[disabled]::-moz-placeholder,html.theme--documenter-dark .input[disabled]::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .textarea[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .input[disabled]::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-moz-placeholder,html.theme--documenter-dark .textarea[disabled]:-moz-placeholder,html.theme--documenter-dark .input[disabled]:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-ms-input-placeholder,html.theme--documenter-dark .textarea[disabled]:-ms-input-placeholder,html.theme--documenter-dark .input[disabled]:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}html.theme--documenter-dark .textarea[readonly],html.theme--documenter-dark .input[readonly],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}html.theme--documenter-dark .is-white.textarea,html.theme--documenter-dark .is-white.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}html.theme--documenter-dark .is-white.textarea:focus,html.theme--documenter-dark .is-white.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:focus,html.theme--documenter-dark .is-white.is-focused.textarea,html.theme--documenter-dark .is-white.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-white.textarea:active,html.theme--documenter-dark .is-white.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:active,html.theme--documenter-dark .is-white.is-active.textarea,html.theme--documenter-dark .is-white.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .is-black.textarea,html.theme--documenter-dark .is-black.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}html.theme--documenter-dark .is-black.textarea:focus,html.theme--documenter-dark .is-black.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:focus,html.theme--documenter-dark .is-black.is-focused.textarea,html.theme--documenter-dark .is-black.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-black.textarea:active,html.theme--documenter-dark .is-black.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:active,html.theme--documenter-dark .is-black.is-active.textarea,html.theme--documenter-dark .is-black.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .is-light.textarea,html.theme--documenter-dark .is-light.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light{border-color:#ecf0f1}html.theme--documenter-dark .is-light.textarea:focus,html.theme--documenter-dark .is-light.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:focus,html.theme--documenter-dark .is-light.is-focused.textarea,html.theme--documenter-dark .is-light.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-light.textarea:active,html.theme--documenter-dark .is-light.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:active,html.theme--documenter-dark .is-light.is-active.textarea,html.theme--documenter-dark .is-light.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .is-dark.textarea,html.theme--documenter-dark .content kbd.textarea,html.theme--documenter-dark .is-dark.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark,html.theme--documenter-dark .content kbd.input{border-color:#282f2f}html.theme--documenter-dark .is-dark.textarea:focus,html.theme--documenter-dark .content kbd.textarea:focus,html.theme--documenter-dark .is-dark.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:focus,html.theme--documenter-dark .content kbd.input:focus,html.theme--documenter-dark .is-dark.is-focused.textarea,html.theme--documenter-dark .content kbd.is-focused.textarea,html.theme--documenter-dark .is-dark.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .content kbd.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-focused,html.theme--documenter-dark .is-dark.textarea:active,html.theme--documenter-dark .content kbd.textarea:active,html.theme--documenter-dark .is-dark.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:active,html.theme--documenter-dark .content kbd.input:active,html.theme--documenter-dark .is-dark.is-active.textarea,html.theme--documenter-dark .content kbd.is-active.textarea,html.theme--documenter-dark .is-dark.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .content kbd.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .is-primary.textarea,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink{border-color:#375a7f}html.theme--documenter-dark .is-primary.textarea:focus,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:focus,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.is-focused.textarea,html.theme--documenter-dark .docstring>section>a.is-focused.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .docstring>section>a.is-focused.input.docs-sourcelink,html.theme--documenter-dark .is-primary.textarea:active,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:active,html.theme--documenter-dark .is-primary.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:active,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:active,html.theme--documenter-dark .is-primary.is-active.textarea,html.theme--documenter-dark .docstring>section>a.is-active.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .is-link.textarea,html.theme--documenter-dark .is-link.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link{border-color:#1abc9c}html.theme--documenter-dark .is-link.textarea:focus,html.theme--documenter-dark .is-link.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:focus,html.theme--documenter-dark .is-link.is-focused.textarea,html.theme--documenter-dark .is-link.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-link.textarea:active,html.theme--documenter-dark .is-link.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:active,html.theme--documenter-dark .is-link.is-active.textarea,html.theme--documenter-dark .is-link.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .is-info.textarea,html.theme--documenter-dark .is-info.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info{border-color:#024c7d}html.theme--documenter-dark .is-info.textarea:focus,html.theme--documenter-dark .is-info.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:focus,html.theme--documenter-dark .is-info.is-focused.textarea,html.theme--documenter-dark .is-info.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-info.textarea:active,html.theme--documenter-dark .is-info.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:active,html.theme--documenter-dark .is-info.is-active.textarea,html.theme--documenter-dark .is-info.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .is-success.textarea,html.theme--documenter-dark .is-success.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success{border-color:#008438}html.theme--documenter-dark .is-success.textarea:focus,html.theme--documenter-dark .is-success.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:focus,html.theme--documenter-dark .is-success.is-focused.textarea,html.theme--documenter-dark .is-success.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-success.textarea:active,html.theme--documenter-dark .is-success.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:active,html.theme--documenter-dark .is-success.is-active.textarea,html.theme--documenter-dark .is-success.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .is-warning.textarea,html.theme--documenter-dark .is-warning.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ad8100}html.theme--documenter-dark .is-warning.textarea:focus,html.theme--documenter-dark .is-warning.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:focus,html.theme--documenter-dark .is-warning.is-focused.textarea,html.theme--documenter-dark .is-warning.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-warning.textarea:active,html.theme--documenter-dark .is-warning.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:active,html.theme--documenter-dark .is-warning.is-active.textarea,html.theme--documenter-dark .is-warning.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .is-danger.textarea,html.theme--documenter-dark .is-danger.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#9e1b0d}html.theme--documenter-dark .is-danger.textarea:focus,html.theme--documenter-dark .is-danger.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:focus,html.theme--documenter-dark .is-danger.is-focused.textarea,html.theme--documenter-dark .is-danger.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-danger.textarea:active,html.theme--documenter-dark .is-danger.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:active,html.theme--documenter-dark .is-danger.is-active.textarea,html.theme--documenter-dark .is-danger.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .is-small.textarea,html.theme--documenter-dark .is-small.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .is-medium.textarea,html.theme--documenter-dark .is-medium.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}html.theme--documenter-dark .is-large.textarea,html.theme--documenter-dark .is-large.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}html.theme--documenter-dark .is-fullwidth.textarea,html.theme--documenter-dark .is-fullwidth.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}html.theme--documenter-dark .is-inline.textarea,html.theme--documenter-dark .is-inline.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}html.theme--documenter-dark .input.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}html.theme--documenter-dark .input.is-static,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}html.theme--documenter-dark .textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}html.theme--documenter-dark .textarea:not([rows]){max-height:40em;min-height:8em}html.theme--documenter-dark .textarea[rows]{height:initial}html.theme--documenter-dark .textarea.has-fixed-size{resize:none}html.theme--documenter-dark .radio,html.theme--documenter-dark .checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}html.theme--documenter-dark .radio input,html.theme--documenter-dark .checkbox input{cursor:pointer}html.theme--documenter-dark .radio:hover,html.theme--documenter-dark .checkbox:hover{color:#8c9b9d}html.theme--documenter-dark .radio[disabled],html.theme--documenter-dark .checkbox[disabled],fieldset[disabled] html.theme--documenter-dark .radio,fieldset[disabled] html.theme--documenter-dark .checkbox,html.theme--documenter-dark .radio input[disabled],html.theme--documenter-dark .checkbox input[disabled]{color:#fff;cursor:not-allowed}html.theme--documenter-dark .radio+.radio{margin-left:.5em}html.theme--documenter-dark .select{display:inline-block;max-width:100%;position:relative;vertical-align:top}html.theme--documenter-dark .select:not(.is-multiple){height:2.5em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border-color:#1abc9c;right:1.125em;z-index:4}html.theme--documenter-dark .select.is-rounded select,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}html.theme--documenter-dark .select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}html.theme--documenter-dark .select select::-ms-expand{display:none}html.theme--documenter-dark .select select[disabled]:hover,fieldset[disabled] html.theme--documenter-dark .select select:hover{border-color:#282f2f}html.theme--documenter-dark .select select:not([multiple]){padding-right:2.5em}html.theme--documenter-dark .select select[multiple]{height:auto;padding:0}html.theme--documenter-dark .select select[multiple] option{padding:0.5em 1em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading):hover::after{border-color:#8c9b9d}html.theme--documenter-dark .select.is-white:not(:hover)::after{border-color:#fff}html.theme--documenter-dark .select.is-white select{border-color:#fff}html.theme--documenter-dark .select.is-white select:hover,html.theme--documenter-dark .select.is-white select.is-hovered{border-color:#f2f2f2}html.theme--documenter-dark .select.is-white select:focus,html.theme--documenter-dark .select.is-white select.is-focused,html.theme--documenter-dark .select.is-white select:active,html.theme--documenter-dark .select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .select.is-black:not(:hover)::after{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select:hover,html.theme--documenter-dark .select.is-black select.is-hovered{border-color:#000}html.theme--documenter-dark .select.is-black select:focus,html.theme--documenter-dark .select.is-black select.is-focused,html.theme--documenter-dark .select.is-black select:active,html.theme--documenter-dark .select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .select.is-light:not(:hover)::after{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select:hover,html.theme--documenter-dark .select.is-light select.is-hovered{border-color:#dde4e6}html.theme--documenter-dark .select.is-light select:focus,html.theme--documenter-dark .select.is-light select.is-focused,html.theme--documenter-dark .select.is-light select:active,html.theme--documenter-dark .select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .select.is-dark:not(:hover)::after,html.theme--documenter-dark .content kbd.select:not(:hover)::after{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select,html.theme--documenter-dark .content kbd.select select{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select:hover,html.theme--documenter-dark .content kbd.select select:hover,html.theme--documenter-dark .select.is-dark select.is-hovered,html.theme--documenter-dark .content kbd.select select.is-hovered{border-color:#1d2122}html.theme--documenter-dark .select.is-dark select:focus,html.theme--documenter-dark .content kbd.select select:focus,html.theme--documenter-dark .select.is-dark select.is-focused,html.theme--documenter-dark .content kbd.select select.is-focused,html.theme--documenter-dark .select.is-dark select:active,html.theme--documenter-dark .content kbd.select select:active,html.theme--documenter-dark .select.is-dark select.is-active,html.theme--documenter-dark .content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .select.is-primary:not(:hover)::after,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select:hover,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:hover,html.theme--documenter-dark .select.is-primary select.is-hovered,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#2f4d6d}html.theme--documenter-dark .select.is-primary select:focus,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:focus,html.theme--documenter-dark .select.is-primary select.is-focused,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-focused,html.theme--documenter-dark .select.is-primary select:active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:active,html.theme--documenter-dark .select.is-primary select.is-active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .select.is-link:not(:hover)::after{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select:hover,html.theme--documenter-dark .select.is-link select.is-hovered{border-color:#17a689}html.theme--documenter-dark .select.is-link select:focus,html.theme--documenter-dark .select.is-link select.is-focused,html.theme--documenter-dark .select.is-link select:active,html.theme--documenter-dark .select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select.is-info:not(:hover)::after{border-color:#024c7d}html.theme--documenter-dark .select.is-info select{border-color:#024c7d}html.theme--documenter-dark .select.is-info select:hover,html.theme--documenter-dark .select.is-info select.is-hovered{border-color:#023d64}html.theme--documenter-dark .select.is-info select:focus,html.theme--documenter-dark .select.is-info select.is-focused,html.theme--documenter-dark .select.is-info select:active,html.theme--documenter-dark .select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .select.is-success:not(:hover)::after{border-color:#008438}html.theme--documenter-dark .select.is-success select{border-color:#008438}html.theme--documenter-dark .select.is-success select:hover,html.theme--documenter-dark .select.is-success select.is-hovered{border-color:#006b2d}html.theme--documenter-dark .select.is-success select:focus,html.theme--documenter-dark .select.is-success select.is-focused,html.theme--documenter-dark .select.is-success select:active,html.theme--documenter-dark .select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .select.is-warning:not(:hover)::after{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select:hover,html.theme--documenter-dark .select.is-warning select.is-hovered{border-color:#946e00}html.theme--documenter-dark .select.is-warning select:focus,html.theme--documenter-dark .select.is-warning select.is-focused,html.theme--documenter-dark .select.is-warning select:active,html.theme--documenter-dark .select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .select.is-danger:not(:hover)::after{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select:hover,html.theme--documenter-dark .select.is-danger select.is-hovered{border-color:#86170b}html.theme--documenter-dark .select.is-danger select:focus,html.theme--documenter-dark .select.is-danger select.is-focused,html.theme--documenter-dark .select.is-danger select:active,html.theme--documenter-dark .select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .select.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .select.is-medium{font-size:1.25rem}html.theme--documenter-dark .select.is-large{font-size:1.5rem}html.theme--documenter-dark .select.is-disabled::after{border-color:#fff !important;opacity:0.5}html.theme--documenter-dark .select.is-fullwidth{width:100%}html.theme--documenter-dark .select.is-fullwidth select{width:100%}html.theme--documenter-dark .select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}html.theme--documenter-dark .select.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .select.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .select.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}html.theme--documenter-dark .file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:hover .file-cta,html.theme--documenter-dark .file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:focus .file-cta,html.theme--documenter-dark .file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}html.theme--documenter-dark .file.is-white:active .file-cta,html.theme--documenter-dark .file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:hover .file-cta,html.theme--documenter-dark .file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:focus .file-cta,html.theme--documenter-dark .file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}html.theme--documenter-dark .file.is-black:active .file-cta,html.theme--documenter-dark .file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-light .file-cta{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:hover .file-cta,html.theme--documenter-dark .file.is-light.is-hovered .file-cta{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:focus .file-cta,html.theme--documenter-dark .file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(236,240,241,0.25);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:active .file-cta,html.theme--documenter-dark .file.is-light.is-active .file-cta{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-dark .file-cta,html.theme--documenter-dark .content kbd.file .file-cta{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:hover .file-cta,html.theme--documenter-dark .content kbd.file:hover .file-cta,html.theme--documenter-dark .file.is-dark.is-hovered .file-cta,html.theme--documenter-dark .content kbd.file.is-hovered .file-cta{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:focus .file-cta,html.theme--documenter-dark .content kbd.file:focus .file-cta,html.theme--documenter-dark .file.is-dark.is-focused .file-cta,html.theme--documenter-dark .content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(40,47,47,0.25);color:#fff}html.theme--documenter-dark .file.is-dark:active .file-cta,html.theme--documenter-dark .content kbd.file:active .file-cta,html.theme--documenter-dark .file.is-dark.is-active .file-cta,html.theme--documenter-dark .content kbd.file.is-active .file-cta{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink .file-cta{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:hover .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:hover .file-cta,html.theme--documenter-dark .file.is-primary.is-hovered .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:focus .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:focus .file-cta,html.theme--documenter-dark .file.is-primary.is-focused .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(55,90,127,0.25);color:#fff}html.theme--documenter-dark .file.is-primary:active .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:active .file-cta,html.theme--documenter-dark .file.is-primary.is-active .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link .file-cta{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:hover .file-cta,html.theme--documenter-dark .file.is-link.is-hovered .file-cta{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:focus .file-cta,html.theme--documenter-dark .file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(26,188,156,0.25);color:#fff}html.theme--documenter-dark .file.is-link:active .file-cta,html.theme--documenter-dark .file.is-link.is-active .file-cta{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info .file-cta{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:hover .file-cta,html.theme--documenter-dark .file.is-info.is-hovered .file-cta{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:focus .file-cta,html.theme--documenter-dark .file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(2,76,125,0.25);color:#fff}html.theme--documenter-dark .file.is-info:active .file-cta,html.theme--documenter-dark .file.is-info.is-active .file-cta{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success .file-cta{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:hover .file-cta,html.theme--documenter-dark .file.is-success.is-hovered .file-cta{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:focus .file-cta,html.theme--documenter-dark .file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(0,132,56,0.25);color:#fff}html.theme--documenter-dark .file.is-success:active .file-cta,html.theme--documenter-dark .file.is-success.is-active .file-cta{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning .file-cta{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:hover .file-cta,html.theme--documenter-dark .file.is-warning.is-hovered .file-cta{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:focus .file-cta,html.theme--documenter-dark .file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(173,129,0,0.25);color:#fff}html.theme--documenter-dark .file.is-warning:active .file-cta,html.theme--documenter-dark .file.is-warning.is-active .file-cta{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger .file-cta{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:hover .file-cta,html.theme--documenter-dark .file.is-danger.is-hovered .file-cta{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:focus .file-cta,html.theme--documenter-dark .file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(158,27,13,0.25);color:#fff}html.theme--documenter-dark .file.is-danger:active .file-cta,html.theme--documenter-dark .file.is-danger.is-active .file-cta{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}html.theme--documenter-dark .file.is-normal{font-size:1rem}html.theme--documenter-dark .file.is-medium{font-size:1.25rem}html.theme--documenter-dark .file.is-medium .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-large{font-size:1.5rem}html.theme--documenter-dark .file.is-large .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .file.has-name.is-empty .file-cta{border-radius:.4em}html.theme--documenter-dark .file.has-name.is-empty .file-name{display:none}html.theme--documenter-dark .file.is-boxed .file-label{flex-direction:column}html.theme--documenter-dark .file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}html.theme--documenter-dark .file.is-boxed .file-name{border-width:0 1px 1px}html.theme--documenter-dark .file.is-boxed .file-icon{height:1.5em;width:1.5em}html.theme--documenter-dark .file.is-boxed .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-boxed.is-small .file-icon .fa,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}html.theme--documenter-dark .file.is-boxed.is-medium .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.is-boxed.is-large .file-icon .fa{font-size:35px}html.theme--documenter-dark .file.is-boxed.has-name .file-cta{border-radius:.4em .4em 0 0}html.theme--documenter-dark .file.is-boxed.has-name .file-name{border-radius:0 0 .4em .4em;border-width:0 1px 1px}html.theme--documenter-dark .file.is-centered{justify-content:center}html.theme--documenter-dark .file.is-fullwidth .file-label{width:100%}html.theme--documenter-dark .file.is-fullwidth .file-name{flex-grow:1;max-width:none}html.theme--documenter-dark .file.is-right{justify-content:flex-end}html.theme--documenter-dark .file.is-right .file-cta{border-radius:0 .4em .4em 0}html.theme--documenter-dark .file.is-right .file-name{border-radius:.4em 0 0 .4em;border-width:1px 0 1px 1px;order:-1}html.theme--documenter-dark .file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}html.theme--documenter-dark .file-label:hover .file-cta{background-color:#232829;color:#f2f2f2}html.theme--documenter-dark .file-label:hover .file-name{border-color:#596668}html.theme--documenter-dark .file-label:active .file-cta{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .file-label:active .file-name{border-color:#535f61}html.theme--documenter-dark .file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-radius:.4em;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}html.theme--documenter-dark .file-cta{background-color:#282f2f;color:#fff}html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}html.theme--documenter-dark .file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}html.theme--documenter-dark .file-icon .fa{font-size:14px}html.theme--documenter-dark .label{color:#f2f2f2;display:block;font-size:1rem;font-weight:700}html.theme--documenter-dark .label:not(:last-child){margin-bottom:0.5em}html.theme--documenter-dark .label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}html.theme--documenter-dark .label.is-medium{font-size:1.25rem}html.theme--documenter-dark .label.is-large{font-size:1.5rem}html.theme--documenter-dark .help{display:block;font-size:.75rem;margin-top:0.25rem}html.theme--documenter-dark .help.is-white{color:#fff}html.theme--documenter-dark .help.is-black{color:#0a0a0a}html.theme--documenter-dark .help.is-light{color:#ecf0f1}html.theme--documenter-dark .help.is-dark,html.theme--documenter-dark .content kbd.help{color:#282f2f}html.theme--documenter-dark .help.is-primary,html.theme--documenter-dark .docstring>section>a.help.docs-sourcelink{color:#375a7f}html.theme--documenter-dark .help.is-link{color:#1abc9c}html.theme--documenter-dark .help.is-info{color:#024c7d}html.theme--documenter-dark .help.is-success{color:#008438}html.theme--documenter-dark .help.is-warning{color:#ad8100}html.theme--documenter-dark .help.is-danger{color:#9e1b0d}html.theme--documenter-dark .field:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.has-addons{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.has-addons .control:not(:last-child){margin-right:-1px}html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .button,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]){z-index:3}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}html.theme--documenter-dark .field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.has-addons.has-addons-centered{justify-content:center}html.theme--documenter-dark .field.has-addons.has-addons-right{justify-content:flex-end}html.theme--documenter-dark .field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .field.is-grouped{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.is-grouped>.control{flex-shrink:0}html.theme--documenter-dark .field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.is-grouped.is-grouped-centered{justify-content:center}html.theme--documenter-dark .field.is-grouped.is-grouped-right{justify-content:flex-end}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline{flex-wrap:wrap}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:last-child,html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field.is-horizontal{display:flex}}html.theme--documenter-dark .field-label .label{font-size:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}html.theme--documenter-dark .field-label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-normal{padding-top:0.375em}html.theme--documenter-dark .field-label.is-medium{font-size:1.25rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-large{font-size:1.5rem;padding-top:0.375em}}html.theme--documenter-dark .field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}html.theme--documenter-dark .field-body .field{margin-bottom:0}html.theme--documenter-dark .field-body>.field{flex-shrink:1}html.theme--documenter-dark .field-body>.field:not(.is-narrow){flex-grow:1}html.theme--documenter-dark .field-body>.field:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}html.theme--documenter-dark .control.has-icons-left .input:focus~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-left .select:focus~.icon,html.theme--documenter-dark .control.has-icons-right .input:focus~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-right .select:focus~.icon{color:#282f2f}html.theme--documenter-dark .control.has-icons-left .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-small~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-small~.icon{font-size:.75rem}html.theme--documenter-dark .control.has-icons-left .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}html.theme--documenter-dark .control.has-icons-left .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-large~.icon{font-size:1.5rem}html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon{color:#5e6d6f;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}html.theme--documenter-dark .control.has-icons-left .input,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input,html.theme--documenter-dark .control.has-icons-left .select select{padding-left:2.5em}html.theme--documenter-dark .control.has-icons-left .icon.is-left{left:0}html.theme--documenter-dark .control.has-icons-right .input,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input,html.theme--documenter-dark .control.has-icons-right .select select{padding-right:2.5em}html.theme--documenter-dark .control.has-icons-right .icon.is-right{right:0}html.theme--documenter-dark .control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}html.theme--documenter-dark .control.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .control.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .control.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .breadcrumb{font-size:1rem;white-space:nowrap}html.theme--documenter-dark .breadcrumb a{align-items:center;color:#1abc9c;display:flex;justify-content:center;padding:0 .75em}html.theme--documenter-dark .breadcrumb a:hover{color:#1dd2af}html.theme--documenter-dark .breadcrumb li{align-items:center;display:flex}html.theme--documenter-dark .breadcrumb li:first-child a{padding-left:0}html.theme--documenter-dark .breadcrumb li.is-active a{color:#f2f2f2;cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb li+li::before{color:#8c9b9d;content:"\0002f"}html.theme--documenter-dark .breadcrumb ul,html.theme--documenter-dark .breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .breadcrumb .icon:first-child{margin-right:.5em}html.theme--documenter-dark .breadcrumb .icon:last-child{margin-left:.5em}html.theme--documenter-dark .breadcrumb.is-centered ol,html.theme--documenter-dark .breadcrumb.is-centered ul{justify-content:center}html.theme--documenter-dark .breadcrumb.is-right ol,html.theme--documenter-dark .breadcrumb.is-right ul{justify-content:flex-end}html.theme--documenter-dark .breadcrumb.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}html.theme--documenter-dark .breadcrumb.is-medium{font-size:1.25rem}html.theme--documenter-dark .breadcrumb.is-large{font-size:1.5rem}html.theme--documenter-dark .breadcrumb.has-arrow-separator li+li::before{content:"\02192"}html.theme--documenter-dark .breadcrumb.has-bullet-separator li+li::before{content:"\02022"}html.theme--documenter-dark .breadcrumb.has-dot-separator li+li::before{content:"\000b7"}html.theme--documenter-dark .breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}html.theme--documenter-dark .card{background-color:#fff;border-radius:.25rem;box-shadow:#171717;color:#fff;max-width:100%;position:relative}html.theme--documenter-dark .card-footer:first-child,html.theme--documenter-dark .card-content:first-child,html.theme--documenter-dark .card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-footer:last-child,html.theme--documenter-dark .card-content:last-child,html.theme--documenter-dark .card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}html.theme--documenter-dark .card-header-title{align-items:center;color:#f2f2f2;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}html.theme--documenter-dark .card-header-title.is-centered{justify-content:center}html.theme--documenter-dark .card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}html.theme--documenter-dark .card-image{display:block;position:relative}html.theme--documenter-dark .card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-content{background-color:rgba(0,0,0,0);padding:1.5rem}html.theme--documenter-dark .card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}html.theme--documenter-dark .card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}html.theme--documenter-dark .card-footer-item:not(:last-child){border-right:1px solid #ededed}html.theme--documenter-dark .card .media:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .dropdown{display:inline-flex;position:relative;vertical-align:top}html.theme--documenter-dark .dropdown.is-active .dropdown-menu,html.theme--documenter-dark .dropdown.is-hoverable:hover .dropdown-menu{display:block}html.theme--documenter-dark .dropdown.is-right .dropdown-menu{left:auto;right:0}html.theme--documenter-dark .dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}html.theme--documenter-dark .dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .dropdown-content{background-color:#282f2f;border-radius:.4em;box-shadow:#171717;padding-bottom:.5rem;padding-top:.5rem}html.theme--documenter-dark .dropdown-item{color:#fff;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}html.theme--documenter-dark a.dropdown-item,html.theme--documenter-dark button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}html.theme--documenter-dark a.dropdown-item:hover,html.theme--documenter-dark button.dropdown-item:hover{background-color:#282f2f;color:#0a0a0a}html.theme--documenter-dark a.dropdown-item.is-active,html.theme--documenter-dark button.dropdown-item.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}html.theme--documenter-dark .level{align-items:center;justify-content:space-between}html.theme--documenter-dark .level code{border-radius:.4em}html.theme--documenter-dark .level img{display:inline-block;vertical-align:top}html.theme--documenter-dark .level.is-mobile{display:flex}html.theme--documenter-dark .level.is-mobile .level-left,html.theme--documenter-dark .level.is-mobile .level-right{display:flex}html.theme--documenter-dark .level.is-mobile .level-left+.level-right{margin-top:0}html.theme--documenter-dark .level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level{display:flex}html.theme--documenter-dark .level>.level-item:not(.is-narrow){flex-grow:1}}html.theme--documenter-dark .level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}html.theme--documenter-dark .level-item .title,html.theme--documenter-dark .level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){html.theme--documenter-dark .level-item:not(:last-child){margin-bottom:.75rem}}html.theme--documenter-dark .level-left,html.theme--documenter-dark .level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .level-left .level-item.is-flexible,html.theme--documenter-dark .level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left .level-item:not(:last-child),html.theme--documenter-dark .level-right .level-item:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){html.theme--documenter-dark .level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left{display:flex}}html.theme--documenter-dark .level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-right{display:flex}}html.theme--documenter-dark .media{align-items:flex-start;display:flex;text-align:inherit}html.theme--documenter-dark .media .content:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .media .media{border-top:1px solid rgba(94,109,111,0.5);display:flex;padding-top:.75rem}html.theme--documenter-dark .media .media .content:not(:last-child),html.theme--documenter-dark .media .media .control:not(:last-child){margin-bottom:.5rem}html.theme--documenter-dark .media .media .media{padding-top:.5rem}html.theme--documenter-dark .media .media .media+.media{margin-top:.5rem}html.theme--documenter-dark .media+.media{border-top:1px solid rgba(94,109,111,0.5);margin-top:1rem;padding-top:1rem}html.theme--documenter-dark .media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}html.theme--documenter-dark .media-left,html.theme--documenter-dark .media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .media-left{margin-right:1rem}html.theme--documenter-dark .media-right{margin-left:1rem}html.theme--documenter-dark .media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .media-content{overflow-x:auto}}html.theme--documenter-dark .menu{font-size:1rem}html.theme--documenter-dark .menu.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}html.theme--documenter-dark .menu.is-medium{font-size:1.25rem}html.theme--documenter-dark .menu.is-large{font-size:1.5rem}html.theme--documenter-dark .menu-list{line-height:1.25}html.theme--documenter-dark .menu-list a{border-radius:3px;color:#fff;display:block;padding:0.5em 0.75em}html.theme--documenter-dark .menu-list a:hover{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .menu-list a.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .menu-list li ul{border-left:1px solid #5e6d6f;margin:.75em;padding-left:.75em}html.theme--documenter-dark .menu-label{color:#fff;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}html.theme--documenter-dark .menu-label:not(:first-child){margin-top:1em}html.theme--documenter-dark .menu-label:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .message{background-color:#282f2f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .message strong{color:currentColor}html.theme--documenter-dark .message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .message.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}html.theme--documenter-dark .message.is-medium{font-size:1.25rem}html.theme--documenter-dark .message.is-large{font-size:1.5rem}html.theme--documenter-dark .message.is-white{background-color:#fff}html.theme--documenter-dark .message.is-white .message-header{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .message.is-white .message-body{border-color:#fff}html.theme--documenter-dark .message.is-black{background-color:#fafafa}html.theme--documenter-dark .message.is-black .message-header{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .message.is-black .message-body{border-color:#0a0a0a}html.theme--documenter-dark .message.is-light{background-color:#f9fafb}html.theme--documenter-dark .message.is-light .message-header{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .message.is-light .message-body{border-color:#ecf0f1}html.theme--documenter-dark .message.is-dark,html.theme--documenter-dark .content kbd.message{background-color:#f9fafa}html.theme--documenter-dark .message.is-dark .message-header,html.theme--documenter-dark .content kbd.message .message-header{background-color:#282f2f;color:#fff}html.theme--documenter-dark .message.is-dark .message-body,html.theme--documenter-dark .content kbd.message .message-body{border-color:#282f2f}html.theme--documenter-dark .message.is-primary,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink{background-color:#f1f5f9}html.theme--documenter-dark .message.is-primary .message-header,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-header{background-color:#375a7f;color:#fff}html.theme--documenter-dark .message.is-primary .message-body,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-body{border-color:#375a7f;color:#4d7eb2}html.theme--documenter-dark .message.is-link{background-color:#edfdf9}html.theme--documenter-dark .message.is-link .message-header{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .message.is-link .message-body{border-color:#1abc9c;color:#15987e}html.theme--documenter-dark .message.is-info{background-color:#ebf7ff}html.theme--documenter-dark .message.is-info .message-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .message.is-info .message-body{border-color:#024c7d;color:#0e9dfb}html.theme--documenter-dark .message.is-success{background-color:#ebfff3}html.theme--documenter-dark .message.is-success .message-header{background-color:#008438;color:#fff}html.theme--documenter-dark .message.is-success .message-body{border-color:#008438;color:#00eb64}html.theme--documenter-dark .message.is-warning{background-color:#fffaeb}html.theme--documenter-dark .message.is-warning .message-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .message.is-warning .message-body{border-color:#ad8100;color:#d19c00}html.theme--documenter-dark .message.is-danger{background-color:#fdeeec}html.theme--documenter-dark .message.is-danger .message-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .message.is-danger .message-body{border-color:#9e1b0d;color:#ec311d}html.theme--documenter-dark .message-header{align-items:center;background-color:#fff;border-radius:.4em .4em 0 0;color:rgba(0,0,0,0.7);display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}html.theme--documenter-dark .message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}html.theme--documenter-dark .message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}html.theme--documenter-dark .message-body{border-color:#5e6d6f;border-radius:.4em;border-style:solid;border-width:0 0 0 4px;color:#fff;padding:1.25em 1.5em}html.theme--documenter-dark .message-body code,html.theme--documenter-dark .message-body pre{background-color:#fff}html.theme--documenter-dark .message-body pre code{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}html.theme--documenter-dark .modal.is-active{display:flex}html.theme--documenter-dark .modal-background{background-color:rgba(10,10,10,0.86)}html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}html.theme--documenter-dark .modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}html.theme--documenter-dark .modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}html.theme--documenter-dark .modal-card-head,html.theme--documenter-dark .modal-card-foot{align-items:center;background-color:#282f2f;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}html.theme--documenter-dark .modal-card-head{border-bottom:1px solid #5e6d6f;border-top-left-radius:8px;border-top-right-radius:8px}html.theme--documenter-dark .modal-card-title{color:#f2f2f2;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}html.theme--documenter-dark .modal-card-foot{border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid #5e6d6f}html.theme--documenter-dark .modal-card-foot .button:not(:last-child){margin-right:.5em}html.theme--documenter-dark .modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}html.theme--documenter-dark .navbar{background-color:#375a7f;min-height:4rem;position:relative;z-index:30}html.theme--documenter-dark .navbar.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-white .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}html.theme--documenter-dark .navbar.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-black .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}html.theme--documenter-dark .navbar.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-light .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}}html.theme--documenter-dark .navbar.is-dark,html.theme--documenter-dark .content kbd.navbar{background-color:#282f2f;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-burger,html.theme--documenter-dark .content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-dark .navbar-start>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-end>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#282f2f;color:#fff}}html.theme--documenter-dark .navbar.is-primary,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-burger,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-primary .navbar-start>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-end>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#375a7f;color:#fff}}html.theme--documenter-dark .navbar.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-link .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c;color:#fff}}html.theme--documenter-dark .navbar.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-info .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#024c7d;color:#fff}}html.theme--documenter-dark .navbar.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-success .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#008438;color:#fff}}html.theme--documenter-dark .navbar.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-warning .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ad8100;color:#fff}}html.theme--documenter-dark .navbar.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-danger .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#9e1b0d;color:#fff}}html.theme--documenter-dark .navbar>.container{align-items:stretch;display:flex;min-height:4rem;width:100%}html.theme--documenter-dark .navbar.has-shadow{box-shadow:0 2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-bottom,html.theme--documenter-dark .navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-top{top:0}html.theme--documenter-dark html.has-navbar-fixed-top,html.theme--documenter-dark body.has-navbar-fixed-top{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom,html.theme--documenter-dark body.has-navbar-fixed-bottom{padding-bottom:4rem}html.theme--documenter-dark .navbar-brand,html.theme--documenter-dark .navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:4rem}html.theme--documenter-dark .navbar-brand a.navbar-item:focus,html.theme--documenter-dark .navbar-brand a.navbar-item:hover{background-color:transparent}html.theme--documenter-dark .navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}html.theme--documenter-dark .navbar-burger{color:#fff;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:4rem;position:relative;width:4rem;margin-left:auto}html.theme--documenter-dark .navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}html.theme--documenter-dark .navbar-burger span:nth-child(1){top:calc(50% - 6px)}html.theme--documenter-dark .navbar-burger span:nth-child(2){top:calc(50% - 1px)}html.theme--documenter-dark .navbar-burger span:nth-child(3){top:calc(50% + 4px)}html.theme--documenter-dark .navbar-burger:hover{background-color:rgba(0,0,0,0.05)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(2){opacity:0}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}html.theme--documenter-dark .navbar-menu{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{color:#fff;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}html.theme--documenter-dark .navbar-item .icon:only-child,html.theme--documenter-dark .navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}html.theme--documenter-dark a.navbar-item,html.theme--documenter-dark .navbar-link{cursor:pointer}html.theme--documenter-dark a.navbar-item:focus,html.theme--documenter-dark a.navbar-item:focus-within,html.theme--documenter-dark a.navbar-item:hover,html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link:focus,html.theme--documenter-dark .navbar-link:focus-within,html.theme--documenter-dark .navbar-link:hover,html.theme--documenter-dark .navbar-link.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-item{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .navbar-item img{max-height:1.75rem}html.theme--documenter-dark .navbar-item.has-dropdown{padding:0}html.theme--documenter-dark .navbar-item.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-item.is-tab{border-bottom:1px solid transparent;min-height:4rem;padding-bottom:calc(0.5rem - 1px)}html.theme--documenter-dark .navbar-item.is-tab:focus,html.theme--documenter-dark .navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c}html.theme--documenter-dark .navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c;border-bottom-style:solid;border-bottom-width:3px;color:#1abc9c;padding-bottom:calc(0.5rem - 3px)}html.theme--documenter-dark .navbar-content{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-link:not(.is-arrowless){padding-right:2.5em}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after{border-color:#fff;margin-top:-0.375em;right:1.125em}html.theme--documenter-dark .navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}html.theme--documenter-dark .navbar-divider{background-color:rgba(0,0,0,0.2);border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar>.container{display:block}html.theme--documenter-dark .navbar-brand .navbar-item,html.theme--documenter-dark .navbar-tabs .navbar-item{align-items:center;display:flex}html.theme--documenter-dark .navbar-link::after{display:none}html.theme--documenter-dark .navbar-menu{background-color:#375a7f;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}html.theme--documenter-dark .navbar-menu.is-active{display:block}html.theme--documenter-dark .navbar.is-fixed-bottom-touch,html.theme--documenter-dark .navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-touch{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-touch{top:0}html.theme--documenter-dark .navbar.is-fixed-top .navbar-menu,html.theme--documenter-dark .navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 4rem);overflow:auto}html.theme--documenter-dark html.has-navbar-fixed-top-touch,html.theme--documenter-dark body.has-navbar-fixed-top-touch{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-touch,html.theme--documenter-dark body.has-navbar-fixed-bottom-touch{padding-bottom:4rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar,html.theme--documenter-dark .navbar-menu,html.theme--documenter-dark .navbar-start,html.theme--documenter-dark .navbar-end{align-items:stretch;display:flex}html.theme--documenter-dark .navbar{min-height:4rem}html.theme--documenter-dark .navbar.is-spaced{padding:1rem 2rem}html.theme--documenter-dark .navbar.is-spaced .navbar-start,html.theme--documenter-dark .navbar.is-spaced .navbar-end{align-items:center}html.theme--documenter-dark .navbar.is-spaced a.navbar-item,html.theme--documenter-dark .navbar.is-spaced .navbar-link{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent a.navbar-item:hover,html.theme--documenter-dark .navbar.is-transparent a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-transparent .navbar-link:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-link:hover,html.theme--documenter-dark .navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-burger{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{align-items:center;display:flex}html.theme--documenter-dark .navbar-item.has-dropdown{align-items:stretch}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:1px solid rgba(0,0,0,0.2);border-radius:8px 8px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}html.theme--documenter-dark .navbar-menu{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .navbar-start{justify-content:flex-start;margin-right:auto}html.theme--documenter-dark .navbar-end{justify-content:flex-end;margin-left:auto}html.theme--documenter-dark .navbar-dropdown{background-color:#375a7f;border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid rgba(0,0,0,0.2);box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}html.theme--documenter-dark .navbar-dropdown a.navbar-item{padding-right:3rem}html.theme--documenter-dark .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}.navbar.is-spaced html.theme--documenter-dark .navbar-dropdown,html.theme--documenter-dark .navbar-dropdown.is-boxed{border-radius:8px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}html.theme--documenter-dark .navbar-dropdown.is-right{left:auto;right:0}html.theme--documenter-dark .navbar-divider{display:block}html.theme--documenter-dark .navbar>.container .navbar-brand,html.theme--documenter-dark .container>.navbar .navbar-brand{margin-left:-.75rem}html.theme--documenter-dark .navbar>.container .navbar-menu,html.theme--documenter-dark .container>.navbar .navbar-menu{margin-right:-.75rem}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop,html.theme--documenter-dark .navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-desktop{top:0}html.theme--documenter-dark html.has-navbar-fixed-top-desktop,html.theme--documenter-dark body.has-navbar-fixed-top-desktop{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-desktop,html.theme--documenter-dark body.has-navbar-fixed-bottom-desktop{padding-bottom:4rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-top,html.theme--documenter-dark body.has-spaced-navbar-fixed-top{padding-top:6rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-bottom,html.theme--documenter-dark body.has-spaced-navbar-fixed-bottom{padding-bottom:6rem}html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link.is-active{color:#1abc9c}html.theme--documenter-dark a.navbar-item.is-active:not(:focus):not(:hover),html.theme--documenter-dark .navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}html.theme--documenter-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown.is-active .navbar-link{background-color:rgba(0,0,0,0)}}html.theme--documenter-dark .hero.is-fullheight-with-navbar{min-height:calc(100vh - 4rem)}html.theme--documenter-dark .pagination{font-size:1rem;margin:-.25rem}html.theme--documenter-dark .pagination.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}html.theme--documenter-dark .pagination.is-medium{font-size:1.25rem}html.theme--documenter-dark .pagination.is-large{font-size:1.5rem}html.theme--documenter-dark .pagination.is-rounded .pagination-previous,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,html.theme--documenter-dark .pagination.is-rounded .pagination-next,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}html.theme--documenter-dark .pagination.is-rounded .pagination-link,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}html.theme--documenter-dark .pagination,html.theme--documenter-dark .pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link{border-color:#5e6d6f;color:#1abc9c;min-width:2.5em}html.theme--documenter-dark .pagination-previous:hover,html.theme--documenter-dark .pagination-next:hover,html.theme--documenter-dark .pagination-link:hover{border-color:#8c9b9d;color:#1dd2af}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus{border-color:#8c9b9d}html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-previous.is-disabled,html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-next.is-disabled,html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-link.is-disabled{background-color:#5e6d6f;border-color:#5e6d6f;box-shadow:none;color:#fff;opacity:0.5}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}html.theme--documenter-dark .pagination-link.is-current{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .pagination-ellipsis{color:#8c9b9d;pointer-events:none}html.theme--documenter-dark .pagination-list{flex-wrap:wrap}html.theme--documenter-dark .pagination-list li{list-style:none}@media screen and (max-width: 768px){html.theme--documenter-dark .pagination{flex-wrap:wrap}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination-previous{order:2}html.theme--documenter-dark .pagination-next{order:3}html.theme--documenter-dark .pagination{justify-content:space-between;margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination.is-centered .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-centered .pagination-list{justify-content:center;order:2}html.theme--documenter-dark .pagination.is-centered .pagination-next{order:3}html.theme--documenter-dark .pagination.is-right .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-right .pagination-next{order:2}html.theme--documenter-dark .pagination.is-right .pagination-list{justify-content:flex-end;order:3}}html.theme--documenter-dark .panel{border-radius:8px;box-shadow:#171717;font-size:1rem}html.theme--documenter-dark .panel:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}html.theme--documenter-dark .panel.is-white .panel-block.is-active .panel-icon{color:#fff}html.theme--documenter-dark .panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}html.theme--documenter-dark .panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}html.theme--documenter-dark .panel.is-light .panel-heading{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .panel.is-light .panel-tabs a.is-active{border-bottom-color:#ecf0f1}html.theme--documenter-dark .panel.is-light .panel-block.is-active .panel-icon{color:#ecf0f1}html.theme--documenter-dark .panel.is-dark .panel-heading,html.theme--documenter-dark .content kbd.panel .panel-heading{background-color:#282f2f;color:#fff}html.theme--documenter-dark .panel.is-dark .panel-tabs a.is-active,html.theme--documenter-dark .content kbd.panel .panel-tabs a.is-active{border-bottom-color:#282f2f}html.theme--documenter-dark .panel.is-dark .panel-block.is-active .panel-icon,html.theme--documenter-dark .content kbd.panel .panel-block.is-active .panel-icon{color:#282f2f}html.theme--documenter-dark .panel.is-primary .panel-heading,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#375a7f;color:#fff}html.theme--documenter-dark .panel.is-primary .panel-tabs a.is-active,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#375a7f}html.theme--documenter-dark .panel.is-primary .panel-block.is-active .panel-icon,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#375a7f}html.theme--documenter-dark .panel.is-link .panel-heading{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .panel.is-link .panel-tabs a.is-active{border-bottom-color:#1abc9c}html.theme--documenter-dark .panel.is-link .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel.is-info .panel-heading{background-color:#024c7d;color:#fff}html.theme--documenter-dark .panel.is-info .panel-tabs a.is-active{border-bottom-color:#024c7d}html.theme--documenter-dark .panel.is-info .panel-block.is-active .panel-icon{color:#024c7d}html.theme--documenter-dark .panel.is-success .panel-heading{background-color:#008438;color:#fff}html.theme--documenter-dark .panel.is-success .panel-tabs a.is-active{border-bottom-color:#008438}html.theme--documenter-dark .panel.is-success .panel-block.is-active .panel-icon{color:#008438}html.theme--documenter-dark .panel.is-warning .panel-heading{background-color:#ad8100;color:#fff}html.theme--documenter-dark .panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ad8100}html.theme--documenter-dark .panel.is-warning .panel-block.is-active .panel-icon{color:#ad8100}html.theme--documenter-dark .panel.is-danger .panel-heading{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .panel.is-danger .panel-tabs a.is-active{border-bottom-color:#9e1b0d}html.theme--documenter-dark .panel.is-danger .panel-block.is-active .panel-icon{color:#9e1b0d}html.theme--documenter-dark .panel-tabs:not(:last-child),html.theme--documenter-dark .panel-block:not(:last-child){border-bottom:1px solid #ededed}html.theme--documenter-dark .panel-heading{background-color:#343c3d;border-radius:8px 8px 0 0;color:#f2f2f2;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}html.theme--documenter-dark .panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}html.theme--documenter-dark .panel-tabs a{border-bottom:1px solid #5e6d6f;margin-bottom:-1px;padding:0.5em}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#343c3d;color:#17a689}html.theme--documenter-dark .panel-list a{color:#fff}html.theme--documenter-dark .panel-list a:hover{color:#1abc9c}html.theme--documenter-dark .panel-block{align-items:center;color:#f2f2f2;display:flex;justify-content:flex-start;padding:0.5em 0.75em}html.theme--documenter-dark .panel-block input[type="checkbox"]{margin-right:.75em}html.theme--documenter-dark .panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}html.theme--documenter-dark .panel-block.is-wrapped{flex-wrap:wrap}html.theme--documenter-dark .panel-block.is-active{border-left-color:#1abc9c;color:#17a689}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel-block:last-child{border-bottom-left-radius:8px;border-bottom-right-radius:8px}html.theme--documenter-dark a.panel-block,html.theme--documenter-dark label.panel-block{cursor:pointer}html.theme--documenter-dark a.panel-block:hover,html.theme--documenter-dark label.panel-block:hover{background-color:#282f2f}html.theme--documenter-dark .panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#fff;margin-right:.75em}html.theme--documenter-dark .panel-icon .fa{font-size:inherit;line-height:inherit}html.theme--documenter-dark .tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}html.theme--documenter-dark .tabs a{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;color:#fff;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}html.theme--documenter-dark .tabs a:hover{border-bottom-color:#f2f2f2;color:#f2f2f2}html.theme--documenter-dark .tabs li{display:block}html.theme--documenter-dark .tabs li.is-active a{border-bottom-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .tabs ul{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}html.theme--documenter-dark .tabs ul.is-left{padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}html.theme--documenter-dark .tabs .icon:first-child{margin-right:.5em}html.theme--documenter-dark .tabs .icon:last-child{margin-left:.5em}html.theme--documenter-dark .tabs.is-centered ul{justify-content:center}html.theme--documenter-dark .tabs.is-right ul{justify-content:flex-end}html.theme--documenter-dark .tabs.is-boxed a{border:1px solid transparent;border-radius:.4em .4em 0 0}html.theme--documenter-dark .tabs.is-boxed a:hover{background-color:#282f2f;border-bottom-color:#5e6d6f}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#fff;border-color:#5e6d6f;border-bottom-color:rgba(0,0,0,0) !important}html.theme--documenter-dark .tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .tabs.is-toggle a{border-color:#5e6d6f;border-style:solid;border-width:1px;margin-bottom:0;position:relative}html.theme--documenter-dark .tabs.is-toggle a:hover{background-color:#282f2f;border-color:#8c9b9d;z-index:2}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .tabs.is-toggle li:first-child a{border-top-left-radius:.4em;border-bottom-left-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li:last-child a{border-top-right-radius:.4em;border-bottom-right-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li.is-active a{background-color:#1abc9c;border-color:#1abc9c;color:#fff;z-index:1}html.theme--documenter-dark .tabs.is-toggle ul{border-bottom:none}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}html.theme--documenter-dark .tabs.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}html.theme--documenter-dark .tabs.is-medium{font-size:1.25rem}html.theme--documenter-dark .tabs.is-large{font-size:1.5rem}html.theme--documenter-dark .column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>html.theme--documenter-dark .column.is-narrow{flex:none;width:unset}.columns.is-mobile>html.theme--documenter-dark .column.is-full{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-half{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-half{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-0{flex:none;width:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-0{margin-left:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-3{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-3{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-6{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-6{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-9{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-9{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-12{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){html.theme--documenter-dark .column.is-narrow-mobile{flex:none;width:unset}html.theme--documenter-dark .column.is-full-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-mobile{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-mobile{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-mobile{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-mobile{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-mobile{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-mobile{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-mobile{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-mobile{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-mobile{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-mobile{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-mobile{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-mobile{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-mobile{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-mobile{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-mobile{margin-left:80%}html.theme--documenter-dark .column.is-0-mobile{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-mobile{margin-left:0%}html.theme--documenter-dark .column.is-1-mobile{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-mobile{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-mobile{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-mobile{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-mobile{margin-left:25%}html.theme--documenter-dark .column.is-4-mobile{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-mobile{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-mobile{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-mobile{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-mobile{margin-left:50%}html.theme--documenter-dark .column.is-7-mobile{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-mobile{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-mobile{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-mobile{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-mobile{margin-left:75%}html.theme--documenter-dark .column.is-10-mobile{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-mobile{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-mobile{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-mobile{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .column.is-narrow,html.theme--documenter-dark .column.is-narrow-tablet{flex:none;width:unset}html.theme--documenter-dark .column.is-full,html.theme--documenter-dark .column.is-full-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters,html.theme--documenter-dark .column.is-three-quarters-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds,html.theme--documenter-dark .column.is-two-thirds-tablet{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half,html.theme--documenter-dark .column.is-half-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third,html.theme--documenter-dark .column.is-one-third-tablet{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter,html.theme--documenter-dark .column.is-one-quarter-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth,html.theme--documenter-dark .column.is-one-fifth-tablet{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths,html.theme--documenter-dark .column.is-two-fifths-tablet{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths,html.theme--documenter-dark .column.is-three-fifths-tablet{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths,html.theme--documenter-dark .column.is-four-fifths-tablet{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters,html.theme--documenter-dark .column.is-offset-three-quarters-tablet{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds,html.theme--documenter-dark .column.is-offset-two-thirds-tablet{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half,html.theme--documenter-dark .column.is-offset-half-tablet{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third,html.theme--documenter-dark .column.is-offset-one-third-tablet{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter,html.theme--documenter-dark .column.is-offset-one-quarter-tablet{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth,html.theme--documenter-dark .column.is-offset-one-fifth-tablet{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths,html.theme--documenter-dark .column.is-offset-two-fifths-tablet{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths,html.theme--documenter-dark .column.is-offset-three-fifths-tablet{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths,html.theme--documenter-dark .column.is-offset-four-fifths-tablet{margin-left:80%}html.theme--documenter-dark .column.is-0,html.theme--documenter-dark .column.is-0-tablet{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0,html.theme--documenter-dark .column.is-offset-0-tablet{margin-left:0%}html.theme--documenter-dark .column.is-1,html.theme--documenter-dark .column.is-1-tablet{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1,html.theme--documenter-dark .column.is-offset-1-tablet{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2,html.theme--documenter-dark .column.is-2-tablet{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2,html.theme--documenter-dark .column.is-offset-2-tablet{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3,html.theme--documenter-dark .column.is-3-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3,html.theme--documenter-dark .column.is-offset-3-tablet{margin-left:25%}html.theme--documenter-dark .column.is-4,html.theme--documenter-dark .column.is-4-tablet{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4,html.theme--documenter-dark .column.is-offset-4-tablet{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5,html.theme--documenter-dark .column.is-5-tablet{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5,html.theme--documenter-dark .column.is-offset-5-tablet{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6,html.theme--documenter-dark .column.is-6-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6,html.theme--documenter-dark .column.is-offset-6-tablet{margin-left:50%}html.theme--documenter-dark .column.is-7,html.theme--documenter-dark .column.is-7-tablet{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7,html.theme--documenter-dark .column.is-offset-7-tablet{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8,html.theme--documenter-dark .column.is-8-tablet{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8,html.theme--documenter-dark .column.is-offset-8-tablet{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9,html.theme--documenter-dark .column.is-9-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9,html.theme--documenter-dark .column.is-offset-9-tablet{margin-left:75%}html.theme--documenter-dark .column.is-10,html.theme--documenter-dark .column.is-10-tablet{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10,html.theme--documenter-dark .column.is-offset-10-tablet{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11,html.theme--documenter-dark .column.is-11-tablet{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11,html.theme--documenter-dark .column.is-offset-11-tablet{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12,html.theme--documenter-dark .column.is-12-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12,html.theme--documenter-dark .column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){html.theme--documenter-dark .column.is-narrow-touch{flex:none;width:unset}html.theme--documenter-dark .column.is-full-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-touch{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-touch{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-touch{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-touch{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-touch{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-touch{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-touch{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-touch{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-touch{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-touch{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-touch{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-touch{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-touch{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-touch{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-touch{margin-left:80%}html.theme--documenter-dark .column.is-0-touch{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-touch{margin-left:0%}html.theme--documenter-dark .column.is-1-touch{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-touch{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-touch{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-touch{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-touch{margin-left:25%}html.theme--documenter-dark .column.is-4-touch{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-touch{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-touch{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-touch{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-touch{margin-left:50%}html.theme--documenter-dark .column.is-7-touch{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-touch{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-touch{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-touch{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-touch{margin-left:75%}html.theme--documenter-dark .column.is-10-touch{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-touch{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-touch{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-touch{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){html.theme--documenter-dark .column.is-narrow-desktop{flex:none;width:unset}html.theme--documenter-dark .column.is-full-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-desktop{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-desktop{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-desktop{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-desktop{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-desktop{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-desktop{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-desktop{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-desktop{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-desktop{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-desktop{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-desktop{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-desktop{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-desktop{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-desktop{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-desktop{margin-left:80%}html.theme--documenter-dark .column.is-0-desktop{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-desktop{margin-left:0%}html.theme--documenter-dark .column.is-1-desktop{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-desktop{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-desktop{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-desktop{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-desktop{margin-left:25%}html.theme--documenter-dark .column.is-4-desktop{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-desktop{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-desktop{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-desktop{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-desktop{margin-left:50%}html.theme--documenter-dark .column.is-7-desktop{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-desktop{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-desktop{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-desktop{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-desktop{margin-left:75%}html.theme--documenter-dark .column.is-10-desktop{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-desktop{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-desktop{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-desktop{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){html.theme--documenter-dark .column.is-narrow-widescreen{flex:none;width:unset}html.theme--documenter-dark .column.is-full-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-widescreen{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-widescreen{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-widescreen{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-widescreen{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-widescreen{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-widescreen{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-widescreen{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-widescreen{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-widescreen{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-widescreen{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-widescreen{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-widescreen{margin-left:80%}html.theme--documenter-dark .column.is-0-widescreen{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-widescreen{margin-left:0%}html.theme--documenter-dark .column.is-1-widescreen{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-widescreen{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-widescreen{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-widescreen{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-4-widescreen{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-widescreen{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-widescreen{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-widescreen{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-7-widescreen{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-widescreen{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-widescreen{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-widescreen{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-10-widescreen{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-widescreen{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-widescreen{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-widescreen{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){html.theme--documenter-dark .column.is-narrow-fullhd{flex:none;width:unset}html.theme--documenter-dark .column.is-full-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-fullhd{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-fullhd{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-fullhd{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-fullhd{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-fullhd{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-fullhd{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-fullhd{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-fullhd{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-fullhd{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-fullhd{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-fullhd{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-fullhd{margin-left:80%}html.theme--documenter-dark .column.is-0-fullhd{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-fullhd{margin-left:0%}html.theme--documenter-dark .column.is-1-fullhd{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-fullhd{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-fullhd{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-fullhd{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-4-fullhd{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-fullhd{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-fullhd{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-fullhd{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-7-fullhd{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-fullhd{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-fullhd{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-fullhd{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-10-fullhd{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-fullhd{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-fullhd{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-fullhd{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-fullhd{margin-left:100%}}html.theme--documenter-dark .columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .columns:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}html.theme--documenter-dark .columns.is-centered{justify-content:center}html.theme--documenter-dark .columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}html.theme--documenter-dark .columns.is-gapless>.column{margin:0;padding:0 !important}html.theme--documenter-dark .columns.is-gapless:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .columns.is-gapless:last-child{margin-bottom:0}html.theme--documenter-dark .columns.is-mobile{display:flex}html.theme--documenter-dark .columns.is-multiline{flex-wrap:wrap}html.theme--documenter-dark .columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-desktop{display:flex}}html.theme--documenter-dark .columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}html.theme--documenter-dark .columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}html.theme--documenter-dark .columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-0-fullhd{--columnGap: 0rem}}html.theme--documenter-dark .columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-1-fullhd{--columnGap: .25rem}}html.theme--documenter-dark .columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-2-fullhd{--columnGap: .5rem}}html.theme--documenter-dark .columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-3-fullhd{--columnGap: .75rem}}html.theme--documenter-dark .columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-4-fullhd{--columnGap: 1rem}}html.theme--documenter-dark .columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}html.theme--documenter-dark .columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}html.theme--documenter-dark .columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}html.theme--documenter-dark .columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-8-fullhd{--columnGap: 2rem}}html.theme--documenter-dark .tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}html.theme--documenter-dark .tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .tile.is-ancestor:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .tile.is-ancestor:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .tile.is-child{margin:0 !important}html.theme--documenter-dark .tile.is-parent{padding:.75rem}html.theme--documenter-dark .tile.is-vertical{flex-direction:column}html.theme--documenter-dark .tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{html.theme--documenter-dark .tile:not(.is-child){display:flex}html.theme--documenter-dark .tile.is-1{flex:none;width:8.33333337%}html.theme--documenter-dark .tile.is-2{flex:none;width:16.66666674%}html.theme--documenter-dark .tile.is-3{flex:none;width:25%}html.theme--documenter-dark .tile.is-4{flex:none;width:33.33333337%}html.theme--documenter-dark .tile.is-5{flex:none;width:41.66666674%}html.theme--documenter-dark .tile.is-6{flex:none;width:50%}html.theme--documenter-dark .tile.is-7{flex:none;width:58.33333337%}html.theme--documenter-dark .tile.is-8{flex:none;width:66.66666674%}html.theme--documenter-dark .tile.is-9{flex:none;width:75%}html.theme--documenter-dark .tile.is-10{flex:none;width:83.33333337%}html.theme--documenter-dark .tile.is-11{flex:none;width:91.66666674%}html.theme--documenter-dark .tile.is-12{flex:none;width:100%}}html.theme--documenter-dark .hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}html.theme--documenter-dark .hero .navbar{background:none}html.theme--documenter-dark .hero .tabs ul{border-bottom:none}html.theme--documenter-dark .hero.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-white strong{color:inherit}html.theme--documenter-dark .hero.is-white .title{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .subtitle{color:rgba(10,10,10,0.9)}html.theme--documenter-dark .hero.is-white .subtitle a:not(.button),html.theme--documenter-dark .hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-white .navbar-menu{background-color:#fff}}html.theme--documenter-dark .hero.is-white .navbar-item,html.theme--documenter-dark .hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}html.theme--documenter-dark .hero.is-white a.navbar-item:hover,html.theme--documenter-dark .hero.is-white a.navbar-item.is-active,html.theme--documenter-dark .hero.is-white .navbar-link:hover,html.theme--documenter-dark .hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}html.theme--documenter-dark .hero.is-white .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}html.theme--documenter-dark .hero.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-black strong{color:inherit}html.theme--documenter-dark .hero.is-black .title{color:#fff}html.theme--documenter-dark .hero.is-black .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-black .subtitle a:not(.button),html.theme--documenter-dark .hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-black .navbar-menu{background-color:#0a0a0a}}html.theme--documenter-dark .hero.is-black .navbar-item,html.theme--documenter-dark .hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-black a.navbar-item:hover,html.theme--documenter-dark .hero.is-black a.navbar-item.is-active,html.theme--documenter-dark .hero.is-black .navbar-link:hover,html.theme--documenter-dark .hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .hero.is-black .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-black .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}html.theme--documenter-dark .hero.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-light strong{color:inherit}html.theme--documenter-dark .hero.is-light .title{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .subtitle{color:rgba(0,0,0,0.9)}html.theme--documenter-dark .hero.is-light .subtitle a:not(.button),html.theme--documenter-dark .hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-light .navbar-menu{background-color:#ecf0f1}}html.theme--documenter-dark .hero.is-light .navbar-item,html.theme--documenter-dark .hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a.navbar-item:hover,html.theme--documenter-dark .hero.is-light a.navbar-item.is-active,html.theme--documenter-dark .hero.is-light .navbar-link:hover,html.theme--documenter-dark .hero.is-light .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}html.theme--documenter-dark .hero.is-light .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-light .tabs li.is-active a{color:#ecf0f1 !important;opacity:1}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .hero.is-light.is-bold{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}}html.theme--documenter-dark .hero.is-dark,html.theme--documenter-dark .content kbd.hero{background-color:#282f2f;color:#fff}html.theme--documenter-dark .hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-dark strong,html.theme--documenter-dark .content kbd.hero strong{color:inherit}html.theme--documenter-dark .hero.is-dark .title,html.theme--documenter-dark .content kbd.hero .title{color:#fff}html.theme--documenter-dark .hero.is-dark .subtitle,html.theme--documenter-dark .content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-dark .subtitle a:not(.button),html.theme--documenter-dark .content kbd.hero .subtitle a:not(.button),html.theme--documenter-dark .hero.is-dark .subtitle strong,html.theme--documenter-dark .content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-dark .navbar-menu,html.theme--documenter-dark .content kbd.hero .navbar-menu{background-color:#282f2f}}html.theme--documenter-dark .hero.is-dark .navbar-item,html.theme--documenter-dark .content kbd.hero .navbar-item,html.theme--documenter-dark .hero.is-dark .navbar-link,html.theme--documenter-dark .content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-dark a.navbar-item:hover,html.theme--documenter-dark .content kbd.hero a.navbar-item:hover,html.theme--documenter-dark .hero.is-dark a.navbar-item.is-active,html.theme--documenter-dark .content kbd.hero a.navbar-item.is-active,html.theme--documenter-dark .hero.is-dark .navbar-link:hover,html.theme--documenter-dark .content kbd.hero .navbar-link:hover,html.theme--documenter-dark .hero.is-dark .navbar-link.is-active,html.theme--documenter-dark .content kbd.hero .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .hero.is-dark .tabs a,html.theme--documenter-dark .content kbd.hero .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-dark .tabs a:hover,html.theme--documenter-dark .content kbd.hero .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-dark .tabs li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs li.is-active a{color:#282f2f !important;opacity:1}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#282f2f}html.theme--documenter-dark .hero.is-dark.is-bold,html.theme--documenter-dark .content kbd.hero.is-bold{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-dark.is-bold .navbar-menu,html.theme--documenter-dark .content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}}html.theme--documenter-dark .hero.is-primary,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-primary strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink strong{color:inherit}html.theme--documenter-dark .hero.is-primary .title,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .title{color:#fff}html.theme--documenter-dark .hero.is-primary .subtitle,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-primary .subtitle a:not(.button),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),html.theme--documenter-dark .hero.is-primary .subtitle strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-primary .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#375a7f}}html.theme--documenter-dark .hero.is-primary .navbar-item,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-item,html.theme--documenter-dark .hero.is-primary .navbar-link,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-primary a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,html.theme--documenter-dark .hero.is-primary a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,html.theme--documenter-dark .hero.is-primary .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link:hover,html.theme--documenter-dark .hero.is-primary .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .hero.is-primary .tabs a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-primary .tabs a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-primary .tabs li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#375a7f !important;opacity:1}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#375a7f}html.theme--documenter-dark .hero.is-primary.is-bold,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-primary.is-bold .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}}html.theme--documenter-dark .hero.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-link strong{color:inherit}html.theme--documenter-dark .hero.is-link .title{color:#fff}html.theme--documenter-dark .hero.is-link .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-link .subtitle a:not(.button),html.theme--documenter-dark .hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-link .navbar-menu{background-color:#1abc9c}}html.theme--documenter-dark .hero.is-link .navbar-item,html.theme--documenter-dark .hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-link a.navbar-item:hover,html.theme--documenter-dark .hero.is-link a.navbar-item.is-active,html.theme--documenter-dark .hero.is-link .navbar-link:hover,html.theme--documenter-dark .hero.is-link .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .hero.is-link .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-link .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-link .tabs li.is-active a{color:#1abc9c !important;opacity:1}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#1abc9c}html.theme--documenter-dark .hero.is-link.is-bold{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}}html.theme--documenter-dark .hero.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-info strong{color:inherit}html.theme--documenter-dark .hero.is-info .title{color:#fff}html.theme--documenter-dark .hero.is-info .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-info .subtitle a:not(.button),html.theme--documenter-dark .hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-info .navbar-menu{background-color:#024c7d}}html.theme--documenter-dark .hero.is-info .navbar-item,html.theme--documenter-dark .hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-info a.navbar-item:hover,html.theme--documenter-dark .hero.is-info a.navbar-item.is-active,html.theme--documenter-dark .hero.is-info .navbar-link:hover,html.theme--documenter-dark .hero.is-info .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .hero.is-info .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-info .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-info .tabs li.is-active a{color:#024c7d !important;opacity:1}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#024c7d}html.theme--documenter-dark .hero.is-info.is-bold{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}}html.theme--documenter-dark .hero.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-success strong{color:inherit}html.theme--documenter-dark .hero.is-success .title{color:#fff}html.theme--documenter-dark .hero.is-success .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-success .subtitle a:not(.button),html.theme--documenter-dark .hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-success .navbar-menu{background-color:#008438}}html.theme--documenter-dark .hero.is-success .navbar-item,html.theme--documenter-dark .hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-success a.navbar-item:hover,html.theme--documenter-dark .hero.is-success a.navbar-item.is-active,html.theme--documenter-dark .hero.is-success .navbar-link:hover,html.theme--documenter-dark .hero.is-success .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .hero.is-success .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-success .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-success .tabs li.is-active a{color:#008438 !important;opacity:1}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#008438}html.theme--documenter-dark .hero.is-success.is-bold{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}}html.theme--documenter-dark .hero.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-warning strong{color:inherit}html.theme--documenter-dark .hero.is-warning .title{color:#fff}html.theme--documenter-dark .hero.is-warning .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-warning .subtitle a:not(.button),html.theme--documenter-dark .hero.is-warning .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-warning .navbar-menu{background-color:#ad8100}}html.theme--documenter-dark .hero.is-warning .navbar-item,html.theme--documenter-dark .hero.is-warning .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-warning a.navbar-item:hover,html.theme--documenter-dark .hero.is-warning a.navbar-item.is-active,html.theme--documenter-dark .hero.is-warning .navbar-link:hover,html.theme--documenter-dark .hero.is-warning .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .hero.is-warning .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-warning .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-warning .tabs li.is-active a{color:#ad8100 !important;opacity:1}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#ad8100}html.theme--documenter-dark .hero.is-warning.is-bold{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}}html.theme--documenter-dark .hero.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-danger strong{color:inherit}html.theme--documenter-dark .hero.is-danger .title{color:#fff}html.theme--documenter-dark .hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-danger .subtitle a:not(.button),html.theme--documenter-dark .hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-danger .navbar-menu{background-color:#9e1b0d}}html.theme--documenter-dark .hero.is-danger .navbar-item,html.theme--documenter-dark .hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-danger a.navbar-item:hover,html.theme--documenter-dark .hero.is-danger a.navbar-item.is-active,html.theme--documenter-dark .hero.is-danger .navbar-link:hover,html.theme--documenter-dark .hero.is-danger .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .hero.is-danger .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-danger .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-danger .tabs li.is-active a{color:#9e1b0d !important;opacity:1}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#9e1b0d}html.theme--documenter-dark .hero.is-danger.is-bold{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}}html.theme--documenter-dark .hero.is-small .hero-body,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-large .hero-body{padding:18rem 6rem}}html.theme--documenter-dark .hero.is-halfheight .hero-body,html.theme--documenter-dark .hero.is-fullheight .hero-body,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}html.theme--documenter-dark .hero.is-halfheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .hero.is-halfheight{min-height:50vh}html.theme--documenter-dark .hero.is-fullheight{min-height:100vh}html.theme--documenter-dark .hero-video{overflow:hidden}html.theme--documenter-dark .hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}html.theme--documenter-dark .hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-video{display:none}}html.theme--documenter-dark .hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-buttons .button{display:flex}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-buttons{display:flex;justify-content:center}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-right:1.5rem}}html.theme--documenter-dark .hero-head,html.theme--documenter-dark .hero-foot{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-body{padding:3rem 3rem}}html.theme--documenter-dark .section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){html.theme--documenter-dark .section{padding:3rem 3rem}html.theme--documenter-dark .section.is-medium{padding:9rem 4.5rem}html.theme--documenter-dark .section.is-large{padding:18rem 6rem}}html.theme--documenter-dark .footer{background-color:#282f2f;padding:3rem 1.5rem 6rem}html.theme--documenter-dark hr{height:1px}html.theme--documenter-dark h6{text-transform:uppercase;letter-spacing:0.5px}html.theme--documenter-dark .hero{background-color:#343c3d}html.theme--documenter-dark a{transition:all 200ms ease}html.theme--documenter-dark .button{transition:all 200ms ease;border-width:1px;color:#fff}html.theme--documenter-dark .button.is-active,html.theme--documenter-dark .button.is-focused,html.theme--documenter-dark .button:active,html.theme--documenter-dark .button:focus{box-shadow:0 0 0 2px rgba(140,155,157,0.5)}html.theme--documenter-dark .button.is-white.is-hovered,html.theme--documenter-dark .button.is-white:hover{background-color:#fff}html.theme--documenter-dark .button.is-white.is-active,html.theme--documenter-dark .button.is-white.is-focused,html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white:focus{border-color:#fff;box-shadow:0 0 0 2px rgba(255,255,255,0.5)}html.theme--documenter-dark .button.is-black.is-hovered,html.theme--documenter-dark .button.is-black:hover{background-color:#1d1d1d}html.theme--documenter-dark .button.is-black.is-active,html.theme--documenter-dark .button.is-black.is-focused,html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black:focus{border-color:#0a0a0a;box-shadow:0 0 0 2px rgba(10,10,10,0.5)}html.theme--documenter-dark .button.is-light.is-hovered,html.theme--documenter-dark .button.is-light:hover{background-color:#fff}html.theme--documenter-dark .button.is-light.is-active,html.theme--documenter-dark .button.is-light.is-focused,html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light:focus{border-color:#ecf0f1;box-shadow:0 0 0 2px rgba(236,240,241,0.5)}html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered,html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover{background-color:#3a4344}html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused,html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus{border-color:#282f2f;box-shadow:0 0 0 2px rgba(40,47,47,0.5)}html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover{background-color:#436d9a}html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink,html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus{border-color:#375a7f;box-shadow:0 0 0 2px rgba(55,90,127,0.5)}html.theme--documenter-dark .button.is-link.is-hovered,html.theme--documenter-dark .button.is-link:hover{background-color:#1fdeb8}html.theme--documenter-dark .button.is-link.is-active,html.theme--documenter-dark .button.is-link.is-focused,html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link:focus{border-color:#1abc9c;box-shadow:0 0 0 2px rgba(26,188,156,0.5)}html.theme--documenter-dark .button.is-info.is-hovered,html.theme--documenter-dark .button.is-info:hover{background-color:#0363a3}html.theme--documenter-dark .button.is-info.is-active,html.theme--documenter-dark .button.is-info.is-focused,html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info:focus{border-color:#024c7d;box-shadow:0 0 0 2px rgba(2,76,125,0.5)}html.theme--documenter-dark .button.is-success.is-hovered,html.theme--documenter-dark .button.is-success:hover{background-color:#00aa48}html.theme--documenter-dark .button.is-success.is-active,html.theme--documenter-dark .button.is-success.is-focused,html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success:focus{border-color:#008438;box-shadow:0 0 0 2px rgba(0,132,56,0.5)}html.theme--documenter-dark .button.is-warning.is-hovered,html.theme--documenter-dark .button.is-warning:hover{background-color:#d39e00}html.theme--documenter-dark .button.is-warning.is-active,html.theme--documenter-dark .button.is-warning.is-focused,html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning:focus{border-color:#ad8100;box-shadow:0 0 0 2px rgba(173,129,0,0.5)}html.theme--documenter-dark .button.is-danger.is-hovered,html.theme--documenter-dark .button.is-danger:hover{background-color:#c12110}html.theme--documenter-dark .button.is-danger.is-active,html.theme--documenter-dark .button.is-danger.is-focused,html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger:focus{border-color:#9e1b0d;box-shadow:0 0 0 2px rgba(158,27,13,0.5)}html.theme--documenter-dark .label{color:#dbdee0}html.theme--documenter-dark .button,html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .select,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea{height:2.5em}html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .textarea{transition:all 200ms ease;box-shadow:none;border-width:1px;padding-left:1em;padding-right:1em}html.theme--documenter-dark .select:after,html.theme--documenter-dark .select select{border-width:1px}html.theme--documenter-dark .control.has-addons .button,html.theme--documenter-dark .control.has-addons .input,html.theme--documenter-dark .control.has-addons #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-addons form.docs-search>input,html.theme--documenter-dark .control.has-addons .select{margin-right:-1px}html.theme--documenter-dark .notification{background-color:#343c3d}html.theme--documenter-dark .card{box-shadow:none;border:1px solid #343c3d;background-color:#282f2f;border-radius:.4em}html.theme--documenter-dark .card .card-image img{border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-header{box-shadow:none;background-color:rgba(18,18,18,0.2);border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-footer{background-color:rgba(18,18,18,0.2)}html.theme--documenter-dark .card .card-footer,html.theme--documenter-dark .card .card-footer-item{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .notification.is-white a:not(.button){color:#0a0a0a;text-decoration:underline}html.theme--documenter-dark .notification.is-black a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-light a:not(.button){color:rgba(0,0,0,0.7);text-decoration:underline}html.theme--documenter-dark .notification.is-dark a:not(.button),html.theme--documenter-dark .content kbd.notification a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-primary a:not(.button),html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-link a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-info a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-success a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-warning a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-danger a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .tag,html.theme--documenter-dark .content kbd,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{border-radius:.4em}html.theme--documenter-dark .menu-list a{transition:all 300ms ease}html.theme--documenter-dark .modal-card-body{background-color:#282f2f}html.theme--documenter-dark .modal-card-foot,html.theme--documenter-dark .modal-card-head{border-color:#343c3d}html.theme--documenter-dark .message-header{font-weight:700;background-color:#343c3d;color:#fff}html.theme--documenter-dark .message-body{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .navbar{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent{background:none}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar .navbar-menu{background-color:#375a7f;border-radius:0 0 .4em .4em}}html.theme--documenter-dark .hero .navbar,html.theme--documenter-dark body>.navbar{border-radius:0}html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous{border-width:1px}html.theme--documenter-dark .panel-block,html.theme--documenter-dark .panel-heading,html.theme--documenter-dark .panel-tabs{border-width:1px}html.theme--documenter-dark .panel-block:first-child,html.theme--documenter-dark .panel-heading:first-child,html.theme--documenter-dark .panel-tabs:first-child{border-top-width:1px}html.theme--documenter-dark .panel-heading{font-weight:700}html.theme--documenter-dark .panel-tabs a{border-width:1px;margin-bottom:-1px}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#17a689}html.theme--documenter-dark .panel-block:hover{color:#1dd2af}html.theme--documenter-dark .panel-block:hover .panel-icon{color:#1dd2af}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#17a689}html.theme--documenter-dark .tabs a{border-bottom-width:1px;margin-bottom:-1px}html.theme--documenter-dark .tabs ul{border-bottom-width:1px}html.theme--documenter-dark .tabs.is-boxed a{border-width:1px}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#1f2424}html.theme--documenter-dark .tabs.is-toggle li a{border-width:1px;margin-bottom:0}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .hero.is-white .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-black .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-light .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-dark .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .content kbd.hero .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-primary .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-link .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-info .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-success .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-warning .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-danger .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark h1 .docs-heading-anchor,html.theme--documenter-dark h1 .docs-heading-anchor:hover,html.theme--documenter-dark h1 .docs-heading-anchor:visited,html.theme--documenter-dark h2 .docs-heading-anchor,html.theme--documenter-dark h2 .docs-heading-anchor:hover,html.theme--documenter-dark h2 .docs-heading-anchor:visited,html.theme--documenter-dark h3 .docs-heading-anchor,html.theme--documenter-dark h3 .docs-heading-anchor:hover,html.theme--documenter-dark h3 .docs-heading-anchor:visited,html.theme--documenter-dark h4 .docs-heading-anchor,html.theme--documenter-dark h4 .docs-heading-anchor:hover,html.theme--documenter-dark h4 .docs-heading-anchor:visited,html.theme--documenter-dark h5 .docs-heading-anchor,html.theme--documenter-dark h5 .docs-heading-anchor:hover,html.theme--documenter-dark h5 .docs-heading-anchor:visited,html.theme--documenter-dark h6 .docs-heading-anchor,html.theme--documenter-dark h6 .docs-heading-anchor:hover,html.theme--documenter-dark h6 .docs-heading-anchor:visited{color:#f2f2f2}html.theme--documenter-dark h1 .docs-heading-anchor-permalink,html.theme--documenter-dark h2 .docs-heading-anchor-permalink,html.theme--documenter-dark h3 .docs-heading-anchor-permalink,html.theme--documenter-dark h4 .docs-heading-anchor-permalink,html.theme--documenter-dark h5 .docs-heading-anchor-permalink,html.theme--documenter-dark h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}html.theme--documenter-dark h1 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h2 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h3 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h4 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h5 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}html.theme--documenter-dark h1:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h2:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h3:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h4:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h5:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h6:hover .docs-heading-anchor-permalink{visibility:visible}html.theme--documenter-dark .docs-light-only{display:none !important}html.theme--documenter-dark pre{position:relative;overflow:hidden}html.theme--documenter-dark pre code,html.theme--documenter-dark pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}html.theme--documenter-dark pre code:first-of-type,html.theme--documenter-dark pre code.hljs:first-of-type{padding-top:0.5rem !important}html.theme--documenter-dark pre code:last-of-type,html.theme--documenter-dark pre code.hljs:last-of-type{padding-bottom:0.5rem !important}html.theme--documenter-dark pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#fff;cursor:pointer;text-align:center}html.theme--documenter-dark pre .copy-button:focus,html.theme--documenter-dark pre .copy-button:hover{opacity:1;background:rgba(255,255,255,0.1);color:#1abc9c}html.theme--documenter-dark pre .copy-button.success{color:#259a12;opacity:1}html.theme--documenter-dark pre .copy-button.error{color:#cb3c33;opacity:1}html.theme--documenter-dark pre:hover .copy-button{opacity:1}html.theme--documenter-dark .admonition{background-color:#282f2f;border-style:solid;border-width:1px;border-color:#5e6d6f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .admonition strong{color:currentColor}html.theme--documenter-dark .admonition.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}html.theme--documenter-dark .admonition.is-medium{font-size:1.25rem}html.theme--documenter-dark .admonition.is-large{font-size:1.5rem}html.theme--documenter-dark .admonition.is-default{background-color:#282f2f;border-color:#5e6d6f}html.theme--documenter-dark .admonition.is-default>.admonition-header{background-color:#5e6d6f;color:#fff}html.theme--documenter-dark .admonition.is-default>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-info{background-color:#282f2f;border-color:#024c7d}html.theme--documenter-dark .admonition.is-info>.admonition-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .admonition.is-info>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-success{background-color:#282f2f;border-color:#008438}html.theme--documenter-dark .admonition.is-success>.admonition-header{background-color:#008438;color:#fff}html.theme--documenter-dark .admonition.is-success>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-warning{background-color:#282f2f;border-color:#ad8100}html.theme--documenter-dark .admonition.is-warning>.admonition-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .admonition.is-warning>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-danger{background-color:#282f2f;border-color:#9e1b0d}html.theme--documenter-dark .admonition.is-danger>.admonition-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .admonition.is-danger>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-compat{background-color:#282f2f;border-color:#137886}html.theme--documenter-dark .admonition.is-compat>.admonition-header{background-color:#137886;color:#fff}html.theme--documenter-dark .admonition.is-compat>.admonition-body{color:#fff}html.theme--documenter-dark .admonition-header{color:#fff;background-color:#5e6d6f;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}html.theme--documenter-dark .admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}html.theme--documenter-dark details.admonition.is-details>.admonition-header{list-style:none}html.theme--documenter-dark details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}html.theme--documenter-dark details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}html.theme--documenter-dark .admonition-body{color:#fff;padding:0.5rem .75rem}html.theme--documenter-dark .admonition-body pre{background-color:#282f2f}html.theme--documenter-dark .admonition-body code{background-color:rgba(255,255,255,0.05)}html.theme--documenter-dark .docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #5e6d6f;box-shadow:none;max-width:100%}html.theme--documenter-dark .docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#282f2f;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #5e6d6f;overflow:auto}html.theme--documenter-dark .docstring>header code{background-color:transparent}html.theme--documenter-dark .docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}html.theme--documenter-dark .docstring>header .docstring-binding{margin-right:0.3em}html.theme--documenter-dark .docstring>header .docstring-category{margin-left:0.3em}html.theme--documenter-dark .docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .docstring>section:last-child{border-bottom:none}html.theme--documenter-dark .docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}html.theme--documenter-dark .docstring>section>a.docs-sourcelink:focus{opacity:1 !important}html.theme--documenter-dark .docstring:hover>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring>section:hover a.docs-sourcelink{opacity:1}html.theme--documenter-dark .documenter-example-output{background-color:#1f2424}html.theme--documenter-dark .outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#282f2f;color:#fff;border-bottom:3px solid #9e1b0d;padding:10px 35px;text-align:center;font-size:15px}html.theme--documenter-dark .outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}html.theme--documenter-dark .outdated-warning-overlay a{color:#1abc9c}html.theme--documenter-dark .outdated-warning-overlay a:hover{color:#1dd2af}html.theme--documenter-dark .content pre{border:1px solid #5e6d6f}html.theme--documenter-dark .content code{font-weight:inherit}html.theme--documenter-dark .content a code{color:#1abc9c}html.theme--documenter-dark .content h1 code,html.theme--documenter-dark .content h2 code,html.theme--documenter-dark .content h3 code,html.theme--documenter-dark .content h4 code,html.theme--documenter-dark .content h5 code,html.theme--documenter-dark .content h6 code{color:#f2f2f2}html.theme--documenter-dark .content table{display:block;width:initial;max-width:100%;overflow-x:auto}html.theme--documenter-dark .content blockquote>ul:first-child,html.theme--documenter-dark .content blockquote>ol:first-child,html.theme--documenter-dark .content .admonition-body>ul:first-child,html.theme--documenter-dark .content .admonition-body>ol:first-child{margin-top:0}html.theme--documenter-dark pre,html.theme--documenter-dark code{font-variant-ligatures:no-contextual}html.theme--documenter-dark .breadcrumb a.is-disabled{cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb a.is-disabled,html.theme--documenter-dark .breadcrumb a.is-disabled:hover{color:#f2f2f2}html.theme--documenter-dark .hljs{background:initial !important}html.theme--documenter-dark .katex .katex-mathml{top:0;right:0}html.theme--documenter-dark .katex-display,html.theme--documenter-dark mjx-container,html.theme--documenter-dark .MathJax_Display{margin:0.5em 0 !important}html.theme--documenter-dark html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}html.theme--documenter-dark li.no-marker{list-style:none}html.theme--documenter-dark #documenter .docs-main>article{overflow-wrap:break-word}html.theme--documenter-dark #documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main{width:100%}html.theme--documenter-dark #documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-main>header,html.theme--documenter-dark #documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar{background-color:#1f2424;border-bottom:1px solid #5e6d6f;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-icon,html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #171717;transition-duration:0.7s;-webkit-transition-duration:0.7s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}html.theme--documenter-dark #documenter .docs-main section.footnotes{border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-main section.footnotes li .tag:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .content kbd:first-child,html.theme--documenter-dark .content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}html.theme--documenter-dark #documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #5e6d6f;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage,html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}html.theme--documenter-dark #documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}html.theme--documenter-dark #documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}html.theme--documenter-dark #documenter .docs-sidebar{display:flex;flex-direction:column;color:#fff;background-color:#282f2f;border-right:1px solid #5e6d6f;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}html.theme--documenter-dark #documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #171717}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar{left:0;top:0}}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a,html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a:hover{color:#fff}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector{border-top:1px solid #5e6d6f;display:none;padding:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector.visible{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #5e6d6f;padding-bottom:1.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#fff;background:#282f2f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu a.tocitem:hover,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#fff;background-color:#32393a}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #5e6d6f;border-bottom:1px solid #5e6d6f;background-color:#1f2424}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#1f2424;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#32393a;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{width:14.4rem}html.theme--documenter-dark #documenter .docs-sidebar #documenter-search-query{color:#868c98;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}html.theme--documenter-dark kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(245,245,245,0.6);box-shadow:0 2px 0 1px rgba(245,245,245,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}html.theme--documenter-dark .search-min-width-50{min-width:50%}html.theme--documenter-dark .search-min-height-100{min-height:100%}html.theme--documenter-dark .search-modal-card-body{max-height:calc(100vh - 15rem)}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333;background-color:#f1f5f9}html.theme--documenter-dark .search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}html.theme--documenter-dark .search-filter:hover,html.theme--documenter-dark .search-filter:focus{color:#333}html.theme--documenter-dark .search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}html.theme--documenter-dark .search-filter-selected:hover,html.theme--documenter-dark .search-filter-selected:focus{color:#f5f5f5}html.theme--documenter-dark .search-result-highlight{background-color:#ffdd57;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .search-result-title{width:85%;color:#f5f5f5}html.theme--documenter-dark .search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-thumb,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-track,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem}html.theme--documenter-dark .gap-8{gap:2rem}html.theme--documenter-dark{background-color:#1f2424;font-size:16px;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark .ansi span.sgr1{font-weight:bolder}html.theme--documenter-dark .ansi span.sgr2{font-weight:lighter}html.theme--documenter-dark .ansi span.sgr3{font-style:italic}html.theme--documenter-dark .ansi span.sgr4{text-decoration:underline}html.theme--documenter-dark .ansi span.sgr7{color:#1f2424;background-color:#fff}html.theme--documenter-dark .ansi span.sgr8{color:transparent}html.theme--documenter-dark .ansi span.sgr8 span{color:transparent}html.theme--documenter-dark .ansi span.sgr9{text-decoration:line-through}html.theme--documenter-dark .ansi span.sgr30{color:#242424}html.theme--documenter-dark .ansi span.sgr31{color:#f6705f}html.theme--documenter-dark .ansi span.sgr32{color:#4fb43a}html.theme--documenter-dark .ansi span.sgr33{color:#f4c72f}html.theme--documenter-dark .ansi span.sgr34{color:#7587f0}html.theme--documenter-dark .ansi span.sgr35{color:#bc89d3}html.theme--documenter-dark .ansi span.sgr36{color:#49b6ca}html.theme--documenter-dark .ansi span.sgr37{color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr40{background-color:#242424}html.theme--documenter-dark .ansi span.sgr41{background-color:#f6705f}html.theme--documenter-dark .ansi span.sgr42{background-color:#4fb43a}html.theme--documenter-dark .ansi span.sgr43{background-color:#f4c72f}html.theme--documenter-dark .ansi span.sgr44{background-color:#7587f0}html.theme--documenter-dark .ansi span.sgr45{background-color:#bc89d3}html.theme--documenter-dark .ansi span.sgr46{background-color:#49b6ca}html.theme--documenter-dark .ansi span.sgr47{background-color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr90{color:#92a0a2}html.theme--documenter-dark .ansi span.sgr91{color:#ff8674}html.theme--documenter-dark .ansi span.sgr92{color:#79d462}html.theme--documenter-dark .ansi span.sgr93{color:#ffe76b}html.theme--documenter-dark .ansi span.sgr94{color:#8a98ff}html.theme--documenter-dark .ansi span.sgr95{color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr96{color:#6bc8db}html.theme--documenter-dark .ansi span.sgr97{color:#ecf0f1}html.theme--documenter-dark .ansi span.sgr100{background-color:#92a0a2}html.theme--documenter-dark .ansi span.sgr101{background-color:#ff8674}html.theme--documenter-dark .ansi span.sgr102{background-color:#79d462}html.theme--documenter-dark .ansi span.sgr103{background-color:#ffe76b}html.theme--documenter-dark .ansi span.sgr104{background-color:#8a98ff}html.theme--documenter-dark .ansi span.sgr105{background-color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr106{background-color:#6bc8db}html.theme--documenter-dark .ansi span.sgr107{background-color:#ecf0f1}html.theme--documenter-dark code.language-julia-repl>span.hljs-meta{color:#4fb43a;font-weight:bolder}html.theme--documenter-dark .hljs{background:#2b2b2b;color:#f8f8f2}html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-quote{color:#d4d0ab}html.theme--documenter-dark .hljs-variable,html.theme--documenter-dark .hljs-template-variable,html.theme--documenter-dark .hljs-tag,html.theme--documenter-dark .hljs-name,html.theme--documenter-dark .hljs-selector-id,html.theme--documenter-dark .hljs-selector-class,html.theme--documenter-dark .hljs-regexp,html.theme--documenter-dark .hljs-deletion{color:#ffa07a}html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-link{color:#f5ab35}html.theme--documenter-dark .hljs-attribute{color:#ffd700}html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-addition{color:#abe338}html.theme--documenter-dark .hljs-title,html.theme--documenter-dark .hljs-section{color:#00e0e0}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{color:#dcc6e0}html.theme--documenter-dark .hljs-emphasis{font-style:italic}html.theme--documenter-dark .hljs-strong{font-weight:bold}@media screen and (-ms-high-contrast: active){html.theme--documenter-dark .hljs-addition,html.theme--documenter-dark .hljs-attribute,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-link,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-quote{color:highlight}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{font-weight:bold}}html.theme--documenter-dark .hljs-subst{color:#f8f8f2}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333 !important;background-color:#f1f5f9 !important}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:whitesmoke;background-color:#33415580;border-radius:0.6rem}html.theme--documenter-dark .search-result-title{color:whitesmoke}html.theme--documenter-dark .search-result-highlight{background-color:greenyellow;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f50}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem} diff --git a/v2.16.1/assets/themes/documenter-light.css b/v2.16.1/assets/themes/documenter-light.css new file mode 100644 index 000000000..2f168c77b --- /dev/null +++ b/v2.16.1/assets/themes/documenter-light.css @@ -0,0 +1,9 @@ +.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.file-cta,.file-name,.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input,.button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:4px;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus,.pagination-ellipsis:focus,.file-cta:focus,.file-name:focus,.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.button:focus,.is-focused.pagination-previous,.is-focused.pagination-next,.is-focused.pagination-link,.is-focused.pagination-ellipsis,.is-focused.file-cta,.is-focused.file-name,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-focused.button,.pagination-previous:active,.pagination-next:active,.pagination-link:active,.pagination-ellipsis:active,.file-cta:active,.file-name:active,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.button:active,.is-active.pagination-previous,.is-active.pagination-next,.is-active.pagination-link,.is-active.pagination-ellipsis,.is-active.file-cta,.is-active.file-name,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.is-active.button{outline:none}.pagination-previous[disabled],.pagination-next[disabled],.pagination-link[disabled],.pagination-ellipsis[disabled],.file-cta[disabled],.file-name[disabled],.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],.button[disabled],fieldset[disabled] .pagination-previous,fieldset[disabled] .pagination-next,fieldset[disabled] .pagination-link,fieldset[disabled] .pagination-ellipsis,fieldset[disabled] .file-cta,fieldset[disabled] .file-name,fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] .button{cursor:not-allowed}.tabs,.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.breadcrumb,.file,.button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.navbar-link:not(.is-arrowless)::after,.select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}.admonition:not(:last-child),.tabs:not(:last-child),.pagination:not(:last-child),.message:not(:last-child),.level:not(:last-child),.breadcrumb:not(:last-child),.block:not(:last-child),.title:not(:last-child),.subtitle:not(:last-child),.table-container:not(:last-child),.table:not(:last-child),.progress:not(:last-child),.notification:not(:last-child),.content:not(:last-child),.box:not(:last-child){margin-bottom:1.5rem}.modal-close,.delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}.modal-close::before,.delete::before,.modal-close::after,.delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.modal-close::before,.delete::before{height:2px;width:50%}.modal-close::after,.delete::after{height:50%;width:2px}.modal-close:hover,.delete:hover,.modal-close:focus,.delete:focus{background-color:rgba(10,10,10,0.3)}.modal-close:active,.delete:active{background-color:rgba(10,10,10,0.4)}.is-small.modal-close,#documenter .docs-sidebar form.docs-search>input.modal-close,.is-small.delete,#documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}.is-medium.modal-close,.is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}.is-large.modal-close,.is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}.control.is-loading::after,.select.is-loading::after,.loader,.button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdbdb;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}.hero-video,.modal-background,.modal,.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}.navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#f5f5f5 !important}a.has-text-light:hover,a.has-text-light:focus{color:#dbdbdb !important}.has-background-light{background-color:#f5f5f5 !important}.has-text-dark{color:#363636 !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#1c1c1c !important}.has-background-dark{background-color:#363636 !important}.has-text-primary{color:#4eb5de !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#27a1d2 !important}.has-background-primary{background-color:#4eb5de !important}.has-text-primary-light{color:#eef8fc !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#c3e6f4 !important}.has-background-primary-light{background-color:#eef8fc !important}.has-text-primary-dark{color:#1a6d8e !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#228eb9 !important}.has-background-primary-dark{background-color:#1a6d8e !important}.has-text-link{color:#2e63b8 !important}a.has-text-link:hover,a.has-text-link:focus{color:#244d8f !important}.has-background-link{background-color:#2e63b8 !important}.has-text-link-light{color:#eff3fb !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c6d6f1 !important}.has-background-link-light{background-color:#eff3fb !important}.has-text-link-dark{color:#3169c4 !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#5485d4 !important}.has-background-link-dark{background-color:#3169c4 !important}.has-text-info{color:#209cee !important}a.has-text-info:hover,a.has-text-info:focus{color:#1081cb !important}.has-background-info{background-color:#209cee !important}.has-text-info-light{color:#ecf7fe !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#bde2fa !important}.has-background-info-light{background-color:#ecf7fe !important}.has-text-info-dark{color:#0e72b4 !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#1190e3 !important}.has-background-info-dark{background-color:#0e72b4 !important}.has-text-success{color:#22c35b !important}a.has-text-success:hover,a.has-text-success:focus{color:#1a9847 !important}.has-background-success{background-color:#22c35b !important}.has-text-success-light{color:#eefcf3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#c2f4d4 !important}.has-background-success-light{background-color:#eefcf3 !important}.has-text-success-dark{color:#198f43 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#21bb57 !important}.has-background-success-dark{background-color:#198f43 !important}.has-text-warning{color:#ffdd57 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#ffd324 !important}.has-background-warning{background-color:#ffdd57 !important}.has-text-warning-light{color:#fffbeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#fff1b8 !important}.has-background-warning-light{background-color:#fffbeb !important}.has-text-warning-dark{color:#947600 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#c79f00 !important}.has-background-warning-dark{background-color:#947600 !important}.has-text-danger{color:#da0b00 !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#a70800 !important}.has-background-danger{background-color:#da0b00 !important}.has-text-danger-light{color:#ffeceb !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#ffbbb8 !important}.has-background-danger-light{background-color:#ffeceb !important}.has-text-danger-dark{color:#f50c00 !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#ff3429 !important}.has-background-danger-dark{background-color:#f50c00 !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#363636 !important}.has-background-grey-darker{background-color:#363636 !important}.has-text-grey-dark{color:#4a4a4a !important}.has-background-grey-dark{background-color:#4a4a4a !important}.has-text-grey{color:#6b6b6b !important}.has-background-grey{background-color:#6b6b6b !important}.has-text-grey-light{color:#b5b5b5 !important}.has-background-grey-light{background-color:#b5b5b5 !important}.has-text-grey-lighter{color:#dbdbdb !important}.has-background-grey-lighter{background-color:#dbdbdb !important}.has-text-white-ter{color:#f5f5f5 !important}.has-background-white-ter{background-color:#f5f5f5 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,.docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}html{background-color:#fff;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}article,aside,figure,footer,header,hgroup,section{display:block}body,button,input,optgroup,select,textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}code,pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}body{color:#222;font-size:1em;font-weight:400;line-height:1.5}a{color:#2e63b8;cursor:pointer;text-decoration:none}a strong{color:currentColor}a:hover{color:#363636}code{background-color:rgba(0,0,0,0.05);color:#000;font-size:.875em;font-weight:normal;padding:.1em}hr{background-color:#f5f5f5;border:none;display:block;height:2px;margin:1.5rem 0}img{height:auto;max-width:100%}input[type="checkbox"],input[type="radio"]{vertical-align:baseline}small{font-size:.875em}span{font-style:inherit;font-weight:inherit}strong{color:#222;font-weight:700}fieldset{border:none}pre{-webkit-overflow-scrolling:touch;background-color:#f5f5f5;color:#222;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}table td,table th{vertical-align:top}table td:not([align]),table th:not([align]){text-align:inherit}table th{color:#222}@keyframes spinAround{from{transform:rotate(0deg)}to{transform:rotate(359deg)}}.box{background-color:#fff;border-radius:6px;box-shadow:#bbb;color:#222;display:block;padding:1.25rem}a.box:hover,a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #2e63b8}a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #2e63b8}.button{background-color:#fff;border-color:#dbdbdb;border-width:1px;color:#222;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}.button strong{color:inherit}.button .icon,.button .icon.is-small,.button #documenter .docs-sidebar form.docs-search>input.icon,#documenter .docs-sidebar .button form.docs-search>input.icon,.button .icon.is-medium,.button .icon.is-large{height:1.5em;width:1.5em}.button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}.button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}.button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}.button:hover,.button.is-hovered{border-color:#b5b5b5;color:#363636}.button:focus,.button.is-focused{border-color:#3c5dcd;color:#363636}.button:focus:not(:active),.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button:active,.button.is-active{border-color:#4a4a4a;color:#363636}.button.is-text{background-color:transparent;border-color:transparent;color:#222;text-decoration:underline}.button.is-text:hover,.button.is-text.is-hovered,.button.is-text:focus,.button.is-text.is-focused{background-color:#f5f5f5;color:#222}.button.is-text:active,.button.is-text.is-active{background-color:#e8e8e8;color:#222}.button.is-text[disabled],fieldset[disabled] .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}.button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#2e63b8;text-decoration:none}.button.is-ghost:hover,.button.is-ghost.is-hovered{color:#2e63b8;text-decoration:underline}.button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}.button.is-white:hover,.button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.button.is-white:focus,.button.is-white.is-focused{border-color:transparent;color:#0a0a0a}.button.is-white:focus:not(:active),.button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.button.is-white:active,.button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.button.is-white[disabled],fieldset[disabled] .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}.button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted:hover,.button.is-white.is-inverted.is-hovered{background-color:#000}.button.is-white.is-inverted[disabled],fieldset[disabled] .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}.button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-white.is-outlined:hover,.button.is-white.is-outlined.is-hovered,.button.is-white.is-outlined:focus,.button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}.button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-outlined.is-loading:hover::after,.button.is-white.is-outlined.is-loading.is-hovered::after,.button.is-white.is-outlined.is-loading:focus::after,.button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined[disabled],fieldset[disabled] .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-white.is-inverted.is-outlined:hover,.button.is-white.is-inverted.is-outlined.is-hovered,.button.is-white.is-inverted.is-outlined:focus,.button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted.is-outlined.is-loading:hover::after,.button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-white.is-inverted.is-outlined.is-loading:focus::after,.button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}.button.is-black:hover,.button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}.button.is-black:focus,.button.is-black.is-focused{border-color:transparent;color:#fff}.button.is-black:focus:not(:active),.button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.button.is-black:active,.button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}.button.is-black[disabled],fieldset[disabled] .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}.button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted:hover,.button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-black.is-inverted[disabled],fieldset[disabled] .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}.button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-black.is-outlined:hover,.button.is-black.is-outlined.is-hovered,.button.is-black.is-outlined:focus,.button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-outlined.is-loading:hover::after,.button.is-black.is-outlined.is-loading.is-hovered::after,.button.is-black.is-outlined.is-loading:focus::after,.button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined[disabled],fieldset[disabled] .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-black.is-inverted.is-outlined:hover,.button.is-black.is-inverted.is-outlined.is-hovered,.button.is-black.is-inverted.is-outlined:focus,.button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted.is-outlined.is-loading:hover::after,.button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-black.is-inverted.is-outlined.is-loading:focus::after,.button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-light{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:hover,.button.is-light.is-hovered{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus,.button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus:not(:active),.button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.button.is-light:active,.button.is-light.is-active{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light[disabled],fieldset[disabled] .button.is-light{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none}.button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted:hover,.button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-light.is-inverted[disabled],fieldset[disabled] .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#f5f5f5}.button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;color:#f5f5f5}.button.is-light.is-outlined:hover,.button.is-light.is-outlined.is-hovered,.button.is-light.is-outlined:focus,.button.is-light.is-outlined.is-focused{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-outlined.is-loading:hover::after,.button.is-light.is-outlined.is-loading.is-hovered::after,.button.is-light.is-outlined.is-loading:focus::after,.button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined[disabled],fieldset[disabled] .button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;box-shadow:none;color:#f5f5f5}.button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-light.is-inverted.is-outlined:hover,.button.is-light.is-inverted.is-outlined.is-hovered,.button.is-light.is-inverted.is-outlined:focus,.button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted.is-outlined.is-loading:hover::after,.button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-light.is-inverted.is-outlined.is-loading:focus::after,.button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-dark,.content kbd.button{background-color:#363636;border-color:transparent;color:#fff}.button.is-dark:hover,.content kbd.button:hover,.button.is-dark.is-hovered,.content kbd.button.is-hovered{background-color:#2f2f2f;border-color:transparent;color:#fff}.button.is-dark:focus,.content kbd.button:focus,.button.is-dark.is-focused,.content kbd.button.is-focused{border-color:transparent;color:#fff}.button.is-dark:focus:not(:active),.content kbd.button:focus:not(:active),.button.is-dark.is-focused:not(:active),.content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.button.is-dark:active,.content kbd.button:active,.button.is-dark.is-active,.content kbd.button.is-active{background-color:#292929;border-color:transparent;color:#fff}.button.is-dark[disabled],.content kbd.button[disabled],fieldset[disabled] .button.is-dark,fieldset[disabled] .content kbd.button,.content fieldset[disabled] kbd.button{background-color:#363636;border-color:#363636;box-shadow:none}.button.is-dark.is-inverted,.content kbd.button.is-inverted{background-color:#fff;color:#363636}.button.is-dark.is-inverted:hover,.content kbd.button.is-inverted:hover,.button.is-dark.is-inverted.is-hovered,.content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-dark.is-inverted[disabled],.content kbd.button.is-inverted[disabled],fieldset[disabled] .button.is-dark.is-inverted,fieldset[disabled] .content kbd.button.is-inverted,.content fieldset[disabled] kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#363636}.button.is-dark.is-loading::after,.content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined,.content kbd.button.is-outlined{background-color:transparent;border-color:#363636;color:#363636}.button.is-dark.is-outlined:hover,.content kbd.button.is-outlined:hover,.button.is-dark.is-outlined.is-hovered,.content kbd.button.is-outlined.is-hovered,.button.is-dark.is-outlined:focus,.content kbd.button.is-outlined:focus,.button.is-dark.is-outlined.is-focused,.content kbd.button.is-outlined.is-focused{background-color:#363636;border-color:#363636;color:#fff}.button.is-dark.is-outlined.is-loading::after,.content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-outlined.is-loading:hover::after,.content kbd.button.is-outlined.is-loading:hover::after,.button.is-dark.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-outlined.is-loading:focus::after,.content kbd.button.is-outlined.is-loading:focus::after,.button.is-dark.is-outlined.is-loading.is-focused::after,.content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined[disabled],.content kbd.button.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-outlined,fieldset[disabled] .content kbd.button.is-outlined,.content fieldset[disabled] kbd.button.is-outlined{background-color:transparent;border-color:#363636;box-shadow:none;color:#363636}.button.is-dark.is-inverted.is-outlined,.content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-dark.is-inverted.is-outlined:hover,.content kbd.button.is-inverted.is-outlined:hover,.button.is-dark.is-inverted.is-outlined.is-hovered,.content kbd.button.is-inverted.is-outlined.is-hovered,.button.is-dark.is-inverted.is-outlined:focus,.content kbd.button.is-inverted.is-outlined:focus,.button.is-dark.is-inverted.is-outlined.is-focused,.content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#363636}.button.is-dark.is-inverted.is-outlined.is-loading:hover::after,.content kbd.button.is-inverted.is-outlined.is-loading:hover::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-inverted.is-outlined.is-loading:focus::after,.content kbd.button.is-inverted.is-outlined.is-loading:focus::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-inverted.is-outlined[disabled],.content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-inverted.is-outlined,fieldset[disabled] .content kbd.button.is-inverted.is-outlined,.content fieldset[disabled] kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary,.docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:transparent;color:#fff}.button.is-primary:hover,.docstring>section>a.button.docs-sourcelink:hover,.button.is-primary.is-hovered,.docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#43b1dc;border-color:transparent;color:#fff}.button.is-primary:focus,.docstring>section>a.button.docs-sourcelink:focus,.button.is-primary.is-focused,.docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}.button.is-primary:focus:not(:active),.docstring>section>a.button.docs-sourcelink:focus:not(:active),.button.is-primary.is-focused:not(:active),.docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.button.is-primary:active,.docstring>section>a.button.docs-sourcelink:active,.button.is-primary.is-active,.docstring>section>a.button.is-active.docs-sourcelink{background-color:#39acda;border-color:transparent;color:#fff}.button.is-primary[disabled],.docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary,fieldset[disabled] .docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;box-shadow:none}.button.is-primary.is-inverted,.docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted:hover,.docstring>section>a.button.is-inverted.docs-sourcelink:hover,.button.is-primary.is-inverted.is-hovered,.docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}.button.is-primary.is-inverted[disabled],.docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted,fieldset[disabled] .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#4eb5de}.button.is-primary.is-loading::after,.docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined,.docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;color:#4eb5de}.button.is-primary.is-outlined:hover,.docstring>section>a.button.is-outlined.docs-sourcelink:hover,.button.is-primary.is-outlined.is-hovered,.docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-outlined:focus,.docstring>section>a.button.is-outlined.docs-sourcelink:focus,.button.is-primary.is-outlined.is-focused,.docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.button.is-primary.is-outlined.is-loading::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined[disabled],.docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-outlined,fieldset[disabled] .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;box-shadow:none;color:#4eb5de}.button.is-primary.is-inverted.is-outlined,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}.button.is-primary.is-inverted.is-outlined:hover,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,.button.is-primary.is-inverted.is-outlined.is-hovered,.docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-inverted.is-outlined:focus,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,.button.is-primary.is-inverted.is-outlined.is-focused,.docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-inverted.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-inverted.is-outlined[disabled],.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted.is-outlined,fieldset[disabled] .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary.is-light,.docstring>section>a.button.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.button.is-primary.is-light:hover,.docstring>section>a.button.is-light.docs-sourcelink:hover,.button.is-primary.is-light.is-hovered,.docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e3f3fa;border-color:transparent;color:#1a6d8e}.button.is-primary.is-light:active,.docstring>section>a.button.is-light.docs-sourcelink:active,.button.is-primary.is-light.is-active,.docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#d8eff8;border-color:transparent;color:#1a6d8e}.button.is-link{background-color:#2e63b8;border-color:transparent;color:#fff}.button.is-link:hover,.button.is-link.is-hovered{background-color:#2b5eae;border-color:transparent;color:#fff}.button.is-link:focus,.button.is-link.is-focused{border-color:transparent;color:#fff}.button.is-link:focus:not(:active),.button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button.is-link:active,.button.is-link.is-active{background-color:#2958a4;border-color:transparent;color:#fff}.button.is-link[disabled],fieldset[disabled] .button.is-link{background-color:#2e63b8;border-color:#2e63b8;box-shadow:none}.button.is-link.is-inverted{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted:hover,.button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-link.is-inverted[disabled],fieldset[disabled] .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#2e63b8}.button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;color:#2e63b8}.button.is-link.is-outlined:hover,.button.is-link.is-outlined.is-hovered,.button.is-link.is-outlined:focus,.button.is-link.is-outlined.is-focused{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-outlined.is-loading:hover::after,.button.is-link.is-outlined.is-loading.is-hovered::after,.button.is-link.is-outlined.is-loading:focus::after,.button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined[disabled],fieldset[disabled] .button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;box-shadow:none;color:#2e63b8}.button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-link.is-inverted.is-outlined:hover,.button.is-link.is-inverted.is-outlined.is-hovered,.button.is-link.is-inverted.is-outlined:focus,.button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted.is-outlined.is-loading:hover::after,.button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-link.is-inverted.is-outlined.is-loading:focus::after,.button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-link.is-light{background-color:#eff3fb;color:#3169c4}.button.is-link.is-light:hover,.button.is-link.is-light.is-hovered{background-color:#e4ecf8;border-color:transparent;color:#3169c4}.button.is-link.is-light:active,.button.is-link.is-light.is-active{background-color:#dae5f6;border-color:transparent;color:#3169c4}.button.is-info{background-color:#209cee;border-color:transparent;color:#fff}.button.is-info:hover,.button.is-info.is-hovered{background-color:#1497ed;border-color:transparent;color:#fff}.button.is-info:focus,.button.is-info.is-focused{border-color:transparent;color:#fff}.button.is-info:focus:not(:active),.button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.button.is-info:active,.button.is-info.is-active{background-color:#1190e3;border-color:transparent;color:#fff}.button.is-info[disabled],fieldset[disabled] .button.is-info{background-color:#209cee;border-color:#209cee;box-shadow:none}.button.is-info.is-inverted{background-color:#fff;color:#209cee}.button.is-info.is-inverted:hover,.button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-info.is-inverted[disabled],fieldset[disabled] .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#209cee}.button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined{background-color:transparent;border-color:#209cee;color:#209cee}.button.is-info.is-outlined:hover,.button.is-info.is-outlined.is-hovered,.button.is-info.is-outlined:focus,.button.is-info.is-outlined.is-focused{background-color:#209cee;border-color:#209cee;color:#fff}.button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-outlined.is-loading:hover::after,.button.is-info.is-outlined.is-loading.is-hovered::after,.button.is-info.is-outlined.is-loading:focus::after,.button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined[disabled],fieldset[disabled] .button.is-info.is-outlined{background-color:transparent;border-color:#209cee;box-shadow:none;color:#209cee}.button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-info.is-inverted.is-outlined:hover,.button.is-info.is-inverted.is-outlined.is-hovered,.button.is-info.is-inverted.is-outlined:focus,.button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#209cee}.button.is-info.is-inverted.is-outlined.is-loading:hover::after,.button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-info.is-inverted.is-outlined.is-loading:focus::after,.button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.button.is-info.is-light:hover,.button.is-info.is-light.is-hovered{background-color:#e0f1fd;border-color:transparent;color:#0e72b4}.button.is-info.is-light:active,.button.is-info.is-light.is-active{background-color:#d4ecfc;border-color:transparent;color:#0e72b4}.button.is-success{background-color:#22c35b;border-color:transparent;color:#fff}.button.is-success:hover,.button.is-success.is-hovered{background-color:#20b856;border-color:transparent;color:#fff}.button.is-success:focus,.button.is-success.is-focused{border-color:transparent;color:#fff}.button.is-success:focus:not(:active),.button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.button.is-success:active,.button.is-success.is-active{background-color:#1ead51;border-color:transparent;color:#fff}.button.is-success[disabled],fieldset[disabled] .button.is-success{background-color:#22c35b;border-color:#22c35b;box-shadow:none}.button.is-success.is-inverted{background-color:#fff;color:#22c35b}.button.is-success.is-inverted:hover,.button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-success.is-inverted[disabled],fieldset[disabled] .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#22c35b}.button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;color:#22c35b}.button.is-success.is-outlined:hover,.button.is-success.is-outlined.is-hovered,.button.is-success.is-outlined:focus,.button.is-success.is-outlined.is-focused{background-color:#22c35b;border-color:#22c35b;color:#fff}.button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-outlined.is-loading:hover::after,.button.is-success.is-outlined.is-loading.is-hovered::after,.button.is-success.is-outlined.is-loading:focus::after,.button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined[disabled],fieldset[disabled] .button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;box-shadow:none;color:#22c35b}.button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-success.is-inverted.is-outlined:hover,.button.is-success.is-inverted.is-outlined.is-hovered,.button.is-success.is-inverted.is-outlined:focus,.button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#22c35b}.button.is-success.is-inverted.is-outlined.is-loading:hover::after,.button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-success.is-inverted.is-outlined.is-loading:focus::after,.button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-success.is-light{background-color:#eefcf3;color:#198f43}.button.is-success.is-light:hover,.button.is-success.is-light.is-hovered{background-color:#e3faeb;border-color:transparent;color:#198f43}.button.is-success.is-light:active,.button.is-success.is-light.is-active{background-color:#d8f8e3;border-color:transparent;color:#198f43}.button.is-warning{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:hover,.button.is-warning.is-hovered{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus,.button.is-warning.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus:not(:active),.button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.button.is-warning:active,.button.is-warning.is-active{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning[disabled],fieldset[disabled] .button.is-warning{background-color:#ffdd57;border-color:#ffdd57;box-shadow:none}.button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted:hover,.button.is-warning.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted[disabled],fieldset[disabled] .button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ffdd57}.button.is-warning.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;color:#ffdd57}.button.is-warning.is-outlined:hover,.button.is-warning.is-outlined.is-hovered,.button.is-warning.is-outlined:focus,.button.is-warning.is-outlined.is-focused{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-outlined.is-loading:hover::after,.button.is-warning.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-outlined.is-loading:focus::after,.button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;box-shadow:none;color:#ffdd57}.button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted.is-outlined:hover,.button.is-warning.is-inverted.is-outlined.is-hovered,.button.is-warning.is-inverted.is-outlined:focus,.button.is-warning.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted.is-outlined.is-loading:hover::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-inverted.is-outlined.is-loading:focus::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-warning.is-light{background-color:#fffbeb;color:#947600}.button.is-warning.is-light:hover,.button.is-warning.is-light.is-hovered{background-color:#fff8de;border-color:transparent;color:#947600}.button.is-warning.is-light:active,.button.is-warning.is-light.is-active{background-color:#fff6d1;border-color:transparent;color:#947600}.button.is-danger{background-color:#da0b00;border-color:transparent;color:#fff}.button.is-danger:hover,.button.is-danger.is-hovered{background-color:#cd0a00;border-color:transparent;color:#fff}.button.is-danger:focus,.button.is-danger.is-focused{border-color:transparent;color:#fff}.button.is-danger:focus:not(:active),.button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.button.is-danger:active,.button.is-danger.is-active{background-color:#c10a00;border-color:transparent;color:#fff}.button.is-danger[disabled],fieldset[disabled] .button.is-danger{background-color:#da0b00;border-color:#da0b00;box-shadow:none}.button.is-danger.is-inverted{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted:hover,.button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-danger.is-inverted[disabled],fieldset[disabled] .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#da0b00}.button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;color:#da0b00}.button.is-danger.is-outlined:hover,.button.is-danger.is-outlined.is-hovered,.button.is-danger.is-outlined:focus,.button.is-danger.is-outlined.is-focused{background-color:#da0b00;border-color:#da0b00;color:#fff}.button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-outlined.is-loading:hover::after,.button.is-danger.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-outlined.is-loading:focus::after,.button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;box-shadow:none;color:#da0b00}.button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-danger.is-inverted.is-outlined:hover,.button.is-danger.is-inverted.is-outlined.is-hovered,.button.is-danger.is-inverted.is-outlined:focus,.button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted.is-outlined.is-loading:hover::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-inverted.is-outlined.is-loading:focus::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.button.is-danger.is-light:hover,.button.is-danger.is-light.is-hovered{background-color:#ffe0de;border-color:transparent;color:#f50c00}.button.is-danger.is-light:active,.button.is-danger.is-light.is-active{background-color:#ffd3d1;border-color:transparent;color:#f50c00}.button.is-small,#documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}.button.is-small:not(.is-rounded),#documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:2px}.button.is-normal{font-size:1rem}.button.is-medium{font-size:1.25rem}.button.is-large{font-size:1.5rem}.button[disabled],fieldset[disabled] .button{background-color:#fff;border-color:#dbdbdb;box-shadow:none;opacity:.5}.button.is-fullwidth{display:flex;width:100%}.button.is-loading{color:transparent !important;pointer-events:none}.button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}.button.is-static{background-color:#f5f5f5;border-color:#dbdbdb;color:#6b6b6b;box-shadow:none;pointer-events:none}.button.is-rounded,#documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}.buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.buttons .button{margin-bottom:0.5rem}.buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}.buttons:last-child{margin-bottom:-0.5rem}.buttons:not(:last-child){margin-bottom:1rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:2px}.buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}.buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}.buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}.buttons.has-addons .button:last-child{margin-right:0}.buttons.has-addons .button:hover,.buttons.has-addons .button.is-hovered{z-index:2}.buttons.has-addons .button:focus,.buttons.has-addons .button.is-focused,.buttons.has-addons .button:active,.buttons.has-addons .button.is-active,.buttons.has-addons .button.is-selected{z-index:3}.buttons.has-addons .button:focus:hover,.buttons.has-addons .button.is-focused:hover,.buttons.has-addons .button:active:hover,.buttons.has-addons .button.is-active:hover,.buttons.has-addons .button.is-selected:hover{z-index:4}.buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}.buttons.is-centered{justify-content:center}.buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}.buttons.is-right{justify-content:flex-end}.buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.65625rem}.button.is-responsive.is-medium{font-size:.75rem}.button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.75rem}.button.is-responsive.is-medium{font-size:1rem}.button.is-responsive.is-large{font-size:1.25rem}}.container{flex-grow:1;margin:0 auto;position:relative;width:auto}.container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){.container{max-width:992px}}@media screen and (max-width: 1215px){.container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){.container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){.container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){.container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}.content li+li{margin-top:0.25em}.content p:not(:last-child),.content dl:not(:last-child),.content ol:not(:last-child),.content ul:not(:last-child),.content blockquote:not(:last-child),.content pre:not(:last-child),.content table:not(:last-child){margin-bottom:1em}.content h1,.content h2,.content h3,.content h4,.content h5,.content h6{color:#222;font-weight:600;line-height:1.125}.content h1{font-size:2em;margin-bottom:0.5em}.content h1:not(:first-child){margin-top:1em}.content h2{font-size:1.75em;margin-bottom:0.5714em}.content h2:not(:first-child){margin-top:1.1428em}.content h3{font-size:1.5em;margin-bottom:0.6666em}.content h3:not(:first-child){margin-top:1.3333em}.content h4{font-size:1.25em;margin-bottom:0.8em}.content h5{font-size:1.125em;margin-bottom:0.8888em}.content h6{font-size:1em;margin-bottom:1em}.content blockquote{background-color:#f5f5f5;border-left:5px solid #dbdbdb;padding:1.25em 1.5em}.content ol{list-style-position:outside;margin-left:2em;margin-top:1em}.content ol:not([type]){list-style-type:decimal}.content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}.content ol.is-lower-roman:not([type]){list-style-type:lower-roman}.content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}.content ol.is-upper-roman:not([type]){list-style-type:upper-roman}.content ul{list-style:disc outside;margin-left:2em;margin-top:1em}.content ul ul{list-style-type:circle;margin-top:0.5em}.content ul ul ul{list-style-type:square}.content dd{margin-left:2em}.content figure{margin-left:2em;margin-right:2em;text-align:center}.content figure:not(:first-child){margin-top:2em}.content figure:not(:last-child){margin-bottom:2em}.content figure img{display:inline-block}.content figure figcaption{font-style:italic}.content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}.content sup,.content sub{font-size:75%}.content table{width:100%}.content table td,.content table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.content table th{color:#222}.content table th:not([align]){text-align:inherit}.content table thead td,.content table thead th{border-width:0 0 2px;color:#222}.content table tfoot td,.content table tfoot th{border-width:2px 0 0;color:#222}.content table tbody tr:last-child td,.content table tbody tr:last-child th{border-bottom-width:0}.content .tabs li+li{margin-top:0}.content.is-small,#documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}.content.is-normal{font-size:1rem}.content.is-medium{font-size:1.25rem}.content.is-large{font-size:1.5rem}.icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}.icon.is-small,#documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}.icon.is-medium{height:2rem;width:2rem}.icon.is-large{height:3rem;width:3rem}.icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}.icon-text .icon{flex-grow:0;flex-shrink:0}.icon-text .icon:not(:last-child){margin-right:.25em}.icon-text .icon:not(:first-child){margin-left:.25em}div.icon-text{display:flex}.image,#documenter .docs-sidebar .docs-logo>img{display:block;position:relative}.image img,#documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}.image img.is-rounded,#documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}.image.is-fullwidth,#documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}.image.is-square,#documenter .docs-sidebar .docs-logo>img.is-square,.image.is-1by1,#documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}.image.is-5by4,#documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}.image.is-4by3,#documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}.image.is-3by2,#documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}.image.is-5by3,#documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}.image.is-16by9,#documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}.image.is-2by1,#documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}.image.is-3by1,#documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}.image.is-4by5,#documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}.image.is-3by4,#documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}.image.is-2by3,#documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}.image.is-3by5,#documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}.image.is-9by16,#documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}.image.is-1by2,#documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}.image.is-1by3,#documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}.image.is-16x16,#documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}.image.is-24x24,#documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}.image.is-32x32,#documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}.image.is-48x48,#documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}.image.is-64x64,#documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}.image.is-96x96,#documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}.image.is-128x128,#documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}.notification{background-color:#f5f5f5;border-radius:4px;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}.notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}.notification strong{color:currentColor}.notification code,.notification pre{background:#fff}.notification pre code{background:transparent}.notification>.delete{right:.5rem;position:absolute;top:0.5rem}.notification .title,.notification .subtitle,.notification .content{color:currentColor}.notification.is-white{background-color:#fff;color:#0a0a0a}.notification.is-black{background-color:#0a0a0a;color:#fff}.notification.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.notification.is-dark,.content kbd.notification{background-color:#363636;color:#fff}.notification.is-primary,.docstring>section>a.notification.docs-sourcelink{background-color:#4eb5de;color:#fff}.notification.is-primary.is-light,.docstring>section>a.notification.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.notification.is-link{background-color:#2e63b8;color:#fff}.notification.is-link.is-light{background-color:#eff3fb;color:#3169c4}.notification.is-info{background-color:#209cee;color:#fff}.notification.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.notification.is-success{background-color:#22c35b;color:#fff}.notification.is-success.is-light{background-color:#eefcf3;color:#198f43}.notification.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.notification.is-warning.is-light{background-color:#fffbeb;color:#947600}.notification.is-danger{background-color:#da0b00;color:#fff}.notification.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}.progress::-webkit-progress-bar{background-color:#ededed}.progress::-webkit-progress-value{background-color:#222}.progress::-moz-progress-bar{background-color:#222}.progress::-ms-fill{background-color:#222;border:none}.progress.is-white::-webkit-progress-value{background-color:#fff}.progress.is-white::-moz-progress-bar{background-color:#fff}.progress.is-white::-ms-fill{background-color:#fff}.progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #ededed 30%)}.progress.is-black::-webkit-progress-value{background-color:#0a0a0a}.progress.is-black::-moz-progress-bar{background-color:#0a0a0a}.progress.is-black::-ms-fill{background-color:#0a0a0a}.progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #ededed 30%)}.progress.is-light::-webkit-progress-value{background-color:#f5f5f5}.progress.is-light::-moz-progress-bar{background-color:#f5f5f5}.progress.is-light::-ms-fill{background-color:#f5f5f5}.progress.is-light:indeterminate{background-image:linear-gradient(to right, #f5f5f5 30%, #ededed 30%)}.progress.is-dark::-webkit-progress-value,.content kbd.progress::-webkit-progress-value{background-color:#363636}.progress.is-dark::-moz-progress-bar,.content kbd.progress::-moz-progress-bar{background-color:#363636}.progress.is-dark::-ms-fill,.content kbd.progress::-ms-fill{background-color:#363636}.progress.is-dark:indeterminate,.content kbd.progress:indeterminate{background-image:linear-gradient(to right, #363636 30%, #ededed 30%)}.progress.is-primary::-webkit-progress-value,.docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#4eb5de}.progress.is-primary::-moz-progress-bar,.docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#4eb5de}.progress.is-primary::-ms-fill,.docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#4eb5de}.progress.is-primary:indeterminate,.docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #4eb5de 30%, #ededed 30%)}.progress.is-link::-webkit-progress-value{background-color:#2e63b8}.progress.is-link::-moz-progress-bar{background-color:#2e63b8}.progress.is-link::-ms-fill{background-color:#2e63b8}.progress.is-link:indeterminate{background-image:linear-gradient(to right, #2e63b8 30%, #ededed 30%)}.progress.is-info::-webkit-progress-value{background-color:#209cee}.progress.is-info::-moz-progress-bar{background-color:#209cee}.progress.is-info::-ms-fill{background-color:#209cee}.progress.is-info:indeterminate{background-image:linear-gradient(to right, #209cee 30%, #ededed 30%)}.progress.is-success::-webkit-progress-value{background-color:#22c35b}.progress.is-success::-moz-progress-bar{background-color:#22c35b}.progress.is-success::-ms-fill{background-color:#22c35b}.progress.is-success:indeterminate{background-image:linear-gradient(to right, #22c35b 30%, #ededed 30%)}.progress.is-warning::-webkit-progress-value{background-color:#ffdd57}.progress.is-warning::-moz-progress-bar{background-color:#ffdd57}.progress.is-warning::-ms-fill{background-color:#ffdd57}.progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ffdd57 30%, #ededed 30%)}.progress.is-danger::-webkit-progress-value{background-color:#da0b00}.progress.is-danger::-moz-progress-bar{background-color:#da0b00}.progress.is-danger::-ms-fill{background-color:#da0b00}.progress.is-danger:indeterminate{background-image:linear-gradient(to right, #da0b00 30%, #ededed 30%)}.progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#ededed;background-image:linear-gradient(to right, #222 30%, #ededed 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}.progress:indeterminate::-webkit-progress-bar{background-color:transparent}.progress:indeterminate::-moz-progress-bar{background-color:transparent}.progress:indeterminate::-ms-fill{animation-name:none}.progress.is-small,#documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}.progress.is-medium{height:1.25rem}.progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}.table{background-color:#fff;color:#222}.table td,.table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.table td.is-white,.table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}.table td.is-black,.table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.table td.is-light,.table th.is-light{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.table td.is-dark,.table th.is-dark{background-color:#363636;border-color:#363636;color:#fff}.table td.is-primary,.table th.is-primary{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.table td.is-link,.table th.is-link{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.table td.is-info,.table th.is-info{background-color:#209cee;border-color:#209cee;color:#fff}.table td.is-success,.table th.is-success{background-color:#22c35b;border-color:#22c35b;color:#fff}.table td.is-warning,.table th.is-warning{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.table td.is-danger,.table th.is-danger{background-color:#da0b00;border-color:#da0b00;color:#fff}.table td.is-narrow,.table th.is-narrow{white-space:nowrap;width:1%}.table td.is-selected,.table th.is-selected{background-color:#4eb5de;color:#fff}.table td.is-selected a,.table td.is-selected strong,.table th.is-selected a,.table th.is-selected strong{color:currentColor}.table td.is-vcentered,.table th.is-vcentered{vertical-align:middle}.table th{color:#222}.table th:not([align]){text-align:left}.table tr.is-selected{background-color:#4eb5de;color:#fff}.table tr.is-selected a,.table tr.is-selected strong{color:currentColor}.table tr.is-selected td,.table tr.is-selected th{border-color:#fff;color:currentColor}.table thead{background-color:rgba(0,0,0,0)}.table thead td,.table thead th{border-width:0 0 2px;color:#222}.table tfoot{background-color:rgba(0,0,0,0)}.table tfoot td,.table tfoot th{border-width:2px 0 0;color:#222}.table tbody{background-color:rgba(0,0,0,0)}.table tbody tr:last-child td,.table tbody tr:last-child th{border-bottom-width:0}.table.is-bordered td,.table.is-bordered th{border-width:1px}.table.is-bordered tr:last-child td,.table.is-bordered tr:last-child th{border-bottom-width:1px}.table.is-fullwidth{width:100%}.table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#f5f5f5}.table.is-narrow td,.table.is-narrow th{padding:0.25em 0.5em}.table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#fafafa}.table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}.tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.tags .tag,.tags .content kbd,.content .tags kbd,.tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}.tags .tag:not(:last-child),.tags .content kbd:not(:last-child),.content .tags kbd:not(:last-child),.tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}.tags:last-child{margin-bottom:-0.5rem}.tags:not(:last-child){margin-bottom:1rem}.tags.are-medium .tag:not(.is-normal):not(.is-large),.tags.are-medium .content kbd:not(.is-normal):not(.is-large),.content .tags.are-medium kbd:not(.is-normal):not(.is-large),.tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}.tags.are-large .tag:not(.is-normal):not(.is-medium),.tags.are-large .content kbd:not(.is-normal):not(.is-medium),.content .tags.are-large kbd:not(.is-normal):not(.is-medium),.tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}.tags.is-centered{justify-content:center}.tags.is-centered .tag,.tags.is-centered .content kbd,.content .tags.is-centered kbd,.tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}.tags.is-right{justify-content:flex-end}.tags.is-right .tag:not(:first-child),.tags.is-right .content kbd:not(:first-child),.content .tags.is-right kbd:not(:first-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}.tags.is-right .tag:not(:last-child),.tags.is-right .content kbd:not(:last-child),.content .tags.is-right kbd:not(:last-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}.tags.has-addons .tag,.tags.has-addons .content kbd,.content .tags.has-addons kbd,.tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}.tags.has-addons .tag:not(:first-child),.tags.has-addons .content kbd:not(:first-child),.content .tags.has-addons kbd:not(:first-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}.tags.has-addons .tag:not(:last-child),.tags.has-addons .content kbd:not(:last-child),.content .tags.has-addons kbd:not(:last-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.tag:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#f5f5f5;border-radius:4px;color:#222;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}.tag:not(body) .delete,.content kbd:not(body) .delete,.docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}.tag.is-white:not(body),.content kbd.is-white:not(body),.docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}.tag.is-black:not(body),.content kbd.is-black:not(body),.docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}.tag.is-light:not(body),.content kbd.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.tag.is-dark:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink.is-dark:not(body),.content .docstring>section>kbd:not(body){background-color:#363636;color:#fff}.tag.is-primary:not(body),.content kbd.is-primary:not(body),.docstring>section>a.docs-sourcelink:not(body){background-color:#4eb5de;color:#fff}.tag.is-primary.is-light:not(body),.content kbd.is-primary.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#eef8fc;color:#1a6d8e}.tag.is-link:not(body),.content kbd.is-link:not(body),.docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#2e63b8;color:#fff}.tag.is-link.is-light:not(body),.content kbd.is-link.is-light:not(body),.docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#eff3fb;color:#3169c4}.tag.is-info:not(body),.content kbd.is-info:not(body),.docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#209cee;color:#fff}.tag.is-info.is-light:not(body),.content kbd.is-info.is-light:not(body),.docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ecf7fe;color:#0e72b4}.tag.is-success:not(body),.content kbd.is-success:not(body),.docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#22c35b;color:#fff}.tag.is-success.is-light:not(body),.content kbd.is-success.is-light:not(body),.docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#eefcf3;color:#198f43}.tag.is-warning:not(body),.content kbd.is-warning:not(body),.docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ffdd57;color:rgba(0,0,0,0.7)}.tag.is-warning.is-light:not(body),.content kbd.is-warning.is-light:not(body),.docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffbeb;color:#947600}.tag.is-danger:not(body),.content kbd.is-danger:not(body),.docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#da0b00;color:#fff}.tag.is-danger.is-light:not(body),.content kbd.is-danger.is-light:not(body),.docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#ffeceb;color:#f50c00}.tag.is-normal:not(body),.content kbd.is-normal:not(body),.docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}.tag.is-medium:not(body),.content kbd.is-medium:not(body),.docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}.tag.is-large:not(body),.content kbd.is-large:not(body),.docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}.tag:not(body) .icon:first-child:not(:last-child),.content kbd:not(body) .icon:first-child:not(:last-child),.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}.tag:not(body) .icon:last-child:not(:first-child),.content kbd:not(body) .icon:last-child:not(:first-child),.docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}.tag:not(body) .icon:first-child:last-child,.content kbd:not(body) .icon:first-child:last-child,.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}.tag.is-delete:not(body),.content kbd.is-delete:not(body),.docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before,.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}.tag.is-delete:not(body):hover,.content kbd.is-delete:not(body):hover,.docstring>section>a.docs-sourcelink.is-delete:not(body):hover,.tag.is-delete:not(body):focus,.content kbd.is-delete:not(body):focus,.docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#e8e8e8}.tag.is-delete:not(body):active,.content kbd.is-delete:not(body):active,.docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#dbdbdb}.tag.is-rounded:not(body),#documenter .docs-sidebar form.docs-search>input:not(body),.content kbd.is-rounded:not(body),#documenter .docs-sidebar .content form.docs-search>input:not(body),.docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}a.tag:hover,.docstring>section>a.docs-sourcelink:hover{text-decoration:underline}.title,.subtitle{word-break:break-word}.title em,.title span,.subtitle em,.subtitle span{font-weight:inherit}.title sub,.subtitle sub{font-size:.75em}.title sup,.subtitle sup{font-size:.75em}.title .tag,.title .content kbd,.content .title kbd,.title .docstring>section>a.docs-sourcelink,.subtitle .tag,.subtitle .content kbd,.content .subtitle kbd,.subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}.title{color:#222;font-size:2rem;font-weight:600;line-height:1.125}.title strong{color:inherit;font-weight:inherit}.title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}.title.is-1{font-size:3rem}.title.is-2{font-size:2.5rem}.title.is-3{font-size:2rem}.title.is-4{font-size:1.5rem}.title.is-5{font-size:1.25rem}.title.is-6{font-size:1rem}.title.is-7{font-size:.75rem}.subtitle{color:#222;font-size:1.25rem;font-weight:400;line-height:1.25}.subtitle strong{color:#222;font-weight:600}.subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}.subtitle.is-1{font-size:3rem}.subtitle.is-2{font-size:2.5rem}.subtitle.is-3{font-size:2rem}.subtitle.is-4{font-size:1.5rem}.subtitle.is-5{font-size:1.25rem}.subtitle.is-6{font-size:1rem}.subtitle.is-7{font-size:.75rem}.heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}.number{align-items:center;background-color:#f5f5f5;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input{background-color:#fff;border-color:#dbdbdb;border-radius:4px;color:#222}.select select::-moz-placeholder,.textarea::-moz-placeholder,.input::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#707070}.select select::-webkit-input-placeholder,.textarea::-webkit-input-placeholder,.input::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#707070}.select select:-moz-placeholder,.textarea:-moz-placeholder,.input:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#707070}.select select:-ms-input-placeholder,.textarea:-ms-input-placeholder,.input:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#707070}.select select:hover,.textarea:hover,.input:hover,#documenter .docs-sidebar form.docs-search>input:hover,.select select.is-hovered,.is-hovered.textarea,.is-hovered.input,#documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#b5b5b5}.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{border-color:#2e63b8;box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none;color:#6b6b6b}.select select[disabled]::-moz-placeholder,.textarea[disabled]::-moz-placeholder,.input[disabled]::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] .select select::-moz-placeholder,.select fieldset[disabled] select::-moz-placeholder,fieldset[disabled] .textarea::-moz-placeholder,fieldset[disabled] .input::-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]::-webkit-input-placeholder,.textarea[disabled]::-webkit-input-placeholder,.input[disabled]::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] .select select::-webkit-input-placeholder,.select fieldset[disabled] select::-webkit-input-placeholder,fieldset[disabled] .textarea::-webkit-input-placeholder,fieldset[disabled] .input::-webkit-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-webkit-input-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-moz-placeholder,.textarea[disabled]:-moz-placeholder,.input[disabled]:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] .select select:-moz-placeholder,.select fieldset[disabled] select:-moz-placeholder,fieldset[disabled] .textarea:-moz-placeholder,fieldset[disabled] .input:-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-ms-input-placeholder,.textarea[disabled]:-ms-input-placeholder,.input[disabled]:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] .select select:-ms-input-placeholder,.select fieldset[disabled] select:-ms-input-placeholder,fieldset[disabled] .textarea:-ms-input-placeholder,fieldset[disabled] .input:-ms-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-ms-input-placeholder{color:rgba(107,107,107,0.3)}.textarea,.input,#documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}.textarea[readonly],.input[readonly],#documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}.is-white.textarea,.is-white.input,#documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}.is-white.textarea:focus,.is-white.input:focus,#documenter .docs-sidebar form.docs-search>input.is-white:focus,.is-white.is-focused.textarea,.is-white.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-white.textarea:active,.is-white.input:active,#documenter .docs-sidebar form.docs-search>input.is-white:active,.is-white.is-active.textarea,.is-white.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.is-black.textarea,.is-black.input,#documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}.is-black.textarea:focus,.is-black.input:focus,#documenter .docs-sidebar form.docs-search>input.is-black:focus,.is-black.is-focused.textarea,.is-black.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-black.textarea:active,.is-black.input:active,#documenter .docs-sidebar form.docs-search>input.is-black:active,.is-black.is-active.textarea,.is-black.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.is-light.textarea,.is-light.input,#documenter .docs-sidebar form.docs-search>input.is-light{border-color:#f5f5f5}.is-light.textarea:focus,.is-light.input:focus,#documenter .docs-sidebar form.docs-search>input.is-light:focus,.is-light.is-focused.textarea,.is-light.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-light.textarea:active,.is-light.input:active,#documenter .docs-sidebar form.docs-search>input.is-light:active,.is-light.is-active.textarea,.is-light.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.is-dark.textarea,.content kbd.textarea,.is-dark.input,#documenter .docs-sidebar form.docs-search>input.is-dark,.content kbd.input{border-color:#363636}.is-dark.textarea:focus,.content kbd.textarea:focus,.is-dark.input:focus,#documenter .docs-sidebar form.docs-search>input.is-dark:focus,.content kbd.input:focus,.is-dark.is-focused.textarea,.content kbd.is-focused.textarea,.is-dark.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.content kbd.is-focused.input,#documenter .docs-sidebar .content form.docs-search>input.is-focused,.is-dark.textarea:active,.content kbd.textarea:active,.is-dark.input:active,#documenter .docs-sidebar form.docs-search>input.is-dark:active,.content kbd.input:active,.is-dark.is-active.textarea,.content kbd.is-active.textarea,.is-dark.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.content kbd.is-active.input,#documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.is-primary.textarea,.docstring>section>a.textarea.docs-sourcelink,.is-primary.input,#documenter .docs-sidebar form.docs-search>input.is-primary,.docstring>section>a.input.docs-sourcelink{border-color:#4eb5de}.is-primary.textarea:focus,.docstring>section>a.textarea.docs-sourcelink:focus,.is-primary.input:focus,#documenter .docs-sidebar form.docs-search>input.is-primary:focus,.docstring>section>a.input.docs-sourcelink:focus,.is-primary.is-focused.textarea,.docstring>section>a.is-focused.textarea.docs-sourcelink,.is-primary.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.docstring>section>a.is-focused.input.docs-sourcelink,.is-primary.textarea:active,.docstring>section>a.textarea.docs-sourcelink:active,.is-primary.input:active,#documenter .docs-sidebar form.docs-search>input.is-primary:active,.docstring>section>a.input.docs-sourcelink:active,.is-primary.is-active.textarea,.docstring>section>a.is-active.textarea.docs-sourcelink,.is-primary.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.is-link.textarea,.is-link.input,#documenter .docs-sidebar form.docs-search>input.is-link{border-color:#2e63b8}.is-link.textarea:focus,.is-link.input:focus,#documenter .docs-sidebar form.docs-search>input.is-link:focus,.is-link.is-focused.textarea,.is-link.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-link.textarea:active,.is-link.input:active,#documenter .docs-sidebar form.docs-search>input.is-link:active,.is-link.is-active.textarea,.is-link.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.is-info.textarea,.is-info.input,#documenter .docs-sidebar form.docs-search>input.is-info{border-color:#209cee}.is-info.textarea:focus,.is-info.input:focus,#documenter .docs-sidebar form.docs-search>input.is-info:focus,.is-info.is-focused.textarea,.is-info.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-info.textarea:active,.is-info.input:active,#documenter .docs-sidebar form.docs-search>input.is-info:active,.is-info.is-active.textarea,.is-info.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.is-success.textarea,.is-success.input,#documenter .docs-sidebar form.docs-search>input.is-success{border-color:#22c35b}.is-success.textarea:focus,.is-success.input:focus,#documenter .docs-sidebar form.docs-search>input.is-success:focus,.is-success.is-focused.textarea,.is-success.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-success.textarea:active,.is-success.input:active,#documenter .docs-sidebar form.docs-search>input.is-success:active,.is-success.is-active.textarea,.is-success.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.is-warning.textarea,.is-warning.input,#documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ffdd57}.is-warning.textarea:focus,.is-warning.input:focus,#documenter .docs-sidebar form.docs-search>input.is-warning:focus,.is-warning.is-focused.textarea,.is-warning.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-warning.textarea:active,.is-warning.input:active,#documenter .docs-sidebar form.docs-search>input.is-warning:active,.is-warning.is-active.textarea,.is-warning.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.is-danger.textarea,.is-danger.input,#documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#da0b00}.is-danger.textarea:focus,.is-danger.input:focus,#documenter .docs-sidebar form.docs-search>input.is-danger:focus,.is-danger.is-focused.textarea,.is-danger.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-danger.textarea:active,.is-danger.input:active,#documenter .docs-sidebar form.docs-search>input.is-danger:active,.is-danger.is-active.textarea,.is-danger.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.is-small.textarea,.is-small.input,#documenter .docs-sidebar form.docs-search>input{border-radius:2px;font-size:.75rem}.is-medium.textarea,.is-medium.input,#documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}.is-large.textarea,.is-large.input,#documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}.is-fullwidth.textarea,.is-fullwidth.input,#documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}.is-inline.textarea,.is-inline.input,#documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}.input.is-rounded,#documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}.input.is-static,#documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}.textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}.textarea:not([rows]){max-height:40em;min-height:8em}.textarea[rows]{height:initial}.textarea.has-fixed-size{resize:none}.radio,.checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}.radio input,.checkbox input{cursor:pointer}.radio:hover,.checkbox:hover{color:#222}.radio[disabled],.checkbox[disabled],fieldset[disabled] .radio,fieldset[disabled] .checkbox,.radio input[disabled],.checkbox input[disabled]{color:#6b6b6b;cursor:not-allowed}.radio+.radio{margin-left:.5em}.select{display:inline-block;max-width:100%;position:relative;vertical-align:top}.select:not(.is-multiple){height:2.5em}.select:not(.is-multiple):not(.is-loading)::after{border-color:#2e63b8;right:1.125em;z-index:4}.select.is-rounded select,#documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}.select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}.select select::-ms-expand{display:none}.select select[disabled]:hover,fieldset[disabled] .select select:hover{border-color:#f5f5f5}.select select:not([multiple]){padding-right:2.5em}.select select[multiple]{height:auto;padding:0}.select select[multiple] option{padding:0.5em 1em}.select:not(.is-multiple):not(.is-loading):hover::after{border-color:#222}.select.is-white:not(:hover)::after{border-color:#fff}.select.is-white select{border-color:#fff}.select.is-white select:hover,.select.is-white select.is-hovered{border-color:#f2f2f2}.select.is-white select:focus,.select.is-white select.is-focused,.select.is-white select:active,.select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.select.is-black:not(:hover)::after{border-color:#0a0a0a}.select.is-black select{border-color:#0a0a0a}.select.is-black select:hover,.select.is-black select.is-hovered{border-color:#000}.select.is-black select:focus,.select.is-black select.is-focused,.select.is-black select:active,.select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.select.is-light:not(:hover)::after{border-color:#f5f5f5}.select.is-light select{border-color:#f5f5f5}.select.is-light select:hover,.select.is-light select.is-hovered{border-color:#e8e8e8}.select.is-light select:focus,.select.is-light select.is-focused,.select.is-light select:active,.select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.select.is-dark:not(:hover)::after,.content kbd.select:not(:hover)::after{border-color:#363636}.select.is-dark select,.content kbd.select select{border-color:#363636}.select.is-dark select:hover,.content kbd.select select:hover,.select.is-dark select.is-hovered,.content kbd.select select.is-hovered{border-color:#292929}.select.is-dark select:focus,.content kbd.select select:focus,.select.is-dark select.is-focused,.content kbd.select select.is-focused,.select.is-dark select:active,.content kbd.select select:active,.select.is-dark select.is-active,.content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.select.is-primary:not(:hover)::after,.docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#4eb5de}.select.is-primary select,.docstring>section>a.select.docs-sourcelink select{border-color:#4eb5de}.select.is-primary select:hover,.docstring>section>a.select.docs-sourcelink select:hover,.select.is-primary select.is-hovered,.docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#39acda}.select.is-primary select:focus,.docstring>section>a.select.docs-sourcelink select:focus,.select.is-primary select.is-focused,.docstring>section>a.select.docs-sourcelink select.is-focused,.select.is-primary select:active,.docstring>section>a.select.docs-sourcelink select:active,.select.is-primary select.is-active,.docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.select.is-link:not(:hover)::after{border-color:#2e63b8}.select.is-link select{border-color:#2e63b8}.select.is-link select:hover,.select.is-link select.is-hovered{border-color:#2958a4}.select.is-link select:focus,.select.is-link select.is-focused,.select.is-link select:active,.select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select.is-info:not(:hover)::after{border-color:#209cee}.select.is-info select{border-color:#209cee}.select.is-info select:hover,.select.is-info select.is-hovered{border-color:#1190e3}.select.is-info select:focus,.select.is-info select.is-focused,.select.is-info select:active,.select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.select.is-success:not(:hover)::after{border-color:#22c35b}.select.is-success select{border-color:#22c35b}.select.is-success select:hover,.select.is-success select.is-hovered{border-color:#1ead51}.select.is-success select:focus,.select.is-success select.is-focused,.select.is-success select:active,.select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.select.is-warning:not(:hover)::after{border-color:#ffdd57}.select.is-warning select{border-color:#ffdd57}.select.is-warning select:hover,.select.is-warning select.is-hovered{border-color:#ffd83e}.select.is-warning select:focus,.select.is-warning select.is-focused,.select.is-warning select:active,.select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.select.is-danger:not(:hover)::after{border-color:#da0b00}.select.is-danger select{border-color:#da0b00}.select.is-danger select:hover,.select.is-danger select.is-hovered{border-color:#c10a00}.select.is-danger select:focus,.select.is-danger select.is-focused,.select.is-danger select:active,.select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.select.is-small,#documenter .docs-sidebar form.docs-search>input.select{border-radius:2px;font-size:.75rem}.select.is-medium{font-size:1.25rem}.select.is-large{font-size:1.5rem}.select.is-disabled::after{border-color:#6b6b6b !important;opacity:0.5}.select.is-fullwidth{width:100%}.select.is-fullwidth select{width:100%}.select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}.select.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.select.is-loading.is-medium:after{font-size:1.25rem}.select.is-loading.is-large:after{font-size:1.5rem}.file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}.file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}.file.is-white:hover .file-cta,.file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.file.is-white:focus .file-cta,.file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}.file.is-white:active .file-cta,.file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}.file.is-black:hover .file-cta,.file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}.file.is-black:focus .file-cta,.file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}.file.is-black:active .file-cta,.file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}.file.is-light .file-cta{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:hover .file-cta,.file.is-light.is-hovered .file-cta{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:focus .file-cta,.file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(245,245,245,0.25);color:rgba(0,0,0,0.7)}.file.is-light:active .file-cta,.file.is-light.is-active .file-cta{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-dark .file-cta,.content kbd.file .file-cta{background-color:#363636;border-color:transparent;color:#fff}.file.is-dark:hover .file-cta,.content kbd.file:hover .file-cta,.file.is-dark.is-hovered .file-cta,.content kbd.file.is-hovered .file-cta{background-color:#2f2f2f;border-color:transparent;color:#fff}.file.is-dark:focus .file-cta,.content kbd.file:focus .file-cta,.file.is-dark.is-focused .file-cta,.content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(54,54,54,0.25);color:#fff}.file.is-dark:active .file-cta,.content kbd.file:active .file-cta,.file.is-dark.is-active .file-cta,.content kbd.file.is-active .file-cta{background-color:#292929;border-color:transparent;color:#fff}.file.is-primary .file-cta,.docstring>section>a.file.docs-sourcelink .file-cta{background-color:#4eb5de;border-color:transparent;color:#fff}.file.is-primary:hover .file-cta,.docstring>section>a.file.docs-sourcelink:hover .file-cta,.file.is-primary.is-hovered .file-cta,.docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#43b1dc;border-color:transparent;color:#fff}.file.is-primary:focus .file-cta,.docstring>section>a.file.docs-sourcelink:focus .file-cta,.file.is-primary.is-focused .file-cta,.docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(78,181,222,0.25);color:#fff}.file.is-primary:active .file-cta,.docstring>section>a.file.docs-sourcelink:active .file-cta,.file.is-primary.is-active .file-cta,.docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#39acda;border-color:transparent;color:#fff}.file.is-link .file-cta{background-color:#2e63b8;border-color:transparent;color:#fff}.file.is-link:hover .file-cta,.file.is-link.is-hovered .file-cta{background-color:#2b5eae;border-color:transparent;color:#fff}.file.is-link:focus .file-cta,.file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(46,99,184,0.25);color:#fff}.file.is-link:active .file-cta,.file.is-link.is-active .file-cta{background-color:#2958a4;border-color:transparent;color:#fff}.file.is-info .file-cta{background-color:#209cee;border-color:transparent;color:#fff}.file.is-info:hover .file-cta,.file.is-info.is-hovered .file-cta{background-color:#1497ed;border-color:transparent;color:#fff}.file.is-info:focus .file-cta,.file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(32,156,238,0.25);color:#fff}.file.is-info:active .file-cta,.file.is-info.is-active .file-cta{background-color:#1190e3;border-color:transparent;color:#fff}.file.is-success .file-cta{background-color:#22c35b;border-color:transparent;color:#fff}.file.is-success:hover .file-cta,.file.is-success.is-hovered .file-cta{background-color:#20b856;border-color:transparent;color:#fff}.file.is-success:focus .file-cta,.file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(34,195,91,0.25);color:#fff}.file.is-success:active .file-cta,.file.is-success.is-active .file-cta{background-color:#1ead51;border-color:transparent;color:#fff}.file.is-warning .file-cta{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:hover .file-cta,.file.is-warning.is-hovered .file-cta{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:focus .file-cta,.file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,221,87,0.25);color:rgba(0,0,0,0.7)}.file.is-warning:active .file-cta,.file.is-warning.is-active .file-cta{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-danger .file-cta{background-color:#da0b00;border-color:transparent;color:#fff}.file.is-danger:hover .file-cta,.file.is-danger.is-hovered .file-cta{background-color:#cd0a00;border-color:transparent;color:#fff}.file.is-danger:focus .file-cta,.file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(218,11,0,0.25);color:#fff}.file.is-danger:active .file-cta,.file.is-danger.is-active .file-cta{background-color:#c10a00;border-color:transparent;color:#fff}.file.is-small,#documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}.file.is-normal{font-size:1rem}.file.is-medium{font-size:1.25rem}.file.is-medium .file-icon .fa{font-size:21px}.file.is-large{font-size:1.5rem}.file.is-large .file-icon .fa{font-size:28px}.file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}.file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}.file.has-name.is-empty .file-cta{border-radius:4px}.file.has-name.is-empty .file-name{display:none}.file.is-boxed .file-label{flex-direction:column}.file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}.file.is-boxed .file-name{border-width:0 1px 1px}.file.is-boxed .file-icon{height:1.5em;width:1.5em}.file.is-boxed .file-icon .fa{font-size:21px}.file.is-boxed.is-small .file-icon .fa,#documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}.file.is-boxed.is-medium .file-icon .fa{font-size:28px}.file.is-boxed.is-large .file-icon .fa{font-size:35px}.file.is-boxed.has-name .file-cta{border-radius:4px 4px 0 0}.file.is-boxed.has-name .file-name{border-radius:0 0 4px 4px;border-width:0 1px 1px}.file.is-centered{justify-content:center}.file.is-fullwidth .file-label{width:100%}.file.is-fullwidth .file-name{flex-grow:1;max-width:none}.file.is-right{justify-content:flex-end}.file.is-right .file-cta{border-radius:0 4px 4px 0}.file.is-right .file-name{border-radius:4px 0 0 4px;border-width:1px 0 1px 1px;order:-1}.file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}.file-label:hover .file-cta{background-color:#eee;color:#222}.file-label:hover .file-name{border-color:#d5d5d5}.file-label:active .file-cta{background-color:#e8e8e8;color:#222}.file-label:active .file-name{border-color:#cfcfcf}.file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}.file-cta,.file-name{border-color:#dbdbdb;border-radius:4px;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}.file-cta{background-color:#f5f5f5;color:#222}.file-name{border-color:#dbdbdb;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}.file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}.file-icon .fa{font-size:14px}.label{color:#222;display:block;font-size:1rem;font-weight:700}.label:not(:last-child){margin-bottom:0.5em}.label.is-small,#documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}.label.is-medium{font-size:1.25rem}.label.is-large{font-size:1.5rem}.help{display:block;font-size:.75rem;margin-top:0.25rem}.help.is-white{color:#fff}.help.is-black{color:#0a0a0a}.help.is-light{color:#f5f5f5}.help.is-dark,.content kbd.help{color:#363636}.help.is-primary,.docstring>section>a.help.docs-sourcelink{color:#4eb5de}.help.is-link{color:#2e63b8}.help.is-info{color:#209cee}.help.is-success{color:#22c35b}.help.is-warning{color:#ffdd57}.help.is-danger{color:#da0b00}.field:not(:last-child){margin-bottom:0.75rem}.field.has-addons{display:flex;justify-content:flex-start}.field.has-addons .control:not(:last-child){margin-right:-1px}.field.has-addons .control:not(:first-child):not(:last-child) .button,.field.has-addons .control:not(:first-child):not(:last-child) .input,.field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,.field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}.field.has-addons .control:first-child:not(:only-child) .button,.field.has-addons .control:first-child:not(:only-child) .input,.field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,.field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}.field.has-addons .control:last-child:not(:only-child) .button,.field.has-addons .control:last-child:not(:only-child) .input,.field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,.field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}.field.has-addons .control .button:not([disabled]):hover,.field.has-addons .control .button.is-hovered:not([disabled]),.field.has-addons .control .input:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,.field.has-addons .control .input.is-hovered:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),.field.has-addons .control .select select:not([disabled]):hover,.field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}.field.has-addons .control .button:not([disabled]):focus,.field.has-addons .control .button.is-focused:not([disabled]),.field.has-addons .control .button:not([disabled]):active,.field.has-addons .control .button.is-active:not([disabled]),.field.has-addons .control .input:not([disabled]):focus,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,.field.has-addons .control .input.is-focused:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),.field.has-addons .control .input:not([disabled]):active,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,.field.has-addons .control .input.is-active:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),.field.has-addons .control .select select:not([disabled]):focus,.field.has-addons .control .select select.is-focused:not([disabled]),.field.has-addons .control .select select:not([disabled]):active,.field.has-addons .control .select select.is-active:not([disabled]){z-index:3}.field.has-addons .control .button:not([disabled]):focus:hover,.field.has-addons .control .button.is-focused:not([disabled]):hover,.field.has-addons .control .button:not([disabled]):active:hover,.field.has-addons .control .button.is-active:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):focus:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,.field.has-addons .control .input.is-focused:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):active:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,.field.has-addons .control .input.is-active:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):focus:hover,.field.has-addons .control .select select.is-focused:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):active:hover,.field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}.field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}.field.has-addons.has-addons-centered{justify-content:center}.field.has-addons.has-addons-right{justify-content:flex-end}.field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}.field.is-grouped{display:flex;justify-content:flex-start}.field.is-grouped>.control{flex-shrink:0}.field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}.field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}.field.is-grouped.is-grouped-centered{justify-content:center}.field.is-grouped.is-grouped-right{justify-content:flex-end}.field.is-grouped.is-grouped-multiline{flex-wrap:wrap}.field.is-grouped.is-grouped-multiline>.control:last-child,.field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}.field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}.field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{.field.is-horizontal{display:flex}}.field-label .label{font-size:inherit}@media screen and (max-width: 768px){.field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{.field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}.field-label.is-small,#documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}.field-label.is-normal{padding-top:0.375em}.field-label.is-medium{font-size:1.25rem;padding-top:0.375em}.field-label.is-large{font-size:1.5rem;padding-top:0.375em}}.field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{.field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}.field-body .field{margin-bottom:0}.field-body>.field{flex-shrink:1}.field-body>.field:not(.is-narrow){flex-grow:1}.field-body>.field:not(:last-child){margin-right:.75rem}}.control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}.control.has-icons-left .input:focus~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,.control.has-icons-left .select:focus~.icon,.control.has-icons-right .input:focus~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,.control.has-icons-right .select:focus~.icon{color:#222}.control.has-icons-left .input.is-small~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,.control.has-icons-left .select.is-small~.icon,.control.has-icons-right .input.is-small~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,.control.has-icons-right .select.is-small~.icon{font-size:.75rem}.control.has-icons-left .input.is-medium~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,.control.has-icons-left .select.is-medium~.icon,.control.has-icons-right .input.is-medium~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,.control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}.control.has-icons-left .input.is-large~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,.control.has-icons-left .select.is-large~.icon,.control.has-icons-right .input.is-large~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,.control.has-icons-right .select.is-large~.icon{font-size:1.5rem}.control.has-icons-left .icon,.control.has-icons-right .icon{color:#dbdbdb;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}.control.has-icons-left .input,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input,.control.has-icons-left .select select{padding-left:2.5em}.control.has-icons-left .icon.is-left{left:0}.control.has-icons-right .input,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input,.control.has-icons-right .select select{padding-right:2.5em}.control.has-icons-right .icon.is-right{right:0}.control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}.control.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.control.is-loading.is-medium:after{font-size:1.25rem}.control.is-loading.is-large:after{font-size:1.5rem}.breadcrumb{font-size:1rem;white-space:nowrap}.breadcrumb a{align-items:center;color:#2e63b8;display:flex;justify-content:center;padding:0 .75em}.breadcrumb a:hover{color:#363636}.breadcrumb li{align-items:center;display:flex}.breadcrumb li:first-child a{padding-left:0}.breadcrumb li.is-active a{color:#222;cursor:default;pointer-events:none}.breadcrumb li+li::before{color:#b5b5b5;content:"\0002f"}.breadcrumb ul,.breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}.breadcrumb .icon:first-child{margin-right:.5em}.breadcrumb .icon:last-child{margin-left:.5em}.breadcrumb.is-centered ol,.breadcrumb.is-centered ul{justify-content:center}.breadcrumb.is-right ol,.breadcrumb.is-right ul{justify-content:flex-end}.breadcrumb.is-small,#documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}.breadcrumb.is-medium{font-size:1.25rem}.breadcrumb.is-large{font-size:1.5rem}.breadcrumb.has-arrow-separator li+li::before{content:"\02192"}.breadcrumb.has-bullet-separator li+li::before{content:"\02022"}.breadcrumb.has-dot-separator li+li::before{content:"\000b7"}.breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}.card{background-color:#fff;border-radius:.25rem;box-shadow:#bbb;color:#222;max-width:100%;position:relative}.card-footer:first-child,.card-content:first-child,.card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-footer:last-child,.card-content:last-child,.card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}.card-header-title{align-items:center;color:#222;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}.card-header-title.is-centered{justify-content:center}.card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}.card-image{display:block;position:relative}.card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-content{background-color:rgba(0,0,0,0);padding:1.5rem}.card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}.card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}.card-footer-item:not(:last-child){border-right:1px solid #ededed}.card .media:not(:last-child){margin-bottom:1.5rem}.dropdown{display:inline-flex;position:relative;vertical-align:top}.dropdown.is-active .dropdown-menu,.dropdown.is-hoverable:hover .dropdown-menu{display:block}.dropdown.is-right .dropdown-menu{left:auto;right:0}.dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}.dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}.dropdown-content{background-color:#fff;border-radius:4px;box-shadow:#bbb;padding-bottom:.5rem;padding-top:.5rem}.dropdown-item{color:#222;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}a.dropdown-item,button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}a.dropdown-item:hover,button.dropdown-item:hover{background-color:#f5f5f5;color:#0a0a0a}a.dropdown-item.is-active,button.dropdown-item.is-active{background-color:#2e63b8;color:#fff}.dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}.level{align-items:center;justify-content:space-between}.level code{border-radius:4px}.level img{display:inline-block;vertical-align:top}.level.is-mobile{display:flex}.level.is-mobile .level-left,.level.is-mobile .level-right{display:flex}.level.is-mobile .level-left+.level-right{margin-top:0}.level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}.level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{.level{display:flex}.level>.level-item:not(.is-narrow){flex-grow:1}}.level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}.level-item .title,.level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){.level-item:not(:last-child){margin-bottom:.75rem}}.level-left,.level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.level-left .level-item.is-flexible,.level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{.level-left .level-item:not(:last-child),.level-right .level-item:not(:last-child){margin-right:.75rem}}.level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){.level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{.level-left{display:flex}}.level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{.level-right{display:flex}}.media{align-items:flex-start;display:flex;text-align:inherit}.media .content:not(:last-child){margin-bottom:.75rem}.media .media{border-top:1px solid rgba(219,219,219,0.5);display:flex;padding-top:.75rem}.media .media .content:not(:last-child),.media .media .control:not(:last-child){margin-bottom:.5rem}.media .media .media{padding-top:.5rem}.media .media .media+.media{margin-top:.5rem}.media+.media{border-top:1px solid rgba(219,219,219,0.5);margin-top:1rem;padding-top:1rem}.media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}.media-left,.media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.media-left{margin-right:1rem}.media-right{margin-left:1rem}.media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){.media-content{overflow-x:auto}}.menu{font-size:1rem}.menu.is-small,#documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}.menu.is-medium{font-size:1.25rem}.menu.is-large{font-size:1.5rem}.menu-list{line-height:1.25}.menu-list a{border-radius:2px;color:#222;display:block;padding:0.5em 0.75em}.menu-list a:hover{background-color:#f5f5f5;color:#222}.menu-list a.is-active{background-color:#2e63b8;color:#fff}.menu-list li ul{border-left:1px solid #dbdbdb;margin:.75em;padding-left:.75em}.menu-label{color:#6b6b6b;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}.menu-label:not(:first-child){margin-top:1em}.menu-label:not(:last-child){margin-bottom:1em}.message{background-color:#f5f5f5;border-radius:4px;font-size:1rem}.message strong{color:currentColor}.message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}.message.is-small,#documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}.message.is-medium{font-size:1.25rem}.message.is-large{font-size:1.5rem}.message.is-white{background-color:#fff}.message.is-white .message-header{background-color:#fff;color:#0a0a0a}.message.is-white .message-body{border-color:#fff}.message.is-black{background-color:#fafafa}.message.is-black .message-header{background-color:#0a0a0a;color:#fff}.message.is-black .message-body{border-color:#0a0a0a}.message.is-light{background-color:#fafafa}.message.is-light .message-header{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.message.is-light .message-body{border-color:#f5f5f5}.message.is-dark,.content kbd.message{background-color:#fafafa}.message.is-dark .message-header,.content kbd.message .message-header{background-color:#363636;color:#fff}.message.is-dark .message-body,.content kbd.message .message-body{border-color:#363636}.message.is-primary,.docstring>section>a.message.docs-sourcelink{background-color:#eef8fc}.message.is-primary .message-header,.docstring>section>a.message.docs-sourcelink .message-header{background-color:#4eb5de;color:#fff}.message.is-primary .message-body,.docstring>section>a.message.docs-sourcelink .message-body{border-color:#4eb5de;color:#1a6d8e}.message.is-link{background-color:#eff3fb}.message.is-link .message-header{background-color:#2e63b8;color:#fff}.message.is-link .message-body{border-color:#2e63b8;color:#3169c4}.message.is-info{background-color:#ecf7fe}.message.is-info .message-header{background-color:#209cee;color:#fff}.message.is-info .message-body{border-color:#209cee;color:#0e72b4}.message.is-success{background-color:#eefcf3}.message.is-success .message-header{background-color:#22c35b;color:#fff}.message.is-success .message-body{border-color:#22c35b;color:#198f43}.message.is-warning{background-color:#fffbeb}.message.is-warning .message-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.message.is-warning .message-body{border-color:#ffdd57;color:#947600}.message.is-danger{background-color:#ffeceb}.message.is-danger .message-header{background-color:#da0b00;color:#fff}.message.is-danger .message-body{border-color:#da0b00;color:#f50c00}.message-header{align-items:center;background-color:#222;border-radius:4px 4px 0 0;color:#fff;display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}.message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}.message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}.message-body{border-color:#dbdbdb;border-radius:4px;border-style:solid;border-width:0 0 0 4px;color:#222;padding:1.25em 1.5em}.message-body code,.message-body pre{background-color:#fff}.message-body pre code{background-color:rgba(0,0,0,0)}.modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}.modal.is-active{display:flex}.modal-background{background-color:rgba(10,10,10,0.86)}.modal-content,.modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){.modal-content,.modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}.modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}.modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}.modal-card-head,.modal-card-foot{align-items:center;background-color:#f5f5f5;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}.modal-card-head{border-bottom:1px solid #dbdbdb;border-top-left-radius:6px;border-top-right-radius:6px}.modal-card-title{color:#222;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}.modal-card-foot{border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:1px solid #dbdbdb}.modal-card-foot .button:not(:last-child){margin-right:.5em}.modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}.navbar{background-color:#fff;min-height:3.25rem;position:relative;z-index:30}.navbar.is-white{background-color:#fff;color:#0a0a0a}.navbar.is-white .navbar-brand>.navbar-item,.navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-brand>a.navbar-item:focus,.navbar.is-white .navbar-brand>a.navbar-item:hover,.navbar.is-white .navbar-brand>a.navbar-item.is-active,.navbar.is-white .navbar-brand .navbar-link:focus,.navbar.is-white .navbar-brand .navbar-link:hover,.navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){.navbar.is-white .navbar-start>.navbar-item,.navbar.is-white .navbar-start .navbar-link,.navbar.is-white .navbar-end>.navbar-item,.navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-start>a.navbar-item:focus,.navbar.is-white .navbar-start>a.navbar-item:hover,.navbar.is-white .navbar-start>a.navbar-item.is-active,.navbar.is-white .navbar-start .navbar-link:focus,.navbar.is-white .navbar-start .navbar-link:hover,.navbar.is-white .navbar-start .navbar-link.is-active,.navbar.is-white .navbar-end>a.navbar-item:focus,.navbar.is-white .navbar-end>a.navbar-item:hover,.navbar.is-white .navbar-end>a.navbar-item.is-active,.navbar.is-white .navbar-end .navbar-link:focus,.navbar.is-white .navbar-end .navbar-link:hover,.navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-start .navbar-link::after,.navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}.navbar.is-black{background-color:#0a0a0a;color:#fff}.navbar.is-black .navbar-brand>.navbar-item,.navbar.is-black .navbar-brand .navbar-link{color:#fff}.navbar.is-black .navbar-brand>a.navbar-item:focus,.navbar.is-black .navbar-brand>a.navbar-item:hover,.navbar.is-black .navbar-brand>a.navbar-item.is-active,.navbar.is-black .navbar-brand .navbar-link:focus,.navbar.is-black .navbar-brand .navbar-link:hover,.navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-black .navbar-start>.navbar-item,.navbar.is-black .navbar-start .navbar-link,.navbar.is-black .navbar-end>.navbar-item,.navbar.is-black .navbar-end .navbar-link{color:#fff}.navbar.is-black .navbar-start>a.navbar-item:focus,.navbar.is-black .navbar-start>a.navbar-item:hover,.navbar.is-black .navbar-start>a.navbar-item.is-active,.navbar.is-black .navbar-start .navbar-link:focus,.navbar.is-black .navbar-start .navbar-link:hover,.navbar.is-black .navbar-start .navbar-link.is-active,.navbar.is-black .navbar-end>a.navbar-item:focus,.navbar.is-black .navbar-end>a.navbar-item:hover,.navbar.is-black .navbar-end>a.navbar-item.is-active,.navbar.is-black .navbar-end .navbar-link:focus,.navbar.is-black .navbar-end .navbar-link:hover,.navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-start .navbar-link::after,.navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}.navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}.navbar.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>.navbar-item,.navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>a.navbar-item:focus,.navbar.is-light .navbar-brand>a.navbar-item:hover,.navbar.is-light .navbar-brand>a.navbar-item.is-active,.navbar.is-light .navbar-brand .navbar-link:focus,.navbar.is-light .navbar-brand .navbar-link:hover,.navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-light .navbar-start>.navbar-item,.navbar.is-light .navbar-start .navbar-link,.navbar.is-light .navbar-end>.navbar-item,.navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start>a.navbar-item:focus,.navbar.is-light .navbar-start>a.navbar-item:hover,.navbar.is-light .navbar-start>a.navbar-item.is-active,.navbar.is-light .navbar-start .navbar-link:focus,.navbar.is-light .navbar-start .navbar-link:hover,.navbar.is-light .navbar-start .navbar-link.is-active,.navbar.is-light .navbar-end>a.navbar-item:focus,.navbar.is-light .navbar-end>a.navbar-item:hover,.navbar.is-light .navbar-end>a.navbar-item.is-active,.navbar.is-light .navbar-end .navbar-link:focus,.navbar.is-light .navbar-end .navbar-link:hover,.navbar.is-light .navbar-end .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start .navbar-link::after,.navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}}.navbar.is-dark,.content kbd.navbar{background-color:#363636;color:#fff}.navbar.is-dark .navbar-brand>.navbar-item,.content kbd.navbar .navbar-brand>.navbar-item,.navbar.is-dark .navbar-brand .navbar-link,.content kbd.navbar .navbar-brand .navbar-link{color:#fff}.navbar.is-dark .navbar-brand>a.navbar-item:focus,.content kbd.navbar .navbar-brand>a.navbar-item:focus,.navbar.is-dark .navbar-brand>a.navbar-item:hover,.content kbd.navbar .navbar-brand>a.navbar-item:hover,.navbar.is-dark .navbar-brand>a.navbar-item.is-active,.content kbd.navbar .navbar-brand>a.navbar-item.is-active,.navbar.is-dark .navbar-brand .navbar-link:focus,.content kbd.navbar .navbar-brand .navbar-link:focus,.navbar.is-dark .navbar-brand .navbar-link:hover,.content kbd.navbar .navbar-brand .navbar-link:hover,.navbar.is-dark .navbar-brand .navbar-link.is-active,.content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-brand .navbar-link::after,.content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-burger,.content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-dark .navbar-start>.navbar-item,.content kbd.navbar .navbar-start>.navbar-item,.navbar.is-dark .navbar-start .navbar-link,.content kbd.navbar .navbar-start .navbar-link,.navbar.is-dark .navbar-end>.navbar-item,.content kbd.navbar .navbar-end>.navbar-item,.navbar.is-dark .navbar-end .navbar-link,.content kbd.navbar .navbar-end .navbar-link{color:#fff}.navbar.is-dark .navbar-start>a.navbar-item:focus,.content kbd.navbar .navbar-start>a.navbar-item:focus,.navbar.is-dark .navbar-start>a.navbar-item:hover,.content kbd.navbar .navbar-start>a.navbar-item:hover,.navbar.is-dark .navbar-start>a.navbar-item.is-active,.content kbd.navbar .navbar-start>a.navbar-item.is-active,.navbar.is-dark .navbar-start .navbar-link:focus,.content kbd.navbar .navbar-start .navbar-link:focus,.navbar.is-dark .navbar-start .navbar-link:hover,.content kbd.navbar .navbar-start .navbar-link:hover,.navbar.is-dark .navbar-start .navbar-link.is-active,.content kbd.navbar .navbar-start .navbar-link.is-active,.navbar.is-dark .navbar-end>a.navbar-item:focus,.content kbd.navbar .navbar-end>a.navbar-item:focus,.navbar.is-dark .navbar-end>a.navbar-item:hover,.content kbd.navbar .navbar-end>a.navbar-item:hover,.navbar.is-dark .navbar-end>a.navbar-item.is-active,.content kbd.navbar .navbar-end>a.navbar-item.is-active,.navbar.is-dark .navbar-end .navbar-link:focus,.content kbd.navbar .navbar-end .navbar-link:focus,.navbar.is-dark .navbar-end .navbar-link:hover,.content kbd.navbar .navbar-end .navbar-link:hover,.navbar.is-dark .navbar-end .navbar-link.is-active,.content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-start .navbar-link::after,.content kbd.navbar .navbar-start .navbar-link::after,.navbar.is-dark .navbar-end .navbar-link::after,.content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,.content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#292929;color:#fff}.navbar.is-dark .navbar-dropdown a.navbar-item.is-active,.content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#363636;color:#fff}}.navbar.is-primary,.docstring>section>a.navbar.docs-sourcelink{background-color:#4eb5de;color:#fff}.navbar.is-primary .navbar-brand>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,.navbar.is-primary .navbar-brand .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}.navbar.is-primary .navbar-brand>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,.navbar.is-primary .navbar-brand>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,.navbar.is-primary .navbar-brand>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,.navbar.is-primary .navbar-brand .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,.navbar.is-primary .navbar-brand .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,.navbar.is-primary .navbar-brand .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-brand .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-burger,.docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-primary .navbar-start>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,.navbar.is-primary .navbar-start .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,.navbar.is-primary .navbar-end>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,.navbar.is-primary .navbar-end .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}.navbar.is-primary .navbar-start>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,.navbar.is-primary .navbar-start>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,.navbar.is-primary .navbar-start>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,.navbar.is-primary .navbar-start .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,.navbar.is-primary .navbar-start .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,.navbar.is-primary .navbar-start .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,.navbar.is-primary .navbar-end>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,.navbar.is-primary .navbar-end>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,.navbar.is-primary .navbar-end>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,.navbar.is-primary .navbar-end .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,.navbar.is-primary .navbar-end .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,.navbar.is-primary .navbar-end .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-start .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,.navbar.is-primary .navbar-end .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-dropdown a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#4eb5de;color:#fff}}.navbar.is-link{background-color:#2e63b8;color:#fff}.navbar.is-link .navbar-brand>.navbar-item,.navbar.is-link .navbar-brand .navbar-link{color:#fff}.navbar.is-link .navbar-brand>a.navbar-item:focus,.navbar.is-link .navbar-brand>a.navbar-item:hover,.navbar.is-link .navbar-brand>a.navbar-item.is-active,.navbar.is-link .navbar-brand .navbar-link:focus,.navbar.is-link .navbar-brand .navbar-link:hover,.navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-link .navbar-start>.navbar-item,.navbar.is-link .navbar-start .navbar-link,.navbar.is-link .navbar-end>.navbar-item,.navbar.is-link .navbar-end .navbar-link{color:#fff}.navbar.is-link .navbar-start>a.navbar-item:focus,.navbar.is-link .navbar-start>a.navbar-item:hover,.navbar.is-link .navbar-start>a.navbar-item.is-active,.navbar.is-link .navbar-start .navbar-link:focus,.navbar.is-link .navbar-start .navbar-link:hover,.navbar.is-link .navbar-start .navbar-link.is-active,.navbar.is-link .navbar-end>a.navbar-item:focus,.navbar.is-link .navbar-end>a.navbar-item:hover,.navbar.is-link .navbar-end>a.navbar-item.is-active,.navbar.is-link .navbar-end .navbar-link:focus,.navbar.is-link .navbar-end .navbar-link:hover,.navbar.is-link .navbar-end .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-start .navbar-link::after,.navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#2e63b8;color:#fff}}.navbar.is-info{background-color:#209cee;color:#fff}.navbar.is-info .navbar-brand>.navbar-item,.navbar.is-info .navbar-brand .navbar-link{color:#fff}.navbar.is-info .navbar-brand>a.navbar-item:focus,.navbar.is-info .navbar-brand>a.navbar-item:hover,.navbar.is-info .navbar-brand>a.navbar-item.is-active,.navbar.is-info .navbar-brand .navbar-link:focus,.navbar.is-info .navbar-brand .navbar-link:hover,.navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-info .navbar-start>.navbar-item,.navbar.is-info .navbar-start .navbar-link,.navbar.is-info .navbar-end>.navbar-item,.navbar.is-info .navbar-end .navbar-link{color:#fff}.navbar.is-info .navbar-start>a.navbar-item:focus,.navbar.is-info .navbar-start>a.navbar-item:hover,.navbar.is-info .navbar-start>a.navbar-item.is-active,.navbar.is-info .navbar-start .navbar-link:focus,.navbar.is-info .navbar-start .navbar-link:hover,.navbar.is-info .navbar-start .navbar-link.is-active,.navbar.is-info .navbar-end>a.navbar-item:focus,.navbar.is-info .navbar-end>a.navbar-item:hover,.navbar.is-info .navbar-end>a.navbar-item.is-active,.navbar.is-info .navbar-end .navbar-link:focus,.navbar.is-info .navbar-end .navbar-link:hover,.navbar.is-info .navbar-end .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-start .navbar-link::after,.navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#209cee;color:#fff}}.navbar.is-success{background-color:#22c35b;color:#fff}.navbar.is-success .navbar-brand>.navbar-item,.navbar.is-success .navbar-brand .navbar-link{color:#fff}.navbar.is-success .navbar-brand>a.navbar-item:focus,.navbar.is-success .navbar-brand>a.navbar-item:hover,.navbar.is-success .navbar-brand>a.navbar-item.is-active,.navbar.is-success .navbar-brand .navbar-link:focus,.navbar.is-success .navbar-brand .navbar-link:hover,.navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-success .navbar-start>.navbar-item,.navbar.is-success .navbar-start .navbar-link,.navbar.is-success .navbar-end>.navbar-item,.navbar.is-success .navbar-end .navbar-link{color:#fff}.navbar.is-success .navbar-start>a.navbar-item:focus,.navbar.is-success .navbar-start>a.navbar-item:hover,.navbar.is-success .navbar-start>a.navbar-item.is-active,.navbar.is-success .navbar-start .navbar-link:focus,.navbar.is-success .navbar-start .navbar-link:hover,.navbar.is-success .navbar-start .navbar-link.is-active,.navbar.is-success .navbar-end>a.navbar-item:focus,.navbar.is-success .navbar-end>a.navbar-item:hover,.navbar.is-success .navbar-end>a.navbar-item.is-active,.navbar.is-success .navbar-end .navbar-link:focus,.navbar.is-success .navbar-end .navbar-link:hover,.navbar.is-success .navbar-end .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-start .navbar-link::after,.navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#22c35b;color:#fff}}.navbar.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>.navbar-item,.navbar.is-warning .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>a.navbar-item:focus,.navbar.is-warning .navbar-brand>a.navbar-item:hover,.navbar.is-warning .navbar-brand>a.navbar-item.is-active,.navbar.is-warning .navbar-brand .navbar-link:focus,.navbar.is-warning .navbar-brand .navbar-link:hover,.navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-warning .navbar-start>.navbar-item,.navbar.is-warning .navbar-start .navbar-link,.navbar.is-warning .navbar-end>.navbar-item,.navbar.is-warning .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start>a.navbar-item:focus,.navbar.is-warning .navbar-start>a.navbar-item:hover,.navbar.is-warning .navbar-start>a.navbar-item.is-active,.navbar.is-warning .navbar-start .navbar-link:focus,.navbar.is-warning .navbar-start .navbar-link:hover,.navbar.is-warning .navbar-start .navbar-link.is-active,.navbar.is-warning .navbar-end>a.navbar-item:focus,.navbar.is-warning .navbar-end>a.navbar-item:hover,.navbar.is-warning .navbar-end>a.navbar-item.is-active,.navbar.is-warning .navbar-end .navbar-link:focus,.navbar.is-warning .navbar-end .navbar-link:hover,.navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start .navbar-link::after,.navbar.is-warning .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ffdd57;color:rgba(0,0,0,0.7)}}.navbar.is-danger{background-color:#da0b00;color:#fff}.navbar.is-danger .navbar-brand>.navbar-item,.navbar.is-danger .navbar-brand .navbar-link{color:#fff}.navbar.is-danger .navbar-brand>a.navbar-item:focus,.navbar.is-danger .navbar-brand>a.navbar-item:hover,.navbar.is-danger .navbar-brand>a.navbar-item.is-active,.navbar.is-danger .navbar-brand .navbar-link:focus,.navbar.is-danger .navbar-brand .navbar-link:hover,.navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-danger .navbar-start>.navbar-item,.navbar.is-danger .navbar-start .navbar-link,.navbar.is-danger .navbar-end>.navbar-item,.navbar.is-danger .navbar-end .navbar-link{color:#fff}.navbar.is-danger .navbar-start>a.navbar-item:focus,.navbar.is-danger .navbar-start>a.navbar-item:hover,.navbar.is-danger .navbar-start>a.navbar-item.is-active,.navbar.is-danger .navbar-start .navbar-link:focus,.navbar.is-danger .navbar-start .navbar-link:hover,.navbar.is-danger .navbar-start .navbar-link.is-active,.navbar.is-danger .navbar-end>a.navbar-item:focus,.navbar.is-danger .navbar-end>a.navbar-item:hover,.navbar.is-danger .navbar-end>a.navbar-item.is-active,.navbar.is-danger .navbar-end .navbar-link:focus,.navbar.is-danger .navbar-end .navbar-link:hover,.navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-start .navbar-link::after,.navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#da0b00;color:#fff}}.navbar>.container{align-items:stretch;display:flex;min-height:3.25rem;width:100%}.navbar.has-shadow{box-shadow:0 2px 0 0 #f5f5f5}.navbar.is-fixed-bottom,.navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom{bottom:0}.navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #f5f5f5}.navbar.is-fixed-top{top:0}html.has-navbar-fixed-top,body.has-navbar-fixed-top{padding-top:3.25rem}html.has-navbar-fixed-bottom,body.has-navbar-fixed-bottom{padding-bottom:3.25rem}.navbar-brand,.navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:3.25rem}.navbar-brand a.navbar-item:focus,.navbar-brand a.navbar-item:hover{background-color:transparent}.navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}.navbar-burger{color:#222;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:3.25rem;position:relative;width:3.25rem;margin-left:auto}.navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}.navbar-burger span:nth-child(1){top:calc(50% - 6px)}.navbar-burger span:nth-child(2){top:calc(50% - 1px)}.navbar-burger span:nth-child(3){top:calc(50% + 4px)}.navbar-burger:hover{background-color:rgba(0,0,0,0.05)}.navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}.navbar-burger.is-active span:nth-child(2){opacity:0}.navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}.navbar-menu{display:none}.navbar-item,.navbar-link{color:#222;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}.navbar-item .icon:only-child,.navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}a.navbar-item,.navbar-link{cursor:pointer}a.navbar-item:focus,a.navbar-item:focus-within,a.navbar-item:hover,a.navbar-item.is-active,.navbar-link:focus,.navbar-link:focus-within,.navbar-link:hover,.navbar-link.is-active{background-color:#fafafa;color:#2e63b8}.navbar-item{flex-grow:0;flex-shrink:0}.navbar-item img{max-height:1.75rem}.navbar-item.has-dropdown{padding:0}.navbar-item.is-expanded{flex-grow:1;flex-shrink:1}.navbar-item.is-tab{border-bottom:1px solid transparent;min-height:3.25rem;padding-bottom:calc(0.5rem - 1px)}.navbar-item.is-tab:focus,.navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8}.navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8;border-bottom-style:solid;border-bottom-width:3px;color:#2e63b8;padding-bottom:calc(0.5rem - 3px)}.navbar-content{flex-grow:1;flex-shrink:1}.navbar-link:not(.is-arrowless){padding-right:2.5em}.navbar-link:not(.is-arrowless)::after{border-color:#2e63b8;margin-top:-0.375em;right:1.125em}.navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}.navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}.navbar-divider{background-color:#f5f5f5;border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){.navbar>.container{display:block}.navbar-brand .navbar-item,.navbar-tabs .navbar-item{align-items:center;display:flex}.navbar-link::after{display:none}.navbar-menu{background-color:#fff;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}.navbar-menu.is-active{display:block}.navbar.is-fixed-bottom-touch,.navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-touch{bottom:0}.navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-touch{top:0}.navbar.is-fixed-top .navbar-menu,.navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 3.25rem);overflow:auto}html.has-navbar-fixed-top-touch,body.has-navbar-fixed-top-touch{padding-top:3.25rem}html.has-navbar-fixed-bottom-touch,body.has-navbar-fixed-bottom-touch{padding-bottom:3.25rem}}@media screen and (min-width: 1056px){.navbar,.navbar-menu,.navbar-start,.navbar-end{align-items:stretch;display:flex}.navbar{min-height:3.25rem}.navbar.is-spaced{padding:1rem 2rem}.navbar.is-spaced .navbar-start,.navbar.is-spaced .navbar-end{align-items:center}.navbar.is-spaced a.navbar-item,.navbar.is-spaced .navbar-link{border-radius:4px}.navbar.is-transparent a.navbar-item:focus,.navbar.is-transparent a.navbar-item:hover,.navbar.is-transparent a.navbar-item.is-active,.navbar.is-transparent .navbar-link:focus,.navbar.is-transparent .navbar-link:hover,.navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}.navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}.navbar.is-transparent .navbar-dropdown a.navbar-item:focus,.navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar-burger{display:none}.navbar-item,.navbar-link{align-items:center;display:flex}.navbar-item.has-dropdown{align-items:stretch}.navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}.navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:2px solid #dbdbdb;border-radius:6px 6px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}.navbar-item.is-active .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced .navbar-item.is-active .navbar-dropdown,.navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:hover .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}.navbar-menu{flex-grow:1;flex-shrink:0}.navbar-start{justify-content:flex-start;margin-right:auto}.navbar-end{justify-content:flex-end;margin-left:auto}.navbar-dropdown{background-color:#fff;border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:2px solid #dbdbdb;box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}.navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}.navbar-dropdown a.navbar-item{padding-right:3rem}.navbar-dropdown a.navbar-item:focus,.navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar.is-spaced .navbar-dropdown,.navbar-dropdown.is-boxed{border-radius:6px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}.navbar-dropdown.is-right{left:auto;right:0}.navbar-divider{display:block}.navbar>.container .navbar-brand,.container>.navbar .navbar-brand{margin-left:-.75rem}.navbar>.container .navbar-menu,.container>.navbar .navbar-menu{margin-right:-.75rem}.navbar.is-fixed-bottom-desktop,.navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-desktop{bottom:0}.navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-desktop{top:0}html.has-navbar-fixed-top-desktop,body.has-navbar-fixed-top-desktop{padding-top:3.25rem}html.has-navbar-fixed-bottom-desktop,body.has-navbar-fixed-bottom-desktop{padding-bottom:3.25rem}html.has-spaced-navbar-fixed-top,body.has-spaced-navbar-fixed-top{padding-top:5.25rem}html.has-spaced-navbar-fixed-bottom,body.has-spaced-navbar-fixed-bottom{padding-bottom:5.25rem}a.navbar-item.is-active,.navbar-link.is-active{color:#0a0a0a}a.navbar-item.is-active:not(:focus):not(:hover),.navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}.navbar-item.has-dropdown:focus .navbar-link,.navbar-item.has-dropdown:hover .navbar-link,.navbar-item.has-dropdown.is-active .navbar-link{background-color:#fafafa}}.hero.is-fullheight-with-navbar{min-height:calc(100vh - 3.25rem)}.pagination{font-size:1rem;margin:-.25rem}.pagination.is-small,#documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}.pagination.is-medium{font-size:1.25rem}.pagination.is-large{font-size:1.5rem}.pagination.is-rounded .pagination-previous,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,.pagination.is-rounded .pagination-next,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}.pagination.is-rounded .pagination-link,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}.pagination,.pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}.pagination-previous,.pagination-next,.pagination-link{border-color:#dbdbdb;color:#222;min-width:2.5em}.pagination-previous:hover,.pagination-next:hover,.pagination-link:hover{border-color:#b5b5b5;color:#363636}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus{border-color:#3c5dcd}.pagination-previous:active,.pagination-next:active,.pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}.pagination-previous[disabled],.pagination-previous.is-disabled,.pagination-next[disabled],.pagination-next.is-disabled,.pagination-link[disabled],.pagination-link.is-disabled{background-color:#dbdbdb;border-color:#dbdbdb;box-shadow:none;color:#6b6b6b;opacity:0.5}.pagination-previous,.pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}.pagination-link.is-current{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.pagination-ellipsis{color:#b5b5b5;pointer-events:none}.pagination-list{flex-wrap:wrap}.pagination-list li{list-style:none}@media screen and (max-width: 768px){.pagination{flex-wrap:wrap}.pagination-previous,.pagination-next{flex-grow:1;flex-shrink:1}.pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{.pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{margin-bottom:0;margin-top:0}.pagination-previous{order:2}.pagination-next{order:3}.pagination{justify-content:space-between;margin-bottom:0;margin-top:0}.pagination.is-centered .pagination-previous{order:1}.pagination.is-centered .pagination-list{justify-content:center;order:2}.pagination.is-centered .pagination-next{order:3}.pagination.is-right .pagination-previous{order:1}.pagination.is-right .pagination-next{order:2}.pagination.is-right .pagination-list{justify-content:flex-end;order:3}}.panel{border-radius:6px;box-shadow:#bbb;font-size:1rem}.panel:not(:last-child){margin-bottom:1.5rem}.panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}.panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}.panel.is-white .panel-block.is-active .panel-icon{color:#fff}.panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}.panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}.panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}.panel.is-light .panel-heading{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.panel.is-light .panel-tabs a.is-active{border-bottom-color:#f5f5f5}.panel.is-light .panel-block.is-active .panel-icon{color:#f5f5f5}.panel.is-dark .panel-heading,.content kbd.panel .panel-heading{background-color:#363636;color:#fff}.panel.is-dark .panel-tabs a.is-active,.content kbd.panel .panel-tabs a.is-active{border-bottom-color:#363636}.panel.is-dark .panel-block.is-active .panel-icon,.content kbd.panel .panel-block.is-active .panel-icon{color:#363636}.panel.is-primary .panel-heading,.docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#4eb5de;color:#fff}.panel.is-primary .panel-tabs a.is-active,.docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#4eb5de}.panel.is-primary .panel-block.is-active .panel-icon,.docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#4eb5de}.panel.is-link .panel-heading{background-color:#2e63b8;color:#fff}.panel.is-link .panel-tabs a.is-active{border-bottom-color:#2e63b8}.panel.is-link .panel-block.is-active .panel-icon{color:#2e63b8}.panel.is-info .panel-heading{background-color:#209cee;color:#fff}.panel.is-info .panel-tabs a.is-active{border-bottom-color:#209cee}.panel.is-info .panel-block.is-active .panel-icon{color:#209cee}.panel.is-success .panel-heading{background-color:#22c35b;color:#fff}.panel.is-success .panel-tabs a.is-active{border-bottom-color:#22c35b}.panel.is-success .panel-block.is-active .panel-icon{color:#22c35b}.panel.is-warning .panel-heading{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ffdd57}.panel.is-warning .panel-block.is-active .panel-icon{color:#ffdd57}.panel.is-danger .panel-heading{background-color:#da0b00;color:#fff}.panel.is-danger .panel-tabs a.is-active{border-bottom-color:#da0b00}.panel.is-danger .panel-block.is-active .panel-icon{color:#da0b00}.panel-tabs:not(:last-child),.panel-block:not(:last-child){border-bottom:1px solid #ededed}.panel-heading{background-color:#ededed;border-radius:6px 6px 0 0;color:#222;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}.panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}.panel-tabs a{border-bottom:1px solid #dbdbdb;margin-bottom:-1px;padding:0.5em}.panel-tabs a.is-active{border-bottom-color:#4a4a4a;color:#363636}.panel-list a{color:#222}.panel-list a:hover{color:#2e63b8}.panel-block{align-items:center;color:#222;display:flex;justify-content:flex-start;padding:0.5em 0.75em}.panel-block input[type="checkbox"]{margin-right:.75em}.panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}.panel-block.is-wrapped{flex-wrap:wrap}.panel-block.is-active{border-left-color:#2e63b8;color:#363636}.panel-block.is-active .panel-icon{color:#2e63b8}.panel-block:last-child{border-bottom-left-radius:6px;border-bottom-right-radius:6px}a.panel-block,label.panel-block{cursor:pointer}a.panel-block:hover,label.panel-block:hover{background-color:#f5f5f5}.panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#6b6b6b;margin-right:.75em}.panel-icon .fa{font-size:inherit;line-height:inherit}.tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}.tabs a{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;color:#222;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}.tabs a:hover{border-bottom-color:#222;color:#222}.tabs li{display:block}.tabs li.is-active a{border-bottom-color:#2e63b8;color:#2e63b8}.tabs ul{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}.tabs ul.is-left{padding-right:0.75em}.tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}.tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}.tabs .icon:first-child{margin-right:.5em}.tabs .icon:last-child{margin-left:.5em}.tabs.is-centered ul{justify-content:center}.tabs.is-right ul{justify-content:flex-end}.tabs.is-boxed a{border:1px solid transparent;border-radius:4px 4px 0 0}.tabs.is-boxed a:hover{background-color:#f5f5f5;border-bottom-color:#dbdbdb}.tabs.is-boxed li.is-active a{background-color:#fff;border-color:#dbdbdb;border-bottom-color:rgba(0,0,0,0) !important}.tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}.tabs.is-toggle a{border-color:#dbdbdb;border-style:solid;border-width:1px;margin-bottom:0;position:relative}.tabs.is-toggle a:hover{background-color:#f5f5f5;border-color:#b5b5b5;z-index:2}.tabs.is-toggle li+li{margin-left:-1px}.tabs.is-toggle li:first-child a{border-top-left-radius:4px;border-bottom-left-radius:4px}.tabs.is-toggle li:last-child a{border-top-right-radius:4px;border-bottom-right-radius:4px}.tabs.is-toggle li.is-active a{background-color:#2e63b8;border-color:#2e63b8;color:#fff;z-index:1}.tabs.is-toggle ul{border-bottom:none}.tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}.tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}.tabs.is-small,#documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}.tabs.is-medium{font-size:1.25rem}.tabs.is-large{font-size:1.5rem}.column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>.column.is-narrow{flex:none;width:unset}.columns.is-mobile>.column.is-full{flex:none;width:100%}.columns.is-mobile>.column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>.column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>.column.is-half{flex:none;width:50%}.columns.is-mobile>.column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>.column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>.column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>.column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>.column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>.column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>.column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>.column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>.column.is-offset-half{margin-left:50%}.columns.is-mobile>.column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>.column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>.column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>.column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>.column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>.column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>.column.is-0{flex:none;width:0%}.columns.is-mobile>.column.is-offset-0{margin-left:0%}.columns.is-mobile>.column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>.column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>.column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>.column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>.column.is-3{flex:none;width:25%}.columns.is-mobile>.column.is-offset-3{margin-left:25%}.columns.is-mobile>.column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>.column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>.column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>.column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>.column.is-6{flex:none;width:50%}.columns.is-mobile>.column.is-offset-6{margin-left:50%}.columns.is-mobile>.column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>.column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>.column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>.column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>.column.is-9{flex:none;width:75%}.columns.is-mobile>.column.is-offset-9{margin-left:75%}.columns.is-mobile>.column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>.column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>.column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>.column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>.column.is-12{flex:none;width:100%}.columns.is-mobile>.column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){.column.is-narrow-mobile{flex:none;width:unset}.column.is-full-mobile{flex:none;width:100%}.column.is-three-quarters-mobile{flex:none;width:75%}.column.is-two-thirds-mobile{flex:none;width:66.6666%}.column.is-half-mobile{flex:none;width:50%}.column.is-one-third-mobile{flex:none;width:33.3333%}.column.is-one-quarter-mobile{flex:none;width:25%}.column.is-one-fifth-mobile{flex:none;width:20%}.column.is-two-fifths-mobile{flex:none;width:40%}.column.is-three-fifths-mobile{flex:none;width:60%}.column.is-four-fifths-mobile{flex:none;width:80%}.column.is-offset-three-quarters-mobile{margin-left:75%}.column.is-offset-two-thirds-mobile{margin-left:66.6666%}.column.is-offset-half-mobile{margin-left:50%}.column.is-offset-one-third-mobile{margin-left:33.3333%}.column.is-offset-one-quarter-mobile{margin-left:25%}.column.is-offset-one-fifth-mobile{margin-left:20%}.column.is-offset-two-fifths-mobile{margin-left:40%}.column.is-offset-three-fifths-mobile{margin-left:60%}.column.is-offset-four-fifths-mobile{margin-left:80%}.column.is-0-mobile{flex:none;width:0%}.column.is-offset-0-mobile{margin-left:0%}.column.is-1-mobile{flex:none;width:8.33333337%}.column.is-offset-1-mobile{margin-left:8.33333337%}.column.is-2-mobile{flex:none;width:16.66666674%}.column.is-offset-2-mobile{margin-left:16.66666674%}.column.is-3-mobile{flex:none;width:25%}.column.is-offset-3-mobile{margin-left:25%}.column.is-4-mobile{flex:none;width:33.33333337%}.column.is-offset-4-mobile{margin-left:33.33333337%}.column.is-5-mobile{flex:none;width:41.66666674%}.column.is-offset-5-mobile{margin-left:41.66666674%}.column.is-6-mobile{flex:none;width:50%}.column.is-offset-6-mobile{margin-left:50%}.column.is-7-mobile{flex:none;width:58.33333337%}.column.is-offset-7-mobile{margin-left:58.33333337%}.column.is-8-mobile{flex:none;width:66.66666674%}.column.is-offset-8-mobile{margin-left:66.66666674%}.column.is-9-mobile{flex:none;width:75%}.column.is-offset-9-mobile{margin-left:75%}.column.is-10-mobile{flex:none;width:83.33333337%}.column.is-offset-10-mobile{margin-left:83.33333337%}.column.is-11-mobile{flex:none;width:91.66666674%}.column.is-offset-11-mobile{margin-left:91.66666674%}.column.is-12-mobile{flex:none;width:100%}.column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{.column.is-narrow,.column.is-narrow-tablet{flex:none;width:unset}.column.is-full,.column.is-full-tablet{flex:none;width:100%}.column.is-three-quarters,.column.is-three-quarters-tablet{flex:none;width:75%}.column.is-two-thirds,.column.is-two-thirds-tablet{flex:none;width:66.6666%}.column.is-half,.column.is-half-tablet{flex:none;width:50%}.column.is-one-third,.column.is-one-third-tablet{flex:none;width:33.3333%}.column.is-one-quarter,.column.is-one-quarter-tablet{flex:none;width:25%}.column.is-one-fifth,.column.is-one-fifth-tablet{flex:none;width:20%}.column.is-two-fifths,.column.is-two-fifths-tablet{flex:none;width:40%}.column.is-three-fifths,.column.is-three-fifths-tablet{flex:none;width:60%}.column.is-four-fifths,.column.is-four-fifths-tablet{flex:none;width:80%}.column.is-offset-three-quarters,.column.is-offset-three-quarters-tablet{margin-left:75%}.column.is-offset-two-thirds,.column.is-offset-two-thirds-tablet{margin-left:66.6666%}.column.is-offset-half,.column.is-offset-half-tablet{margin-left:50%}.column.is-offset-one-third,.column.is-offset-one-third-tablet{margin-left:33.3333%}.column.is-offset-one-quarter,.column.is-offset-one-quarter-tablet{margin-left:25%}.column.is-offset-one-fifth,.column.is-offset-one-fifth-tablet{margin-left:20%}.column.is-offset-two-fifths,.column.is-offset-two-fifths-tablet{margin-left:40%}.column.is-offset-three-fifths,.column.is-offset-three-fifths-tablet{margin-left:60%}.column.is-offset-four-fifths,.column.is-offset-four-fifths-tablet{margin-left:80%}.column.is-0,.column.is-0-tablet{flex:none;width:0%}.column.is-offset-0,.column.is-offset-0-tablet{margin-left:0%}.column.is-1,.column.is-1-tablet{flex:none;width:8.33333337%}.column.is-offset-1,.column.is-offset-1-tablet{margin-left:8.33333337%}.column.is-2,.column.is-2-tablet{flex:none;width:16.66666674%}.column.is-offset-2,.column.is-offset-2-tablet{margin-left:16.66666674%}.column.is-3,.column.is-3-tablet{flex:none;width:25%}.column.is-offset-3,.column.is-offset-3-tablet{margin-left:25%}.column.is-4,.column.is-4-tablet{flex:none;width:33.33333337%}.column.is-offset-4,.column.is-offset-4-tablet{margin-left:33.33333337%}.column.is-5,.column.is-5-tablet{flex:none;width:41.66666674%}.column.is-offset-5,.column.is-offset-5-tablet{margin-left:41.66666674%}.column.is-6,.column.is-6-tablet{flex:none;width:50%}.column.is-offset-6,.column.is-offset-6-tablet{margin-left:50%}.column.is-7,.column.is-7-tablet{flex:none;width:58.33333337%}.column.is-offset-7,.column.is-offset-7-tablet{margin-left:58.33333337%}.column.is-8,.column.is-8-tablet{flex:none;width:66.66666674%}.column.is-offset-8,.column.is-offset-8-tablet{margin-left:66.66666674%}.column.is-9,.column.is-9-tablet{flex:none;width:75%}.column.is-offset-9,.column.is-offset-9-tablet{margin-left:75%}.column.is-10,.column.is-10-tablet{flex:none;width:83.33333337%}.column.is-offset-10,.column.is-offset-10-tablet{margin-left:83.33333337%}.column.is-11,.column.is-11-tablet{flex:none;width:91.66666674%}.column.is-offset-11,.column.is-offset-11-tablet{margin-left:91.66666674%}.column.is-12,.column.is-12-tablet{flex:none;width:100%}.column.is-offset-12,.column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){.column.is-narrow-touch{flex:none;width:unset}.column.is-full-touch{flex:none;width:100%}.column.is-three-quarters-touch{flex:none;width:75%}.column.is-two-thirds-touch{flex:none;width:66.6666%}.column.is-half-touch{flex:none;width:50%}.column.is-one-third-touch{flex:none;width:33.3333%}.column.is-one-quarter-touch{flex:none;width:25%}.column.is-one-fifth-touch{flex:none;width:20%}.column.is-two-fifths-touch{flex:none;width:40%}.column.is-three-fifths-touch{flex:none;width:60%}.column.is-four-fifths-touch{flex:none;width:80%}.column.is-offset-three-quarters-touch{margin-left:75%}.column.is-offset-two-thirds-touch{margin-left:66.6666%}.column.is-offset-half-touch{margin-left:50%}.column.is-offset-one-third-touch{margin-left:33.3333%}.column.is-offset-one-quarter-touch{margin-left:25%}.column.is-offset-one-fifth-touch{margin-left:20%}.column.is-offset-two-fifths-touch{margin-left:40%}.column.is-offset-three-fifths-touch{margin-left:60%}.column.is-offset-four-fifths-touch{margin-left:80%}.column.is-0-touch{flex:none;width:0%}.column.is-offset-0-touch{margin-left:0%}.column.is-1-touch{flex:none;width:8.33333337%}.column.is-offset-1-touch{margin-left:8.33333337%}.column.is-2-touch{flex:none;width:16.66666674%}.column.is-offset-2-touch{margin-left:16.66666674%}.column.is-3-touch{flex:none;width:25%}.column.is-offset-3-touch{margin-left:25%}.column.is-4-touch{flex:none;width:33.33333337%}.column.is-offset-4-touch{margin-left:33.33333337%}.column.is-5-touch{flex:none;width:41.66666674%}.column.is-offset-5-touch{margin-left:41.66666674%}.column.is-6-touch{flex:none;width:50%}.column.is-offset-6-touch{margin-left:50%}.column.is-7-touch{flex:none;width:58.33333337%}.column.is-offset-7-touch{margin-left:58.33333337%}.column.is-8-touch{flex:none;width:66.66666674%}.column.is-offset-8-touch{margin-left:66.66666674%}.column.is-9-touch{flex:none;width:75%}.column.is-offset-9-touch{margin-left:75%}.column.is-10-touch{flex:none;width:83.33333337%}.column.is-offset-10-touch{margin-left:83.33333337%}.column.is-11-touch{flex:none;width:91.66666674%}.column.is-offset-11-touch{margin-left:91.66666674%}.column.is-12-touch{flex:none;width:100%}.column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){.column.is-narrow-desktop{flex:none;width:unset}.column.is-full-desktop{flex:none;width:100%}.column.is-three-quarters-desktop{flex:none;width:75%}.column.is-two-thirds-desktop{flex:none;width:66.6666%}.column.is-half-desktop{flex:none;width:50%}.column.is-one-third-desktop{flex:none;width:33.3333%}.column.is-one-quarter-desktop{flex:none;width:25%}.column.is-one-fifth-desktop{flex:none;width:20%}.column.is-two-fifths-desktop{flex:none;width:40%}.column.is-three-fifths-desktop{flex:none;width:60%}.column.is-four-fifths-desktop{flex:none;width:80%}.column.is-offset-three-quarters-desktop{margin-left:75%}.column.is-offset-two-thirds-desktop{margin-left:66.6666%}.column.is-offset-half-desktop{margin-left:50%}.column.is-offset-one-third-desktop{margin-left:33.3333%}.column.is-offset-one-quarter-desktop{margin-left:25%}.column.is-offset-one-fifth-desktop{margin-left:20%}.column.is-offset-two-fifths-desktop{margin-left:40%}.column.is-offset-three-fifths-desktop{margin-left:60%}.column.is-offset-four-fifths-desktop{margin-left:80%}.column.is-0-desktop{flex:none;width:0%}.column.is-offset-0-desktop{margin-left:0%}.column.is-1-desktop{flex:none;width:8.33333337%}.column.is-offset-1-desktop{margin-left:8.33333337%}.column.is-2-desktop{flex:none;width:16.66666674%}.column.is-offset-2-desktop{margin-left:16.66666674%}.column.is-3-desktop{flex:none;width:25%}.column.is-offset-3-desktop{margin-left:25%}.column.is-4-desktop{flex:none;width:33.33333337%}.column.is-offset-4-desktop{margin-left:33.33333337%}.column.is-5-desktop{flex:none;width:41.66666674%}.column.is-offset-5-desktop{margin-left:41.66666674%}.column.is-6-desktop{flex:none;width:50%}.column.is-offset-6-desktop{margin-left:50%}.column.is-7-desktop{flex:none;width:58.33333337%}.column.is-offset-7-desktop{margin-left:58.33333337%}.column.is-8-desktop{flex:none;width:66.66666674%}.column.is-offset-8-desktop{margin-left:66.66666674%}.column.is-9-desktop{flex:none;width:75%}.column.is-offset-9-desktop{margin-left:75%}.column.is-10-desktop{flex:none;width:83.33333337%}.column.is-offset-10-desktop{margin-left:83.33333337%}.column.is-11-desktop{flex:none;width:91.66666674%}.column.is-offset-11-desktop{margin-left:91.66666674%}.column.is-12-desktop{flex:none;width:100%}.column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){.column.is-narrow-widescreen{flex:none;width:unset}.column.is-full-widescreen{flex:none;width:100%}.column.is-three-quarters-widescreen{flex:none;width:75%}.column.is-two-thirds-widescreen{flex:none;width:66.6666%}.column.is-half-widescreen{flex:none;width:50%}.column.is-one-third-widescreen{flex:none;width:33.3333%}.column.is-one-quarter-widescreen{flex:none;width:25%}.column.is-one-fifth-widescreen{flex:none;width:20%}.column.is-two-fifths-widescreen{flex:none;width:40%}.column.is-three-fifths-widescreen{flex:none;width:60%}.column.is-four-fifths-widescreen{flex:none;width:80%}.column.is-offset-three-quarters-widescreen{margin-left:75%}.column.is-offset-two-thirds-widescreen{margin-left:66.6666%}.column.is-offset-half-widescreen{margin-left:50%}.column.is-offset-one-third-widescreen{margin-left:33.3333%}.column.is-offset-one-quarter-widescreen{margin-left:25%}.column.is-offset-one-fifth-widescreen{margin-left:20%}.column.is-offset-two-fifths-widescreen{margin-left:40%}.column.is-offset-three-fifths-widescreen{margin-left:60%}.column.is-offset-four-fifths-widescreen{margin-left:80%}.column.is-0-widescreen{flex:none;width:0%}.column.is-offset-0-widescreen{margin-left:0%}.column.is-1-widescreen{flex:none;width:8.33333337%}.column.is-offset-1-widescreen{margin-left:8.33333337%}.column.is-2-widescreen{flex:none;width:16.66666674%}.column.is-offset-2-widescreen{margin-left:16.66666674%}.column.is-3-widescreen{flex:none;width:25%}.column.is-offset-3-widescreen{margin-left:25%}.column.is-4-widescreen{flex:none;width:33.33333337%}.column.is-offset-4-widescreen{margin-left:33.33333337%}.column.is-5-widescreen{flex:none;width:41.66666674%}.column.is-offset-5-widescreen{margin-left:41.66666674%}.column.is-6-widescreen{flex:none;width:50%}.column.is-offset-6-widescreen{margin-left:50%}.column.is-7-widescreen{flex:none;width:58.33333337%}.column.is-offset-7-widescreen{margin-left:58.33333337%}.column.is-8-widescreen{flex:none;width:66.66666674%}.column.is-offset-8-widescreen{margin-left:66.66666674%}.column.is-9-widescreen{flex:none;width:75%}.column.is-offset-9-widescreen{margin-left:75%}.column.is-10-widescreen{flex:none;width:83.33333337%}.column.is-offset-10-widescreen{margin-left:83.33333337%}.column.is-11-widescreen{flex:none;width:91.66666674%}.column.is-offset-11-widescreen{margin-left:91.66666674%}.column.is-12-widescreen{flex:none;width:100%}.column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){.column.is-narrow-fullhd{flex:none;width:unset}.column.is-full-fullhd{flex:none;width:100%}.column.is-three-quarters-fullhd{flex:none;width:75%}.column.is-two-thirds-fullhd{flex:none;width:66.6666%}.column.is-half-fullhd{flex:none;width:50%}.column.is-one-third-fullhd{flex:none;width:33.3333%}.column.is-one-quarter-fullhd{flex:none;width:25%}.column.is-one-fifth-fullhd{flex:none;width:20%}.column.is-two-fifths-fullhd{flex:none;width:40%}.column.is-three-fifths-fullhd{flex:none;width:60%}.column.is-four-fifths-fullhd{flex:none;width:80%}.column.is-offset-three-quarters-fullhd{margin-left:75%}.column.is-offset-two-thirds-fullhd{margin-left:66.6666%}.column.is-offset-half-fullhd{margin-left:50%}.column.is-offset-one-third-fullhd{margin-left:33.3333%}.column.is-offset-one-quarter-fullhd{margin-left:25%}.column.is-offset-one-fifth-fullhd{margin-left:20%}.column.is-offset-two-fifths-fullhd{margin-left:40%}.column.is-offset-three-fifths-fullhd{margin-left:60%}.column.is-offset-four-fifths-fullhd{margin-left:80%}.column.is-0-fullhd{flex:none;width:0%}.column.is-offset-0-fullhd{margin-left:0%}.column.is-1-fullhd{flex:none;width:8.33333337%}.column.is-offset-1-fullhd{margin-left:8.33333337%}.column.is-2-fullhd{flex:none;width:16.66666674%}.column.is-offset-2-fullhd{margin-left:16.66666674%}.column.is-3-fullhd{flex:none;width:25%}.column.is-offset-3-fullhd{margin-left:25%}.column.is-4-fullhd{flex:none;width:33.33333337%}.column.is-offset-4-fullhd{margin-left:33.33333337%}.column.is-5-fullhd{flex:none;width:41.66666674%}.column.is-offset-5-fullhd{margin-left:41.66666674%}.column.is-6-fullhd{flex:none;width:50%}.column.is-offset-6-fullhd{margin-left:50%}.column.is-7-fullhd{flex:none;width:58.33333337%}.column.is-offset-7-fullhd{margin-left:58.33333337%}.column.is-8-fullhd{flex:none;width:66.66666674%}.column.is-offset-8-fullhd{margin-left:66.66666674%}.column.is-9-fullhd{flex:none;width:75%}.column.is-offset-9-fullhd{margin-left:75%}.column.is-10-fullhd{flex:none;width:83.33333337%}.column.is-offset-10-fullhd{margin-left:83.33333337%}.column.is-11-fullhd{flex:none;width:91.66666674%}.column.is-offset-11-fullhd{margin-left:91.66666674%}.column.is-12-fullhd{flex:none;width:100%}.column.is-offset-12-fullhd{margin-left:100%}}.columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.columns:last-child{margin-bottom:-.75rem}.columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}.columns.is-centered{justify-content:center}.columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}.columns.is-gapless>.column{margin:0;padding:0 !important}.columns.is-gapless:not(:last-child){margin-bottom:1.5rem}.columns.is-gapless:last-child{margin-bottom:0}.columns.is-mobile{display:flex}.columns.is-multiline{flex-wrap:wrap}.columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{.columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){.columns.is-desktop{display:flex}}.columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}.columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}.columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){.columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-0-fullhd{--columnGap: 0rem}}.columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){.columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-1-fullhd{--columnGap: .25rem}}.columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){.columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-2-fullhd{--columnGap: .5rem}}.columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){.columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-3-fullhd{--columnGap: .75rem}}.columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){.columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-4-fullhd{--columnGap: 1rem}}.columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){.columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}.columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){.columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}.columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){.columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}.columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){.columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-8-fullhd{--columnGap: 2rem}}.tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}.tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.tile.is-ancestor:last-child{margin-bottom:-.75rem}.tile.is-ancestor:not(:last-child){margin-bottom:.75rem}.tile.is-child{margin:0 !important}.tile.is-parent{padding:.75rem}.tile.is-vertical{flex-direction:column}.tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{.tile:not(.is-child){display:flex}.tile.is-1{flex:none;width:8.33333337%}.tile.is-2{flex:none;width:16.66666674%}.tile.is-3{flex:none;width:25%}.tile.is-4{flex:none;width:33.33333337%}.tile.is-5{flex:none;width:41.66666674%}.tile.is-6{flex:none;width:50%}.tile.is-7{flex:none;width:58.33333337%}.tile.is-8{flex:none;width:66.66666674%}.tile.is-9{flex:none;width:75%}.tile.is-10{flex:none;width:83.33333337%}.tile.is-11{flex:none;width:91.66666674%}.tile.is-12{flex:none;width:100%}}.hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}.hero .navbar{background:none}.hero .tabs ul{border-bottom:none}.hero.is-white{background-color:#fff;color:#0a0a0a}.hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-white strong{color:inherit}.hero.is-white .title{color:#0a0a0a}.hero.is-white .subtitle{color:rgba(10,10,10,0.9)}.hero.is-white .subtitle a:not(.button),.hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){.hero.is-white .navbar-menu{background-color:#fff}}.hero.is-white .navbar-item,.hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}.hero.is-white a.navbar-item:hover,.hero.is-white a.navbar-item.is-active,.hero.is-white .navbar-link:hover,.hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}.hero.is-white .tabs a:hover{opacity:1}.hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}.hero.is-white .tabs.is-boxed a,.hero.is-white .tabs.is-toggle a{color:#0a0a0a}.hero.is-white .tabs.is-boxed a:hover,.hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-white .tabs.is-boxed li.is-active a,.hero.is-white .tabs.is-boxed li.is-active a:hover,.hero.is-white .tabs.is-toggle li.is-active a,.hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}.hero.is-black{background-color:#0a0a0a;color:#fff}.hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-black strong{color:inherit}.hero.is-black .title{color:#fff}.hero.is-black .subtitle{color:rgba(255,255,255,0.9)}.hero.is-black .subtitle a:not(.button),.hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-black .navbar-menu{background-color:#0a0a0a}}.hero.is-black .navbar-item,.hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-black a.navbar-item:hover,.hero.is-black a.navbar-item.is-active,.hero.is-black .navbar-link:hover,.hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}.hero.is-black .tabs a{color:#fff;opacity:0.9}.hero.is-black .tabs a:hover{opacity:1}.hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}.hero.is-black .tabs.is-boxed a,.hero.is-black .tabs.is-toggle a{color:#fff}.hero.is-black .tabs.is-boxed a:hover,.hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-black .tabs.is-boxed li.is-active a,.hero.is-black .tabs.is-boxed li.is-active a:hover,.hero.is-black .tabs.is-toggle li.is-active a,.hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}.hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){.hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}.hero.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-light strong{color:inherit}.hero.is-light .title{color:rgba(0,0,0,0.7)}.hero.is-light .subtitle{color:rgba(0,0,0,0.9)}.hero.is-light .subtitle a:not(.button),.hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-light .navbar-menu{background-color:#f5f5f5}}.hero.is-light .navbar-item,.hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-light a.navbar-item:hover,.hero.is-light a.navbar-item.is-active,.hero.is-light .navbar-link:hover,.hero.is-light .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-light .tabs a:hover{opacity:1}.hero.is-light .tabs li.is-active a{color:#f5f5f5 !important;opacity:1}.hero.is-light .tabs.is-boxed a,.hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-light .tabs.is-boxed a:hover,.hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-light .tabs.is-boxed li.is-active a,.hero.is-light .tabs.is-boxed li.is-active a:hover,.hero.is-light .tabs.is-toggle li.is-active a,.hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#f5f5f5}.hero.is-light.is-bold{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}}.hero.is-dark,.content kbd.hero{background-color:#363636;color:#fff}.hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-dark strong,.content kbd.hero strong{color:inherit}.hero.is-dark .title,.content kbd.hero .title{color:#fff}.hero.is-dark .subtitle,.content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}.hero.is-dark .subtitle a:not(.button),.content kbd.hero .subtitle a:not(.button),.hero.is-dark .subtitle strong,.content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-dark .navbar-menu,.content kbd.hero .navbar-menu{background-color:#363636}}.hero.is-dark .navbar-item,.content kbd.hero .navbar-item,.hero.is-dark .navbar-link,.content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-dark a.navbar-item:hover,.content kbd.hero a.navbar-item:hover,.hero.is-dark a.navbar-item.is-active,.content kbd.hero a.navbar-item.is-active,.hero.is-dark .navbar-link:hover,.content kbd.hero .navbar-link:hover,.hero.is-dark .navbar-link.is-active,.content kbd.hero .navbar-link.is-active{background-color:#292929;color:#fff}.hero.is-dark .tabs a,.content kbd.hero .tabs a{color:#fff;opacity:0.9}.hero.is-dark .tabs a:hover,.content kbd.hero .tabs a:hover{opacity:1}.hero.is-dark .tabs li.is-active a,.content kbd.hero .tabs li.is-active a{color:#363636 !important;opacity:1}.hero.is-dark .tabs.is-boxed a,.content kbd.hero .tabs.is-boxed a,.hero.is-dark .tabs.is-toggle a,.content kbd.hero .tabs.is-toggle a{color:#fff}.hero.is-dark .tabs.is-boxed a:hover,.content kbd.hero .tabs.is-boxed a:hover,.hero.is-dark .tabs.is-toggle a:hover,.content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-dark .tabs.is-boxed li.is-active a,.content kbd.hero .tabs.is-boxed li.is-active a,.hero.is-dark .tabs.is-boxed li.is-active a:hover,.hero.is-dark .tabs.is-toggle li.is-active a,.content kbd.hero .tabs.is-toggle li.is-active a,.hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#363636}.hero.is-dark.is-bold,.content kbd.hero.is-bold{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}@media screen and (max-width: 768px){.hero.is-dark.is-bold .navbar-menu,.content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}}.hero.is-primary,.docstring>section>a.hero.docs-sourcelink{background-color:#4eb5de;color:#fff}.hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-primary strong,.docstring>section>a.hero.docs-sourcelink strong{color:inherit}.hero.is-primary .title,.docstring>section>a.hero.docs-sourcelink .title{color:#fff}.hero.is-primary .subtitle,.docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}.hero.is-primary .subtitle a:not(.button),.docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),.hero.is-primary .subtitle strong,.docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-primary .navbar-menu,.docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#4eb5de}}.hero.is-primary .navbar-item,.docstring>section>a.hero.docs-sourcelink .navbar-item,.hero.is-primary .navbar-link,.docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-primary a.navbar-item:hover,.docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,.hero.is-primary a.navbar-item.is-active,.docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,.hero.is-primary .navbar-link:hover,.docstring>section>a.hero.docs-sourcelink .navbar-link:hover,.hero.is-primary .navbar-link.is-active,.docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#39acda;color:#fff}.hero.is-primary .tabs a,.docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}.hero.is-primary .tabs a:hover,.docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}.hero.is-primary .tabs li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#4eb5de !important;opacity:1}.hero.is-primary .tabs.is-boxed a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,.hero.is-primary .tabs.is-toggle a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}.hero.is-primary .tabs.is-boxed a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,.hero.is-primary .tabs.is-toggle a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-primary .tabs.is-boxed li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,.hero.is-primary .tabs.is-boxed li.is-active a:hover,.hero.is-primary .tabs.is-toggle li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,.hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#4eb5de}.hero.is-primary.is-bold,.docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}@media screen and (max-width: 768px){.hero.is-primary.is-bold .navbar-menu,.docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}}.hero.is-link{background-color:#2e63b8;color:#fff}.hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-link strong{color:inherit}.hero.is-link .title{color:#fff}.hero.is-link .subtitle{color:rgba(255,255,255,0.9)}.hero.is-link .subtitle a:not(.button),.hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-link .navbar-menu{background-color:#2e63b8}}.hero.is-link .navbar-item,.hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-link a.navbar-item:hover,.hero.is-link a.navbar-item.is-active,.hero.is-link .navbar-link:hover,.hero.is-link .navbar-link.is-active{background-color:#2958a4;color:#fff}.hero.is-link .tabs a{color:#fff;opacity:0.9}.hero.is-link .tabs a:hover{opacity:1}.hero.is-link .tabs li.is-active a{color:#2e63b8 !important;opacity:1}.hero.is-link .tabs.is-boxed a,.hero.is-link .tabs.is-toggle a{color:#fff}.hero.is-link .tabs.is-boxed a:hover,.hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-link .tabs.is-boxed li.is-active a,.hero.is-link .tabs.is-boxed li.is-active a:hover,.hero.is-link .tabs.is-toggle li.is-active a,.hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#2e63b8}.hero.is-link.is-bold{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}@media screen and (max-width: 768px){.hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}}.hero.is-info{background-color:#209cee;color:#fff}.hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-info strong{color:inherit}.hero.is-info .title{color:#fff}.hero.is-info .subtitle{color:rgba(255,255,255,0.9)}.hero.is-info .subtitle a:not(.button),.hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-info .navbar-menu{background-color:#209cee}}.hero.is-info .navbar-item,.hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-info a.navbar-item:hover,.hero.is-info a.navbar-item.is-active,.hero.is-info .navbar-link:hover,.hero.is-info .navbar-link.is-active{background-color:#1190e3;color:#fff}.hero.is-info .tabs a{color:#fff;opacity:0.9}.hero.is-info .tabs a:hover{opacity:1}.hero.is-info .tabs li.is-active a{color:#209cee !important;opacity:1}.hero.is-info .tabs.is-boxed a,.hero.is-info .tabs.is-toggle a{color:#fff}.hero.is-info .tabs.is-boxed a:hover,.hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-info .tabs.is-boxed li.is-active a,.hero.is-info .tabs.is-boxed li.is-active a:hover,.hero.is-info .tabs.is-toggle li.is-active a,.hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#209cee}.hero.is-info.is-bold{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}@media screen and (max-width: 768px){.hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}}.hero.is-success{background-color:#22c35b;color:#fff}.hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-success strong{color:inherit}.hero.is-success .title{color:#fff}.hero.is-success .subtitle{color:rgba(255,255,255,0.9)}.hero.is-success .subtitle a:not(.button),.hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-success .navbar-menu{background-color:#22c35b}}.hero.is-success .navbar-item,.hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-success a.navbar-item:hover,.hero.is-success a.navbar-item.is-active,.hero.is-success .navbar-link:hover,.hero.is-success .navbar-link.is-active{background-color:#1ead51;color:#fff}.hero.is-success .tabs a{color:#fff;opacity:0.9}.hero.is-success .tabs a:hover{opacity:1}.hero.is-success .tabs li.is-active a{color:#22c35b !important;opacity:1}.hero.is-success .tabs.is-boxed a,.hero.is-success .tabs.is-toggle a{color:#fff}.hero.is-success .tabs.is-boxed a:hover,.hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-success .tabs.is-boxed li.is-active a,.hero.is-success .tabs.is-boxed li.is-active a:hover,.hero.is-success .tabs.is-toggle li.is-active a,.hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#22c35b}.hero.is-success.is-bold{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}@media screen and (max-width: 768px){.hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}}.hero.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-warning strong{color:inherit}.hero.is-warning .title{color:rgba(0,0,0,0.7)}.hero.is-warning .subtitle{color:rgba(0,0,0,0.9)}.hero.is-warning .subtitle a:not(.button),.hero.is-warning .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-warning .navbar-menu{background-color:#ffdd57}}.hero.is-warning .navbar-item,.hero.is-warning .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-warning a.navbar-item:hover,.hero.is-warning a.navbar-item.is-active,.hero.is-warning .navbar-link:hover,.hero.is-warning .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.hero.is-warning .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-warning .tabs a:hover{opacity:1}.hero.is-warning .tabs li.is-active a{color:#ffdd57 !important;opacity:1}.hero.is-warning .tabs.is-boxed a,.hero.is-warning .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-warning .tabs.is-boxed a:hover,.hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-warning .tabs.is-boxed li.is-active a,.hero.is-warning .tabs.is-boxed li.is-active a:hover,.hero.is-warning .tabs.is-toggle li.is-active a,.hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ffdd57}.hero.is-warning.is-bold{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}@media screen and (max-width: 768px){.hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}}.hero.is-danger{background-color:#da0b00;color:#fff}.hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-danger strong{color:inherit}.hero.is-danger .title{color:#fff}.hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}.hero.is-danger .subtitle a:not(.button),.hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-danger .navbar-menu{background-color:#da0b00}}.hero.is-danger .navbar-item,.hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-danger a.navbar-item:hover,.hero.is-danger a.navbar-item.is-active,.hero.is-danger .navbar-link:hover,.hero.is-danger .navbar-link.is-active{background-color:#c10a00;color:#fff}.hero.is-danger .tabs a{color:#fff;opacity:0.9}.hero.is-danger .tabs a:hover{opacity:1}.hero.is-danger .tabs li.is-active a{color:#da0b00 !important;opacity:1}.hero.is-danger .tabs.is-boxed a,.hero.is-danger .tabs.is-toggle a{color:#fff}.hero.is-danger .tabs.is-boxed a:hover,.hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-danger .tabs.is-boxed li.is-active a,.hero.is-danger .tabs.is-boxed li.is-active a:hover,.hero.is-danger .tabs.is-toggle li.is-active a,.hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#da0b00}.hero.is-danger.is-bold{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}@media screen and (max-width: 768px){.hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}}.hero.is-small .hero-body,#documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{.hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{.hero.is-large .hero-body{padding:18rem 6rem}}.hero.is-halfheight .hero-body,.hero.is-fullheight .hero-body,.hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}.hero.is-halfheight .hero-body>.container,.hero.is-fullheight .hero-body>.container,.hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}.hero.is-halfheight{min-height:50vh}.hero.is-fullheight{min-height:100vh}.hero-video{overflow:hidden}.hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}.hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){.hero-video{display:none}}.hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){.hero-buttons .button{display:flex}.hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{.hero-buttons{display:flex;justify-content:center}.hero-buttons .button:not(:last-child){margin-right:1.5rem}}.hero-head,.hero-foot{flex-grow:0;flex-shrink:0}.hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{.hero-body{padding:3rem 3rem}}.section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){.section{padding:3rem 3rem}.section.is-medium{padding:9rem 4.5rem}.section.is-large{padding:18rem 6rem}}.footer{background-color:#fafafa;padding:3rem 1.5rem 6rem}h1 .docs-heading-anchor,h1 .docs-heading-anchor:hover,h1 .docs-heading-anchor:visited,h2 .docs-heading-anchor,h2 .docs-heading-anchor:hover,h2 .docs-heading-anchor:visited,h3 .docs-heading-anchor,h3 .docs-heading-anchor:hover,h3 .docs-heading-anchor:visited,h4 .docs-heading-anchor,h4 .docs-heading-anchor:hover,h4 .docs-heading-anchor:visited,h5 .docs-heading-anchor,h5 .docs-heading-anchor:hover,h5 .docs-heading-anchor:visited,h6 .docs-heading-anchor,h6 .docs-heading-anchor:hover,h6 .docs-heading-anchor:visited{color:#222}h1 .docs-heading-anchor-permalink,h2 .docs-heading-anchor-permalink,h3 .docs-heading-anchor-permalink,h4 .docs-heading-anchor-permalink,h5 .docs-heading-anchor-permalink,h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}h1 .docs-heading-anchor-permalink::before,h2 .docs-heading-anchor-permalink::before,h3 .docs-heading-anchor-permalink::before,h4 .docs-heading-anchor-permalink::before,h5 .docs-heading-anchor-permalink::before,h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}h1:hover .docs-heading-anchor-permalink,h2:hover .docs-heading-anchor-permalink,h3:hover .docs-heading-anchor-permalink,h4:hover .docs-heading-anchor-permalink,h5:hover .docs-heading-anchor-permalink,h6:hover .docs-heading-anchor-permalink{visibility:visible}.docs-dark-only{display:none !important}pre{position:relative;overflow:hidden}pre code,pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}pre code:first-of-type,pre code.hljs:first-of-type{padding-top:0.5rem !important}pre code:last-of-type,pre code.hljs:last-of-type{padding-bottom:0.5rem !important}pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#222;cursor:pointer;text-align:center}pre .copy-button:focus,pre .copy-button:hover{opacity:1;background:rgba(34,34,34,0.1);color:#2e63b8}pre .copy-button.success{color:#259a12;opacity:1}pre .copy-button.error{color:#cb3c33;opacity:1}pre:hover .copy-button{opacity:1}.admonition{background-color:#b5b5b5;border-style:solid;border-width:1px;border-color:#363636;border-radius:4px;font-size:1rem}.admonition strong{color:currentColor}.admonition.is-small,#documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}.admonition.is-medium{font-size:1.25rem}.admonition.is-large{font-size:1.5rem}.admonition.is-default{background-color:#b5b5b5;border-color:#363636}.admonition.is-default>.admonition-header{background-color:#363636;color:#fff}.admonition.is-default>.admonition-body{color:#fff}.admonition.is-info{background-color:#def0fc;border-color:#209cee}.admonition.is-info>.admonition-header{background-color:#209cee;color:#fff}.admonition.is-info>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-success{background-color:#bdf4d1;border-color:#22c35b}.admonition.is-success>.admonition-header{background-color:#22c35b;color:#fff}.admonition.is-success>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-warning{background-color:#fff3c5;border-color:#ffdd57}.admonition.is-warning>.admonition-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.admonition.is-warning>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-danger{background-color:#ffaba7;border-color:#da0b00}.admonition.is-danger>.admonition-header{background-color:#da0b00;color:#fff}.admonition.is-danger>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-compat{background-color:#bdeff5;border-color:#1db5c9}.admonition.is-compat>.admonition-header{background-color:#1db5c9;color:#fff}.admonition.is-compat>.admonition-body{color:rgba(0,0,0,0.7)}.admonition-header{color:#fff;background-color:#363636;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}details.admonition.is-details>.admonition-header{list-style:none}details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}.admonition-body{color:#222;padding:0.5rem .75rem}.admonition-body pre{background-color:#f5f5f5}.admonition-body code{background-color:rgba(0,0,0,0.05)}.docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #dbdbdb;box-shadow:2px 2px 3px rgba(10,10,10,0.1);max-width:100%}.docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#f5f5f5;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #dbdbdb;overflow:auto}.docstring>header code{background-color:transparent}.docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}.docstring>header .docstring-binding{margin-right:0.3em}.docstring>header .docstring-category{margin-left:0.3em}.docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #dbdbdb}.docstring>section:last-child{border-bottom:none}.docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}.docstring>section>a.docs-sourcelink:focus{opacity:1 !important}.docstring:hover>section>a.docs-sourcelink{opacity:0.2}.docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}.docstring>section:hover a.docs-sourcelink{opacity:1}.documenter-example-output{background-color:#fff}.outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#ffaba7;color:rgba(0,0,0,0.7);border-bottom:3px solid #da0b00;padding:10px 35px;text-align:center;font-size:15px}.outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}.outdated-warning-overlay a{color:#2e63b8}.outdated-warning-overlay a:hover{color:#363636}.content pre{border:1px solid #dbdbdb}.content code{font-weight:inherit}.content a code{color:#2e63b8}.content h1 code,.content h2 code,.content h3 code,.content h4 code,.content h5 code,.content h6 code{color:#222}.content table{display:block;width:initial;max-width:100%;overflow-x:auto}.content blockquote>ul:first-child,.content blockquote>ol:first-child,.content .admonition-body>ul:first-child,.content .admonition-body>ol:first-child{margin-top:0}pre,code{font-variant-ligatures:no-contextual}.breadcrumb a.is-disabled{cursor:default;pointer-events:none}.breadcrumb a.is-disabled,.breadcrumb a.is-disabled:hover{color:#222}.hljs{background:initial !important}.katex .katex-mathml{top:0;right:0}.katex-display,mjx-container,.MathJax_Display{margin:0.5em 0 !important}html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}li.no-marker{list-style:none}#documenter .docs-main>article{overflow-wrap:break-word}#documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){#documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){#documenter .docs-main{width:100%}#documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}#documenter .docs-main>header,#documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}#documenter .docs-main header.docs-navbar{background-color:#fff;border-bottom:1px solid #dbdbdb;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}#documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}#documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}#documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}#documenter .docs-main header.docs-navbar .docs-right .docs-icon,#documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}#documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}#documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}#documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #bbb;transition-duration:0.7s;-webkit-transition-duration:0.7s}#documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}#documenter .docs-main section.footnotes{border-top:1px solid #dbdbdb}#documenter .docs-main section.footnotes li .tag:first-child,#documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,#documenter .docs-main section.footnotes li .content kbd:first-child,.content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}#documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #dbdbdb;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){#documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}#documenter .docs-main .docs-footer .docs-footer-nextpage,#documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}#documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}#documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}#documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}#documenter .docs-sidebar{display:flex;flex-direction:column;color:#0a0a0a;background-color:#f5f5f5;border-right:1px solid #dbdbdb;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}#documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #bbb}@media screen and (min-width: 1056px){#documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){#documenter .docs-sidebar{left:0;top:0}}#documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}#documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}#documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}#documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}#documenter .docs-sidebar .docs-package-name a,#documenter .docs-sidebar .docs-package-name a:hover{color:#0a0a0a}#documenter .docs-sidebar .docs-version-selector{border-top:1px solid #dbdbdb;display:none;padding:0.5rem}#documenter .docs-sidebar .docs-version-selector.visible{display:flex}#documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #dbdbdb;padding-bottom:1.5rem}#documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}#documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}#documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}#documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}#documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}#documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}#documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}#documenter .docs-sidebar ul.docs-menu .tocitem,#documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#0a0a0a;background:#f5f5f5}#documenter .docs-sidebar ul.docs-menu a.tocitem:hover,#documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#0a0a0a;background-color:#ebebeb}#documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #dbdbdb;border-bottom:1px solid #dbdbdb;background-color:#fff}#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#fff;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#ebebeb;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}#documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}#documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}#documenter .docs-sidebar form.docs-search>input{width:14.4rem}#documenter .docs-sidebar #documenter-search-query{color:#707070;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){#documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#ccc}}@media screen and (max-width: 1055px){#documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#ccc}}kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(0,0,0,0.6);box-shadow:0 2px 0 1px rgba(0,0,0,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}.search-min-width-50{min-width:50%}.search-min-height-100{min-height:100%}.search-modal-card-body{max-height:calc(100vh - 15rem)}.search-result-link{border-radius:0.7em;transition:all 300ms}.search-result-link:hover,.search-result-link:focus{background-color:rgba(0,128,128,0.1)}.search-result-link .property-search-result-badge,.search-result-link .search-filter{transition:all 300ms}.property-search-result-badge,.search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}.search-result-link:hover .property-search-result-badge,.search-result-link:hover .search-filter,.search-result-link:focus .property-search-result-badge,.search-result-link:focus .search-filter{color:#f1f5f9;background-color:#333}.search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}.search-filter:hover,.search-filter:focus{color:#333}.search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}.search-filter-selected:hover,.search-filter-selected:focus{color:#f5f5f5}.search-result-highlight{background-color:#ffdd57;color:black}.search-divider{border-bottom:1px solid #dbdbdb}.search-result-title{width:85%;color:#333}.search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}#search-modal .modal-card-body::-webkit-scrollbar,#search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}#search-modal .modal-card-body::-webkit-scrollbar-thumb,#search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}#search-modal .modal-card-body::-webkit-scrollbar-track,#search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}.w-100{width:100%}.gap-2{gap:0.5rem}.gap-4{gap:1rem}.gap-8{gap:2rem}.ansi span.sgr1{font-weight:bolder}.ansi span.sgr2{font-weight:lighter}.ansi span.sgr3{font-style:italic}.ansi span.sgr4{text-decoration:underline}.ansi span.sgr7{color:#fff;background-color:#222}.ansi span.sgr8{color:transparent}.ansi span.sgr8 span{color:transparent}.ansi span.sgr9{text-decoration:line-through}.ansi span.sgr30{color:#242424}.ansi span.sgr31{color:#a7201f}.ansi span.sgr32{color:#066f00}.ansi span.sgr33{color:#856b00}.ansi span.sgr34{color:#2149b0}.ansi span.sgr35{color:#7d4498}.ansi span.sgr36{color:#007989}.ansi span.sgr37{color:gray}.ansi span.sgr40{background-color:#242424}.ansi span.sgr41{background-color:#a7201f}.ansi span.sgr42{background-color:#066f00}.ansi span.sgr43{background-color:#856b00}.ansi span.sgr44{background-color:#2149b0}.ansi span.sgr45{background-color:#7d4498}.ansi span.sgr46{background-color:#007989}.ansi span.sgr47{background-color:gray}.ansi span.sgr90{color:#616161}.ansi span.sgr91{color:#cb3c33}.ansi span.sgr92{color:#0e8300}.ansi span.sgr93{color:#a98800}.ansi span.sgr94{color:#3c5dcd}.ansi span.sgr95{color:#9256af}.ansi span.sgr96{color:#008fa3}.ansi span.sgr97{color:#f5f5f5}.ansi span.sgr100{background-color:#616161}.ansi span.sgr101{background-color:#cb3c33}.ansi span.sgr102{background-color:#0e8300}.ansi span.sgr103{background-color:#a98800}.ansi span.sgr104{background-color:#3c5dcd}.ansi span.sgr105{background-color:#9256af}.ansi span.sgr106{background-color:#008fa3}.ansi span.sgr107{background-color:#f5f5f5}code.language-julia-repl>span.hljs-meta{color:#066f00;font-weight:bolder}/*! + Theme: Default + Description: Original highlight.js style + Author: (c) Ivan Sagalaev + Maintainer: @highlightjs/core-team + Website: https://highlightjs.org/ + License: see project LICENSE + Touched: 2021 +*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{background:#F3F3F3;color:#444}.hljs-comment{color:#697070}.hljs-tag,.hljs-punctuation{color:#444a}.hljs-tag .hljs-name,.hljs-tag .hljs-attr{color:#444}.hljs-keyword,.hljs-attribute,.hljs-selector-tag,.hljs-meta .hljs-keyword,.hljs-doctag,.hljs-name{font-weight:bold}.hljs-type,.hljs-string,.hljs-number,.hljs-selector-id,.hljs-selector-class,.hljs-quote,.hljs-template-tag,.hljs-deletion{color:#880000}.hljs-title,.hljs-section{color:#880000;font-weight:bold}.hljs-regexp,.hljs-symbol,.hljs-variable,.hljs-template-variable,.hljs-link,.hljs-selector-attr,.hljs-operator,.hljs-selector-pseudo{color:#ab5656}.hljs-literal{color:#695}.hljs-built_in,.hljs-bullet,.hljs-code,.hljs-addition{color:#397300}.hljs-meta{color:#1f7199}.hljs-meta .hljs-string{color:#38a}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold}.gap-4{gap:1rem} diff --git a/v2.16.1/assets/themeswap.js b/v2.16.1/assets/themeswap.js new file mode 100644 index 000000000..9f5eebe6a --- /dev/null +++ b/v2.16.1/assets/themeswap.js @@ -0,0 +1,84 @@ +// Small function to quickly swap out themes. Gets put into the tag.. +function set_theme_from_local_storage() { + // Initialize the theme to null, which means default + var theme = null; + // If the browser supports the localstorage and is not disabled then try to get the + // documenter theme + if (window.localStorage != null) { + // Get the user-picked theme from localStorage. May be `null`, which means the default + // theme. + theme = window.localStorage.getItem("documenter-theme"); + } + // Check if the users preference is for dark color scheme + var darkPreference = + window.matchMedia("(prefers-color-scheme: dark)").matches === true; + // Initialize a few variables for the loop: + // + // - active: will contain the index of the theme that should be active. Note that there + // is no guarantee that localStorage contains sane values. If `active` stays `null` + // we either could not find the theme or it is the default (primary) theme anyway. + // Either way, we then need to stick to the primary theme. + // + // - disabled: style sheets that should be disabled (i.e. all the theme style sheets + // that are not the currently active theme) + var active = null; + var disabled = []; + var primaryLightTheme = null; + var primaryDarkTheme = null; + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // To distinguish the default (primary) theme, it needs to have the data-theme-primary + // attribute set. + if (ss.ownerNode.getAttribute("data-theme-primary") !== null) { + primaryLightTheme = themename; + } + // Check if the theme is primary dark theme so that we could store its name in darkTheme + if (ss.ownerNode.getAttribute("data-theme-primary-dark") !== null) { + primaryDarkTheme = themename; + } + // If we find a matching theme (and it's not the default), we'll set active to non-null + if (themename === theme) active = i; + // Store the style sheets of inactive themes so that we could disable them + if (themename !== theme) disabled.push(ss); + } + var activeTheme = null; + if (active !== null) { + // If we did find an active theme, we'll (1) add the theme--$(theme) class to + document.getElementsByTagName("html")[0].className = "theme--" + theme; + activeTheme = theme; + } else { + // If we did _not_ find an active theme, then we need to fall back to the primary theme + // which can either be dark or light, depending on the user's OS preference. + var activeTheme = darkPreference ? primaryDarkTheme : primaryLightTheme; + // In case it somehow happens that the relevant primary theme was not found in the + // preceding loop, we abort without doing anything. + if (activeTheme === null) { + console.error("Unable to determine primary theme."); + return; + } + // When switching to the primary light theme, then we must not have a class name + // for the tag. That's only for non-primary or the primary dark theme. + if (darkPreference) { + document.getElementsByTagName("html")[0].className = + "theme--" + activeTheme; + } else { + document.getElementsByTagName("html")[0].className = ""; + } + } + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // we'll disable all the stylesheets, except for the active one + ss.disabled = !(themename == activeTheme); + } +} +set_theme_from_local_storage(); diff --git a/v2.16.1/assets/warner.js b/v2.16.1/assets/warner.js new file mode 100644 index 000000000..3f6f5d008 --- /dev/null +++ b/v2.16.1/assets/warner.js @@ -0,0 +1,52 @@ +function maybeAddWarning() { + // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE + // in siteinfo.js. + // If either of these are undefined something went horribly wrong, so we abort. + if ( + window.DOCUMENTER_NEWEST === undefined || + window.DOCUMENTER_CURRENT_VERSION === undefined || + window.DOCUMENTER_STABLE === undefined + ) { + return; + } + + // Current version is not a version number, so we can't tell if it's the newest version. Abort. + if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) { + return; + } + + // Current version is newest version, so no need to add a warning. + if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) { + return; + } + + // Add a noindex meta tag (unless one exists) so that search engines don't index this version of the docs. + if (document.body.querySelector('meta[name="robots"]') === null) { + const meta = document.createElement("meta"); + meta.name = "robots"; + meta.content = "noindex"; + + document.getElementsByTagName("head")[0].appendChild(meta); + } + + const div = document.createElement("div"); + div.classList.add("outdated-warning-overlay"); + const closer = document.createElement("button"); + closer.classList.add("outdated-warning-closer", "delete"); + closer.addEventListener("click", function () { + document.body.removeChild(div); + }); + const href = window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE; + div.innerHTML = + 'This documentation is not for the latest stable release, but for either the development version or an older release.
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/v2.16.1/contributing/new-documentation/index.html b/v2.16.1/contributing/new-documentation/index.html new file mode 100644 index 000000000..bca06084d --- /dev/null +++ b/v2.16.1/contributing/new-documentation/index.html @@ -0,0 +1,2 @@ + +Contributing to the documentation · RxInfer.jl
GitHub

Contributing to the documentation

Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:

  1. Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.

  2. Identify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.

  3. Fork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.

  4. Make Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.

  5. Submit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.

  6. Review and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.

  7. Merging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!

By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.

Use LiveServer.jl

LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.

To use LiveServer.jl, simply follow these steps[1]

  • Make sure to import the required packages 
julia> using LiveServer, Documenter
  • After importing the required packages, you can start the live server with the following command:
julia> servedocs()
  • 1Make sure to install the LiveServer and Documenter in your current working environment.
diff --git a/v2.16.1/contributing/new-example/index.html b/v2.16.1/contributing/new-example/index.html new file mode 100644 index 000000000..3ba8595a3 --- /dev/null +++ b/v2.16.1/contributing/new-example/index.html @@ -0,0 +1,7 @@ + +Contributing to the examples · RxInfer.jl
GitHub

Contributing to the examples

We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.

In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/"subcategory" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.

After preparing the new example it is necessary to modify the examples/.meta.jl file.

  1. Make sure that the very first cell of the notebook contains ONLY # <title> in it and has the markdown cell type. This is important for generating links in our documentation.
  2. The path option must be set to a local path in a category sub-folder.
  3. The text in the description option will be used on the Examples page in the documentation.
  4. Set category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).
  5. Please do no use Overview as a name for the new example, the title Overview is reserved.
  6. Use the following template for equations, note that $$ and both \begin and \end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.
$$\begin{aligned}
+      <latex equations here>
+\end{aligned}$$
  1. When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.
  2. Notebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.
variable = 0
+for i in 1:10
+    global variable = variable + i
+end
  1. All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.
  2. All plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.
Note

Please avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.

Note

Use make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.

diff --git a/v2.16.1/contributing/new-package/index.html b/v2.16.1/contributing/new-package/index.html new file mode 100644 index 000000000..852765419 --- /dev/null +++ b/v2.16.1/contributing/new-package/index.html @@ -0,0 +1,28 @@ + +Contributing to the dependencies · RxInfer.jl
GitHub

Contributing to the dependencies

Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.

The benefits of small packages for the ecosystem

In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:

  1. Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.

  2. Collaboration: Teams can work on different packages concurrently, speeding up development.

  3. Version Control: Precise versioning and fewer dependencies lead to leaner projects.

  4. Performance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.

  5. Flexibility: Developers can select and customize packages for their needs.

  6. Community: Smaller packages attract contributors, fostering collaboration and faster feedback.

In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.

Use PkgTemplates

PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:

julia> using PkgTemplates
+
+julia> USER = "your github user name" # Use `reactivebayes` if developing within the ReactiveBayes organisation
+
+julia> template = Template(
+    user = USER, 
+    plugins = [
+        CompatHelper(), 
+        ProjectFile(), 
+        SrcDir(), 
+        Git(), 
+        License(), 
+        Readme(), 
+        Tests(), 
+        GitHubActions(), 
+        Codecov(), 
+        Documenter{GitHubActions}(), 
+        Formatter(style="blue"), 
+        BlueStyleBadge(), 
+        PkgEvalBadge()
+])
+
+julia> template("MyNewCoolPackage")

This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.

  • Adjust the minimum supported version of Julia

After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:

[compat]
+julia = "1.9.2"

Try to be conservative and set as low version of Julia as possible.

  • Adjust the authors of the package

The authors field is present in the Project.toml, e.g 

authors = ["John Wick <john.wick@continental.com>", ...]

  • Add requires dependencies and their [compat] bounds

To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:

julia --project=.

or 

julia
julia> ] activate .

Then, add dependencies like this:

julia> ] add SomeCoolDependency, SomeOtherCoolDependency

For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:

[compat]
+julia = "1.9"
+SomeCoolDependency = "0.19.2"
+SomeOtherCoolDependency = "1.3.12"

For more details on compat bounds, check the official Julia documentation.

Adjust README.md

The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.

Note

Some badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.

Write code and tests

The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.

Simplify Testing with ReTestItems

You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.

Write code and the documentation

Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):

julia --project=docs docs/make.jl

For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.

Hosting Documentation with GitHub Actions

The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.

Enable GitHub Pages in Repository Settings

The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:

  1. Navigate to the GitHub Pages settings of your repository.
  2. Choose the Deploy from a branch option.
  3. Select the gh-pages branch.
diff --git a/v2.16.1/contributing/new-release/index.html b/v2.16.1/contributing/new-release/index.html new file mode 100644 index 000000000..b83d1ca3b --- /dev/null +++ b/v2.16.1/contributing/new-release/index.html @@ -0,0 +1,2 @@ + +Publishing a new release · RxInfer.jl
GitHub

Publishing a new release

Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.

Start the release process

In order to start the release process a person with the associated permissions should:

  • Open a commit page on GitHub
  • Write the @JuliaRegistrator register comment for the commit:

Release comment

The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.

diff --git a/v2.16.1/contributing/overview/index.html b/v2.16.1/contributing/overview/index.html new file mode 100644 index 000000000..0e456d1f3 --- /dev/null +++ b/v2.16.1/contributing/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Contributing

We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.

Reporting bugs

We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.

Nightly Julia status

The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.

PkgEval

Suggesting features

We welcome new feature proposals. However, before submitting a feature request, consider a few things:

  • Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.
  • If you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.

Contributing code

Installing RxInfer

We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:

] dev git@github.com:your_username/RxInfer.jl.git

The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.

Note

It is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.

Core dependencies

RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.

Committing code

We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.

Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well.

Note

Use make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.

Style conventions

We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:

  • Use 4 spaces for indentation
  • Type names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..
  • Function names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..
  • Variable names and function arguments use snake_case
  • The name of a method that modifies its argument(s) must end in !
Note

RxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.

Unit tests

We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.

All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.

The tests can be evaluated by running following command in the Julia REPL:

] test RxInfer

In addition tests can be evaluated by running following command in the RxInfer root directory:

make test
Note

Use make devtest to use local dev-ed versions of the core packages.

Makefile

RxInfer.jl uses Makefile for most common operations:

  • make help: Shows help snippet
  • make test: Run tests, supports extra arguments
    • make test test_args="distributions:normal_mean_variance" would run tests only from distributions/test_normal_mean_variance.jl
    • make test test_args="distributions:normal_mean_variance models:lgssm" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl
    • make test dev=true would run tests while using dev-ed versions of core packages
  • make devtest: Alias for the make test dev=true ...
  • make docs: Compile documentation
  • make devdocs: Same as make docs, but uses dev-ed versions of core packages
  • make examples: Run all examples and put them in the docs/ folder if successfull
  • make devexamples: Same as make examples, but uses dev-ed versions of core packages
  • make lint: Check codestyle
  • make format: Check and fix codestyle
Note

Core packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.

diff --git a/v2.16.1/examples/advanced_examples/Active Inference Mountain car/index.html b/v2.16.1/examples/advanced_examples/Active Inference Mountain car/index.html new file mode 100644 index 000000000..767f8c6c2 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Active Inference Mountain car/index.html @@ -0,0 +1,286 @@ + +Active Inference Mountain car · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Active Inference Mountain car

import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.

The environmental process of the mountain

Firstly, we specify the environmental process according to Ueltzhoeffer (2017) "Deep active inference". This process shows how the environment evolves after interacting with the agent.

Particularly, let's denote $z_t = (\phi_t, \,\,\dot{\phi_t})$ as the environmental state depending on the position $\phi_t$ and velocity $\dot{\phi_t}$ of the car; $a_t$ as the action of the environment on the car. Then the evolution of the state is described as follows

\[\begin{aligned} +\dot{\phi_t} &= \dot{\phi}_{t-1} + F_g(\phi_{t-1}) + F_f(\dot{\phi}_{t-1}) + F_a(a_t)\\ +\phi_t &= \phi_{t-1} + \dot{\phi_t} +\end{aligned}\]

where $F_g(\phi_{t-1})$ is the gravitational force of the hill landscape that depends on the car's position

\[F_g(\phi) = \begin{cases} + -0.05(2\phi + 1) , \, & \mathrm{if} \, \phi < 0 \\ + -0.05 \left[(1 + 5\phi^2)^{-\frac{1}{2}} + \phi^2 (1 + 5\phi^2)^{-\frac{3}{2}} + \frac{1}{16}\phi^4 \right], \, & \mathrm{otherwise} +\end{cases}\]

\[F_f(\dot{\phi})\]

is the friction on the car defined through the car's velocity $F_f(\dot{\phi}) = -0.1 \, \dot{\phi}\,$ and $F_a(a)$ is the engine force $F_a(a) = 0.04 \,\tanh(a).$ Since the car is on low battery, we use the $\tanh(\cdot)$ function to limit the engine force to the interval [-0.04, 0.04].

In the cell below, the create_physics function defines forces $F_g,\, F_f,\, F_a\,$; and the create_world function defines the environmental process of the mountain.

import HypergeometricFunctions: _₂F₁
+
+function create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)
+    # Engine force as function of action
+    Fa = (a::Real) -> engine_force_limit * tanh(a) 
+
+    # Friction force as function of velocity
+    Ff = (y_dot::Real) -> -friction_coefficient * y_dot 
+    
+    # Gravitational force (horizontal component) as function of position
+    Fg = (y::Real) -> begin
+        if y < 0
+            0.05*(-2*y - 1)
+        else
+            0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)
+        end
+    end
+    
+    # The height of the landscape as a function of the horizontal coordinate
+    height = (x::Float64) -> begin
+        if x < 0
+            h = x^2 + x
+        else
+            h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80
+        end
+        return 0.05*h
+    end
+
+    return (Fa, Ff, Fg,height)
+end;
+
+function create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)
+
+    y_t_min = initial_position
+    y_dot_t_min = initial_velocity
+    
+    y_t = y_t_min
+    y_dot_t = y_dot_t_min
+    
+    execute = (a_t::Float64) -> begin
+        # Compute next state
+        y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)
+        y_t = y_t_min + y_dot_t
+    
+        # Reset state for next step
+        y_t_min = y_t
+        y_dot_t_min = y_dot_t
+    end
+    
+    observe = () -> begin 
+        return [y_t, y_dot_t]
+    end
+        
+    return (execute, observe)
+end
create_world (generic function with 1 method)

Let's visualize the mountain landscape and the situation of the car. 

engine_force_limit   = 0.04
+friction_coefficient = 0.1
+
+Fa, Ff, Fg, height = create_physics(
+    engine_force_limit = engine_force_limit,
+    friction_coefficient = friction_coefficient
+);
+initial_position = -0.5
+initial_velocity = 0.0
+
+x_target = [0.5, 0.0] 
+
+valley_x = range(-2, 2, length=400)
+valley_y = [ height(xs) for xs in valley_x ]
+plot(valley_x, valley_y, title = "Mountain valley", label = "Landscape", color = "black")
+scatter!([ initial_position ], [ height(initial_position) ], label="initial car position")   
+scatter!([x_target[1]], [height(x_target[1])], label="camping site")

Naive approach

Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.

N_naive  = 100 # Total simulation time
+pi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only
+
+# Let there be a world
+(execute_naive, observe_naive) = create_world(; 
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+);
+
+y_naive = Vector{Vector{Float64}}(undef, N_naive)
+for t = 1:N_naive
+    execute_naive(pi_naive[t]) # Execute environmental process
+    y_naive[t] = observe_naive() # Observe external states
+end
+
+animation_naive = @animate for i in 1:N_naive
+    plot(valley_x, valley_y, title = "Naive policy", label = "Landscape", color = "black", size = (800, 400))
+    scatter!([y_naive[i][1]], [height(y_naive[i][1])], label="car")
+    scatter!([x_target[1]], [height(x_target[1])], label="goal")   
+end
+
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_naive, "../pics/ai-mountain-car-naive.gif", fps = 24, show_msg = false);

They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.

Active inference approach

Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.

We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows

\[\begin{aligned} +p_t(x,s,u) \propto p(s_{t-1}) \prod_{k=t}^{t+T} p(x_k \mid s_k) \, p(s_k \mid s_{k-1},u_k) \, p(u_k) \, p'(x_k) \nonumber +\end{aligned}\]

where the factors are defined as

\[p'(x_k) = \mathcal{N}(x_k \mid x_{goal},\,V_{goal}) , \quad (\mathrm{target})\]

\[p(s_k \mid s_{k-1},u_k) = \mathcal{N}(s_k \mid \tilde{g}(s_{k-1})+h(u_k),\,\gamma^{-1}) , \quad (\mathrm{state \,\, transition})\]

\[p(x_k \mid s_k) = \mathcal{N}(x_k \mid s_k,\,\theta), \quad (\mathrm{observation})\]

\[p(u_k) = \mathcal{N}(u_k \mid m_u,\,V_u), \quad (\mathrm{control})\]

\[p(s_{t-1}) = \mathcal{N}(s_{t-1} \mid m_{t-1},\,V_{t-1}), \quad (\mathrm{previous \,\, state})\]

where

  • \[x\]

    denotes observations of the agent after interacting with the environment;

  • \[s_t = (s_t,\dot{s_t})\]

    is the state of the car embodying its position and velocity;

  • \[u_t\]

    denotes the control state of the agent;

  • \[h(\cdot)\]

    is the $\tanh(\cdot)$ function modeling engine control;

  • \[\tilde{g}(\cdot)\]

    executes a linear approximation of equations (1) and (2):

\[\begin{aligned} +\dot{s_t} &= \dot{s}_{t-1} + F_g(s_{t-1}) + F_f(\dot{s}_{t-1})\\ +s_t &= s_{t-1} + \dot{s_t} +\end{aligned}\]

In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.

@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)
+    
+    # Transition function modeling transition due to gravity and friction
+    g = (s_t_min::AbstractVector) -> begin 
+        s_t = similar(s_t_min) # Next state
+        s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity
+        s_t[1] = s_t_min[1] + s_t[2] # Update position
+        return s_t
+    end
+    
+    # Function for modeling engine control
+    h = (u::AbstractVector) -> [0.0, Fa(u[1])] 
+    
+    # Inverse engine force, from change in state to corresponding engine force
+    h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] 
+    
+    # Internal model perameters
+    Gamma = 1e4*diageye(2) # Transition precision
+    Theta = 1e-4*diageye(2) # Observation variance
+    
+    m_s_t_min = datavar(Vector{Float64})
+    V_s_t_min = datavar(Matrix{Float64})
+
+    s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)
+    s_k_min = s_t_min
+    
+    m_u = datavar(Vector{Float64}, T)
+    V_u = datavar(Matrix{Float64}, T)
+    
+    m_x = datavar(Vector{Float64}, T)
+    V_x = datavar(Matrix{Float64}, T)
+    
+    u = randomvar(T)
+    s = randomvar(T)
+    x = randomvar(T)
+    
+    u_h_k = randomvar(T)
+    s_g_k = randomvar(T)
+    u_s_sum = randomvar(T)
+    
+    for k in 1:T
+        u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])
+        u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }
+        s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }
+        u_s_sum[k] ~ s_g_k[k] + u_h_k[k]
+        s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)
+        x[k] ~ MvNormal(mean = s[k], cov = Theta)
+        x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal
+        s_k_min = s[k]
+    end
+    
+    return (s, )
+end

After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.

  1. Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time $t$ and gets $T$ observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next $T$ time step.
  2. Infer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state $s_t$ and control $u_t$, i.e. $p(s_t\mid x_t)$ and $p(u_t\mid x_t)$.
  3. Slide: After updating its internal belief, the agent moves to the next time step and uses the inferred action $u_t$ in the previous time step to interact with the environment.

In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:

  • The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next $T$ positions based on the current action. These two function implement the Act-Execute-Observe phase.
  • The compute function infers the policy (which is a set of actions for the next $T$ time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.
  • The slide function implements the Slide phase, which moves the agent internal model to the next time step.
# We are going to use some private functionality from ReactiveMP, 
+# in the future we should expose a proper API for this
+import RxInfer.ReactiveMP: getrecent, messageout
+
+function create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)
+    Epsilon = fill(huge, 1, 1)                # Control prior variance
+    m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors
+    V_u = Matrix{Float64}[ Epsilon for k=1:T ]
+
+    Sigma    = 1e-4*diageye(2) # Goal prior variance
+    m_x      = [zeros(2) for k=1:T]
+    V_x      = [huge*diageye(2) for k=1:T]
+    V_x[end] = Sigma # Set prior to reach goal at t=T
+
+    # Set initial brain state prior
+    m_s_t_min = [initial_position, initial_velocity] 
+    V_s_t_min = tiny * diageye(2)
+    
+    # Set current inference results
+    result = nothing
+
+    # The `infer` function is the heart of the agent
+    # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing
+    compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin
+        m_u[1] = [ upsilon_t ] # Register action with the generative model
+        V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action
+
+        m_x[1] = y_hat_t # Register observation with the generative model
+        V_x[1] = tiny*diageye(2) # Clamp goal prior to observation
+
+        data = Dict(:m_u       => m_u, 
+                    :V_u       => V_u, 
+                    :m_x       => m_x, 
+                    :V_x       => V_x,
+                    :m_s_t_min => m_s_t_min,
+                    :V_s_t_min => V_s_t_min)
+        
+        model  = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) 
+        result = infer(model = model, data = data)
+    end
+    
+    # The `act` function returns the inferred best possible action
+    act = () -> begin
+        if result !== nothing
+            return mode(result.posteriors[:u][2])[1]
+        else
+            return 0.0 # Without inference result we return some 'random' action
+        end
+    end
+    
+    # The `future` function returns the inferred future states
+    future = () -> begin 
+        if result !== nothing 
+            return getindex.(mode.(result.posteriors[:s]), 1)
+        else
+            return zeros(T)
+        end
+    end
+
+    # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step
+    # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`
+    slide = () -> begin
+        (s, ) = result.returnval
+        
+        slide_msg_idx = 3 # This index is model dependend
+        (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))
+
+        m_u = circshift(m_u, -1)
+        m_u[end] = [0.0]
+        V_u = circshift(V_u, -1)
+        V_u[end] = Epsilon
+
+        m_x = circshift(m_x, -1)
+        m_x[end] = x_target
+        V_x = circshift(V_x, -1)
+        V_x[end] = Sigma
+    end
+
+    return (compute, act, slide, future)    
+end
create_agent (generic function with 1 method)

Now it's time to see if we can help our friends arrive at the camping site by midnight?

(execute_ai, observe_ai) = create_world(
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+) # Let there be a world
+
+T_ai = 50
+
+(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent
+    T  = T_ai, 
+    Fa = Fa,
+    Fg = Fg, 
+    Ff = Ff, 
+    engine_force_limit = engine_force_limit,
+    x_target = x_target,
+    initial_position = initial_position,
+    initial_velocity = initial_velocity
+) 
+
+N_ai = 100
+
+# Step through experimental protocol
+agent_a = Vector{Float64}(undef, N_ai) # Actions
+agent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future
+agent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations
+
+for t=1:N_ai
+    agent_a[t] = act_ai()               # Invoke an action from the agent
+    agent_f[t] = future_ai()            # Fetch the predicted future states
+    execute_ai(agent_a[t])              # The action influences hidden external states
+    agent_x[t] = observe_ai()           # Observe the current environmental outcome (update p)
+    compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)
+    slide_ai()                          # Prepare for next iteration
+end
+
+animation_ai = @animate for i in 1:N_ai
+    # pls - plot landscape
+    pls = plot(valley_x, valley_y, title = "Active inference results", label = "Landscape", color = "black")
+    pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label="car")
+    pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label="goal")   
+    pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = "Predicted future", alpha = map(i -> 0.5 / i, 1:T_ai))
+    
+    # pef - plot engine force
+    pef = plot(Fa.(agent_a[1:i]), title = "Engine force (agents actions)", xlim = (0, N_ai), ylim = (-0.05, 0.05))
+    
+    plot(pls, pef, size = (800, 400))
+end
+    
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_ai, "../pics/ai-mountain-car-ai.gif", fps = 24, show_msg = false);

Voila! The car now is able to reach the camping site with a smart strategy.

The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.

Now our friends can enjoy their trip at the camping site!.

Reference

We refer reader to the Thijs van de Laar (2019) "Simulating active inference processes by message passing" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) "Deep active inference".

diff --git a/v2.16.1/examples/advanced_examples/Advanced Tutorial/index.html b/v2.16.1/examples/advanced_examples/Advanced Tutorial/index.html new file mode 100644 index 000000000..c9fb02ad0 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Advanced Tutorial/index.html @@ -0,0 +1,416 @@ + +Advanced Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Advanced Tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.

This tutorial is also available in the documentation.

General model specification syntax

We use the @model macro from the RxInfer.jl package to create a probabilistic model $p(s, y)$ and we also specify extra constraints on the variational family of distributions $\mathcal{Q}$, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.

# the `@model` macro accepts a regular Julia function
+@model function test_model1(s_mean, s_precision)
+    
+    # We use the `randomvar` function to create 
+    # a random variable in our model
+    s = randomvar()
+    
+    # the `tilde` operator creates a functional dependency
+    # between variables in our model and can be read as 
+    # `sampled from` or `is modeled by`
+    s ~ Normal(mean = s_mean, precision = s_precision)
+    
+    # We use the `datavar` function to create 
+    # observed data variables in our models
+    # We also need to specify the type of our data 
+    # In this example it is `Float64`
+    y = datavar(Float64)
+    
+    y ~ Normal(mean = s, precision = 1.0)
+    
+    # It is possible to return something from the model specification (including variables and nodes)
+    return "Hello world"
+end

The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.

modelgenerator = test_model1(0.0, 1.0)
+
+model, returnval = create_model(modelgenerator)
(FactorGraphModel(), "Hello world")

The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.

RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as:

  • getnodes(): returns an array of factor nodes in a corresponding factor graph
  • getrandom(): returns an array of random variables in the model
  • getdata(): returns an array of data inputs in the model
  • getconstant(): returns an array of constant values in the model
getnodes(model)
FactorNodesCollection(nodes: 2)
getrandom(model) .|> name
1-element Vector{Symbol}:
+ :s
getdata(model) .|> name
1-element Vector{Symbol}:
+ :y
getconstant(model) .|> getconst
3-element Vector{Float64}:
+ 0.0
+ 1.0
+ 1.0

It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:

@model function test_model2(n)
+    
+    if n <= 1
+        error("`n` argument must be greater than one.")
+    end
+    
+    # `randomvar(n)` creates a dense sequence of 
+    # random variables
+    s = randomvar(n)
+    
+    # `datavar(Float64, n)` creates a dense sequence of 
+    # observed data variables of type `Float64`
+    y = datavar(Float64, n)
+    
+    s[1] ~ Normal(mean = 0.0, precision = 0.1)
+    y[1] ~ Normal(mean = s[1], precision = 1.0)
+    
+    for i in 2:n
+        s[i] ~ Normal(mean = s[i - 1], precision = 1.0)
+        y[i] ~ Normal(mean = s[i], precision = 1.0)
+    end
+    
+end
model, _ = create_model(test_model2(10));
# An amount of factor nodes in generated Factor Graph
+getnodes(model) |> length
20
# An amount of random variables
+getrandom(model) |> length
10
# An amount of data inputs
+getdata(model) |> length
10
# An amount of constant values
+getconstant(model) |> length
21

It is also possible to use complex expressions inside the functional dependency expressions

y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)

The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists

# s = randomvar() here is optional
+# `~` creates random variables automatically
+s ~ NormalMeanPrecision(0.0, 1.0)

An example model which will throw an error:

@model function error_model1()
+    s = 1.0
+    s ~ NormalMeanPrecision(0.0, 1.0)
+end

By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as

# Creates constant reference in a model with a prespecified value
+c = constvar(0.0)

An example:

@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)
+    
+    s = randomvar(n)
+    
+    y = datavar(Vector{Float64}, n)
+    
+    # Here we create constant references
+    # for constant matrices in our model 
+    # to make inference more memory efficient
+    cA = constvar(A)
+    cP = constvar(P)
+    cQ = constvar(Q)
+    
+    s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)
+    y[1] ~ MvNormal(mean = s[1], covariance = cQ)
+    
+    for i in 2:n
+        s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)
+        y[i] ~ MvNormal(mean = s[i], covariance = cQ)
+    end
+    
+end

The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:

@model function test_model()
+
+    # In this example `ynode` refers to the corresponding 
+    # `GaussianMeanVariance` node created in the factor graph
+    ynode, y ~ GaussianMeanVariance(0.0, 1.0)
+    
+    return ynode, y
+end

Probabilistic inference in RxInfer.jl

RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.

Observables

Observables are lazy push-based collections and they deliver their values over time.

# Timer that emits a new value every second and has an initial one second delay 
+observable = timer(300, 300)
TimerObservable(300, 300)

A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:

actor = (value) -> println(value)
+subscription1 = subscribe!(observable, actor)
TimerSubscription()
# We always need to unsubscribe from some observables
+unsubscribe!(subscription1)
# We can modify our observables
+modified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)
ProxyObservable(Int64, MapProxy(Int64))
subscription2 = subscribe!(modified, (value) -> println(value))
TimerSubscription()
unsubscribe!(subscription2)
@model function coin_toss_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+    
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    
+    # We assume that the outcome of each coin flip 
+    # is modeled by a Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+    
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during the inference step
+    return y, θ
+end

We can call the inference function to run inference in such model:

p = 0.75 # Bias of a coin
+
+dataset = float.(rand(Bernoulli(p), 500));
+
+result = infer(
+    model = coin_toss_model(length(dataset)),
+    data  = (y = dataset, )
+)
+
+println("Inferred bias: ", mean_var(result.posteriors[:θ]))
Inferred bias: (0.7347740667976425, 0.0003821198775672473)

We can see that the inferred bias is quite close to the actual value we used in the dataset generation.

The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions:

  • getmarginal(x): for a single random variable x
  • getmarginals(xs): for a dense sequence of random variables sx

Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.

_, (y, θ) = create_model(coin_toss_model(length(dataset)));
# As soon as we have a new value for the marginal posterior over the `θ` variable
+# we simply print the first two statistics of it
+θ_subscription = subscribe!(getmarginal(θ), (marginal) -> println("New update: mean(θ) = ", mean(marginal), ", std(θ) = ", std(marginal)));

To pass data to our model we use update! function

update!(y, dataset)
New update: mean(θ) = 0.7347740667976425, std(θ) = 0.019547886780090767
# It is necessary to always unsubscribe from running observables
+unsubscribe!(θ_subscription)
# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them
+# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing
+update!(y, dataset)

Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.

# the `keep` actor simply keeps all incoming updates in an internal storage, ordered
+θvalues = keep(Marginal)
KeepActor{Marginal}(Marginal[])
# `getmarginal` always emits last cached value as its first value
+subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=374.0, β=135.0))
subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
2-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=374.0, β=135.0))
+ Marginal(Beta{Float64}(α=374.0, β=135.0))
# the `buffer` actor keeps very last incoming update in an internal storage and can also store 
+# an array of updates for a sequence of random variables
+θbuffer = buffer(Marginal, 1)
BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=374.0, β=135.0))
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=374.0, β=135.0))

Reactive Online Inference

RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.

@model function online_coin_toss_model()
+    
+    # We create datavars for the prior 
+    # over `θ` variable
+    θ_a = datavar(Float64)
+    θ_b = datavar(Float64)
+    
+    θ ~ Beta(θ_a, θ_b)
+    
+    y = datavar(Float64)
+    y ~ Bernoulli(θ)
+
+end
autoupdates = @autoupdates begin 
+    θ_a, θ_b = params(q(θ))
+end
(θ_a,θ_b = params(q(θ)),)
rxresult = infer(
+    model = online_coin_toss_model(),
+    data  = (y = dataset, ),
+    autoupdates = autoupdates,
+    historyvars = (θ = KeepLast(), ),
+    keephistory = length(dataset),
+    initmarginals = (
+        θ = vague(Beta),
+    ),
+    autostart = true
+);
animation = @animate for i in 1:length(dataset)
+    plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = "Online coin bias inference", label = "Inferred bias", legend = :bottomright)
+    hline!([ p ], label = "Real bias", size = (600, 200))
+end
+
+gif(animation, "../pics/online-coin-bias-inference.gif", fps = 24, show_msg = false);

In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.

That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.

Variational inference

On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions $q \in \mathcal{Q}$. Often this involves assuming some factorization over $q$. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.

@model function test_model6_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+
+end

In this example we specified an extra constraints for $q_a$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

There are several options to specify the mean-field factorisation constraint. 

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name

It is also possible to use local structured factorisation:

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification

RxInfer.jl constraints macro

RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:

constraints6 = @constraints begin
+     q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

Note: where blocks have higher priority over constraints specification

@model function test_model6(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end

Inference

To run inference in this model we again need to create a synthetic dataset:

dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);

inference function

In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:

Use ?inference to quickly check the documentation for the inference function.

result = infer(
+    model         = test_model6(length(dataset)),
+    data          = (y = dataset, ),
+    constraints   = constraints6, 
+    initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),
+    returnvars    = (μ = KeepLast(), τ = KeepLast()),
+    iterations    = 10,
+    free_energy   = true,
+    showprogress  = true
+)
Inference results:
+  Posteriors       | available for (μ, τ)
+  Free Energy:     | Real[14763.3, 3275.49, 644.502, 601.009, 601.009, 601.
+009, 601.009, 601.009, 601.009, 601.009]
println("μ: mean = ", mean(result.posteriors[:μ]), ", std = ", std(result.posteriors[:μ]))
μ: mean = -2.9919174008110594, std = 0.013849961458913337
println("τ: mean = ", mean(result.posteriors[:τ]), ", std = ", std(result.posteriors[:τ]))
τ: mean = 5.213171798397569, std = 0.2329073393900073

Manual inference

For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);

For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:

setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values)
10-element Vector{Marginal}:
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-2.997906986213373e-9, w=
+0.010000001002000566))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.46754573443492, w=9.1
+90565291792494))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9965.403984486915, w=333
+0.7787123998623))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15588.61696393659, w=521
+0.243095807691))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.400556480787, w=52
+13.178863918331))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409327454854, w=52
+13.181795468951))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336208271, w=52
+13.181798394724))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336217037, w=52
+13.18179839753))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336217064, w=52
+13.181798397531))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336217064, w=52
+13.181798397531))
getvalues(τ_values)
10-element Vector{Marginal}:
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=5.0000000000457144e14))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=54571.80294201576))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=150.4157277972677))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.1569263385032))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10277608069556))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272203871091))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198477709))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198472312))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198472299))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198472299))
println("μ: mean = ", mean(last(μ_values)), ", std = ", std(last(μ_values)))
μ: mean = -2.9919174008110594, std = 0.013849961458913337
println("τ: mean = ", mean(last(τ_values)), ", std = ", std(last(τ_values)))
τ: mean = 5.213171798397569, std = 0.2329073393900073

Form constraints

In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.

<img style="display: block; margin-left: auto; margin-right: auto; width: 50%;" src="./pics/posterior.png" />

@model function test_model7_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+    
+    return μ, τ, y
+end

As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:

constraints7 = @constraints begin 
+    q(μ) :: PointMass
+    
+    q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+    q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

In this example we specified an extra constraints for $q_i$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

@model function test_model7(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar()
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end
model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);
setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, PointMass(1.0))
+
+μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values) |> last
Marginal(PointMass{Float64}(-2.99191740653874))
getvalues(τ_values) |> last
Marginal(GammaShapeRate{Float64}(a=501.0, b=96.00681126848353))

By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.

μ = randomvar() where { 
+    prod_constraint = ProdGeneric(),
+    form_constraint = SampleListFormConstraint() 
+}

Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:

μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }

Note: @constraints macro specifies required prod_constraint automatically.

Free Energy

During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);
bfe_observable = score(model, Float64, BetheFreeEnergy())
ProxyObservable(Float64, ErrorIfProxy())
bfe_subscription = subscribe!(bfe_observable, (fe) -> println("Current BFE value: ", fe));
# Reset the model with vague marginals
+setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
+
+for i in 1:10
+    update!(y, dataset)
+end
Current BFE value: 613.4987949414008
+Current BFE value: 601.0091294023605
+Current BFE value: 601.0091291534445
+Current BFE value: 601.0091291534441
+Current BFE value: 601.0091291534454
+Current BFE value: 601.0091291534436
+Current BFE value: 601.0091291534454
+Current BFE value: 601.0091291534436
+Current BFE value: 601.0091291534454
+Current BFE value: 601.0091291534436
# It always necessary to unsubscribe and release computer resources
+unsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])

Meta data specification

During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:

# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of 
+# the autoregressive process and its order. In addition it specifies that the message computation rules should
+# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations
+# by cost of possible numerical instabilities during an inference procedure
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }
+...
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }

Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:

# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` 
+# method with `21` sigma points for approximation of non-lineariety between hierarchy layers
+xt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }

The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.

RxInfer.jl @meta macro

Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:

@meta begin 
+     AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())
+end
Meta specification:
+  AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())
+Options:
+  warn = true

Creating custom nodes and message computation rules

Custom nodes

To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:

# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification
+@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]
+
+# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error
+struct NormalMeanVariance end 
+
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# It is also possible to use function objects as a node functional form
+function dot end
+
+# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them 
+# out = dot(x, a)
+@node typeof(dot) Deterministic [ out, x, a ]

Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.

After that it is possible to use the newly created node during model specification:

@model function test_model()
+    ...
+    y ~ dot(x, a)
+    ...
+end

Custom messages computation rules

RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:

\[\begin{aligned} +\mu_z = \mu_x + \mu_y\\ +V_z = V_x + V_y +\end{aligned}\]

To specify this in RxInfer.jl we use the @node and @rule macros:

@node typeof(+) Deterministic  [ z, x, y ]
+
+@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin
+    x_mean, x_var = mean_var(m_x)
+    y_mean, y_var = mean_var(m_y)
+    return NormalMeanVariance(x_mean + y_mean, x_var + y_var)
+end

In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:

\[\begin{aligned} +q(z) = \int q(z, x, y) \mathrm{d}x\mathrm{d}y +\end{aligned}\]

If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:

\[\begin{aligned} +\mu(z) = \int f(x, y, z)\mu(x)\mu(y)\mathrm{d}x\mathrm{d}y +\end{aligned}\]

\[\begin{aligned} +\nu(z) = \exp{ \int \log f(x, y, z)q(x)q(y)\mathrm{d}x\mathrm{d}y } +\end{aligned}\]

The @rule macro supports both cases with special prefixes during rule specification:

  • m_ prefix corresponds to the incoming message on a specific edge
  • q_ prefix corresponds to the posterior marginal of a specific edge

Example of a Sum-Product rule with m_ messages used:

@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin 
+    m_out_mean, m_out_cov = mean_cov(m_out)
+    return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))
+end

Example of a Variational rule with Mean-Field assumption with q_ posteriors used:

@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin 
+    return NormalMeanPrecision(mean(q_out), mean(q_τ))
+end

RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:

@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin
+    m, V = mean_cov(q_out_μ)
+    θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))
+    α = convert(typeof(θ), 1.5)
+    return Gamma(α, θ)
+end

NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:

# Inference backend expects arguments in `@rule` macro to be in the same order
+@node NormalMeanPrecision Stochastic [ out, μ, τ ]

Any rule always has access to the meta information with hidden the meta::Any variable:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin 
+    ...
+    println(meta)
+    ...
+end

It is also possible to dispatch on a specific type of a meta object:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin 
+    ...
+end

or

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin 
+    ...
+end

Customizing messages computational pipeline

In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.

<img style="display: block; margin-left: auto; margin-right: auto; width: 30%;" src="./pics/pipeline.png" width="20%" />

# Logs all outbound messages
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }
+# Initialise messages to be vague
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }
+# In principle, it is possible to approximate outbound messages with Laplace Approximation
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }

Let us return to the coin toss model, but this time we want to print flowing messages:

@model function coin_toss_model_log(n)
+
+    y = datavar(Float64, n)
+
+    θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage("θ") }
+
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)  where { pipeline = LoggerPipelineStage("y[$i]") }
+    end
+    
+    return y, θ
+end
_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));
θ_subscription = subscribe!(getmarginal(θ), (value) -> println("New posterior marginal for θ: ", value));
[θ][Beta][out]: VariationalMessage()
coinflips = float.(rand(Bernoulli(0.5), 5));
update!(y, coinflips)
[y[1]][Bernoulli][p]: VariationalMessage()
+[y[2]][Bernoulli][p]: VariationalMessage()
+[y[3]][Bernoulli][p]: VariationalMessage()
+[y[4]][Bernoulli][p]: VariationalMessage()
+[y[5]][Bernoulli][p]: VariationalMessage()
+New posterior marginal for θ: Marginal(Beta{Float64}(α=5.0, β=9.0))
unsubscribe!(θ_subscription)
# Inference is lazy and does not send messages if no one is listening for them
+update!(y, coinflips)
diff --git a/v2.16.1/examples/advanced_examples/Assessing People Skills/index.html b/v2.16.1/examples/advanced_examples/Assessing People Skills/index.html new file mode 100644 index 000000000..5befb8b03 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Assessing People Skills/index.html @@ -0,0 +1,49 @@ + +Assessing People’s Skills · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Assessing People’s Skills

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of "Model-Based Machine Learning" by Winn et al.

Problem Statement

We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?

We model the result for question $i$ as a continuous variable $r_i\in[0,1]$, and skill/attitude as a binary variable $s_i \in \{0, 1\}$, where $s_1$ represents whether the student has partied, and $s_2$ and $s_3$ represent whether the student has studied the chapters for the corresponding questions.

We assume the following logic:

  • If the student is alert (has not partied), then they will score on the first question;
  • If the student is alert or has studied chapter two, then they will score on question two;
  • If the student can answer question two and has studied chapter three, then they will score on question three.

Generative Model Definition

To model the probability for correct answers, we assume a latent state variable $t_i \in \{0,1\}$. The dependencies between the variables can then be modeled by the following Bayesian network:

(s_1)   (s_2)   (s_3)
+  |       |       |
+  v       v       v
+(t_1)-->(t_2)-->(t_3)
+  |       |       |
+  v       v       v
+(r_1)   (r_2)   (r_3)

As prior beliefs, we assume that a student is equally likely to study/party or not: $s_i \sim Ber(0.5)\,,$ for all $i$. Next, we model the domain logic as $\begin{aligned} t_1 &= ¬s_1\\ + t_2 &= t_1 ∨ s_2\\ + t_3 &= t_2 ∧ s_3\,. \end{aligned}$ For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as $t_i \sim Ber(s_i)\,,$ for all $i$.

Custom Nodes and Rules

The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.

In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.

using RxInfer, Random
+
+# Create Score node
+struct Score end
+
+@node Score Stochastic [out, in]

We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.

# Adding update rule for the Score node
+@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin     
+    return Bernoulli(mean(q_out))
+end

Generative Model Specification

We can now build the full generative model.

# GraphPPL.jl exports the `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function skill_model()
+    s = randomvar(3)
+    t = randomvar(3)
+    r = datavar(Float64, 3)
+
+    # Priors
+    for i=1:3
+        s[i] ~ Bernoulli(0.5)
+    end
+
+    # Domain logic
+    t[1] ~ ¬s[1]
+    t[2] ~ t[1] || s[2]
+    t[3] ~ t[2] && s[3]
+    
+    # Results
+    for i=1:3
+        r[i] ~ Score(t[i])
+    end
+end

Inference Specification

Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.

test_results = [0.1, 0.1, 0.1]
+inference_result = infer(
+    model = skill_model(),
+    data  = (r = test_results, )
+)
Inference results:
+  Posteriors       | available for (s, t)

Results

# Inspect the results
+map(params, inference_result.posteriors[:s])
3-element Vector{Tuple{Float64}}:
+ (0.9872448979591837,)
+ (0.06377551020408162,)
+ (0.4719387755102041,)

These results suggest that this particular student was very likely out on the town last night.

diff --git a/v2.16.1/examples/advanced_examples/Chance Constraints/index.html b/v2.16.1/examples/advanced_examples/Chance Constraints/index.html new file mode 100644 index 000000000..0110e854a --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Chance Constraints/index.html @@ -0,0 +1,166 @@ + +Chance-Constrained Active Inference · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Chance-Constrained Active Inference

This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, "Chance-constrained active inference") and discussion with John Boik.

We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. 

using Pkg; Pkg.activate(".."); Pkg.instantiate();
using Plots, Distributions, StatsFuns, RxInfer

Chance-Constraint Node Definition

A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not "overflow" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.

In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.

struct ChanceConstraint end  
+
+# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol
+@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]
# Function to compute normalizing constant and central moments of a truncated Gaussian distribution
+function truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)
+    V = clamp(V, tiny, huge)
+    StdG = Distributions.Normal(m, sqrt(V))
+    TrG = Distributions.Truncated(StdG, a, b)
+    
+    Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a)  # safe mass for standard Gaussian
+    
+    if Z < tiny
+        # Invalid region; return undefined mean and variance of truncated distribution
+        Z    = 0.0
+        m_tr = 0.0
+        V_tr = 0.0
+    else
+        m_tr = Distributions.mean(TrG)
+        V_tr = Distributions.var(TrG)
+    end
+    
+    return (Z, m_tr, V_tr)
+end;
@rule ChanceConstraint(:out, Marginalisation) (
+    m_out::UnivariateNormalDistributionsFamily, # Require inbound message
+    q_lo::PointMass, 
+    q_hi::PointMass, 
+    q_epsilon::PointMass, 
+    q_atol::PointMass) = begin 
+
+    # Extract parameters
+    lo = mean(q_lo)
+    hi = mean(q_hi)
+    epsilon = mean(q_epsilon)
+    atol = mean(q_atol)
+    
+    (m_bw, V_bw) = mean_var(m_out)
+    (xi_bw, W_bw) = (m_bw, 1. /V_bw)  # check division by  zero
+    (m_tilde, V_tilde) = (m_bw, V_bw)
+    
+    # Compute statistics (and normalizing constant) of q in safe region G
+    # Phi_G is called the "safe mass" 
+    (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)
+
+    xi_fw = xi_bw
+    W_fw  = W_bw
+    if epsilon <= 1.0 - Phi_G # If constraint is active
+        # Initialize statistics of uncorrected belief
+        m_tilde = m_bw
+        V_tilde = V_bw
+        for i = 1:100 # Iterate at most this many times
+            (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G
+            (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G
+
+            # Compute moments of non-G region as a mixture of left and right truncations
+            Phi_nG = Phi_lG + Phi_rG
+            m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG
+            V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2
+
+            # Compute moments of corrected belief as a mixture of G and non-G regions
+            m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG
+            V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2
+            # Re-compute statistics (and normalizing constant) of corrected belief
+            (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)
+            if (1.0 - Phi_G) < (1.0 + atol)*epsilon
+                break # Break the loop if the belief is sufficiently corrected
+            end
+        end
+        
+        # Convert moments of corrected belief to canonical form
+        W_tilde = inv(V_tilde)
+        xi_tilde = W_tilde * m_tilde
+
+        # Compute canonical parameters of forward message
+        xi_fw = xi_tilde - xi_bw
+        W_fw  = W_tilde - W_bw
+    end
+
+    return NormalWeightedMeanPrecision(xi_fw, W_fw)
+end

Definition of the Environment

We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.

wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile
+
+function initializeWorld()
+    x_0 = 0.0 # Initial elevation
+    
+    x_t_last = x_0
+    function execute(t::Int64, a_t::Float64)
+        x_t = x_t_last + a_t + wind(t) # Update elevation
+    
+        x_t_last = x_t # Reset state
+                
+        return x_t
+    end
+
+    x_t = x_0 # Predefine outcome variable
+    observe() = x_t # State is fully observed
+
+    return (execute, observe)
+end;

Generative Model for Regulator

We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.

@model function regulator_model(; T, lo, hi, epsilon, atol)
+    # Fully observed state
+    x_t = datavar(Float64)
+
+    # Control prior statistics
+    m_u = datavar(Float64, T)
+    v_u = datavar(Float64, T)    
+        
+    # Random variables
+    u = randomvar(T) # Control
+    x = randomvar(T) # Elevation
+    
+    # Loop over horizon
+    x_k_last = x_t
+    for k = 1:T
+        u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior
+        x[k] ~ x_k_last + u[k] # Transition model
+        x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state
+            pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency
+        x_k_last = x[k]
+    end
+    
+    return (u, x)
+end

Reactive Agent Definition

function initializeAgent()
+    # Set control prior statistics
+    m_u = zeros(T)
+    v_u = lambda^(-1)*ones(T)
+    
+    function compute(x_t::Float64)
+        model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)
+        data_t = (m_u = m_u, v_u = v_u, x_t = x_t)
+        
+        result = infer(
+            model = model_t, 
+            data = data_t,
+            iterations = n_its)
+
+        # Extract policy from inference results
+        pol = mode.(result.posteriors[:u][end])
+
+        return pol
+    end
+
+    pol = zeros(T) # Predefine policy variable
+    act() = pol[1]
+
+    return (compute, act)
+end;

Action-Perception Cycle

Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. 

# Simulation parameters
+N = 160 # Total simulation time
+T = 1 # Lookahead time horizon
+lambda = 1.0 # Control prior precision
+lo = 1.0 # Chance region lower bound
+hi = Inf # Chance region upper bound
+epsilon = 0.01 # Allowed chance violation
+atol = 0.01 # Convergence tolerance for chance constraints
+n_its = 10;  # Number of inference iterations
(execute, observe) = initializeWorld() # Let there be a world
+(compute, act) = initializeAgent() # Let there be an agent
+
+a = Vector{Float64}(undef, N) # Actions
+x = Vector{Float64}(undef, N) # States
+for t = 1:N
+    a[t] = act()
+           execute(t, a[t])
+    x[t] = observe()
+           compute(x[t])
+end

Results

Results show that the agent does not allow the wind to push it all the way to the ground.

p1 = plot(1:N, wind.(1:N), color="blue", label="Wind", ylabel="Velocity", lw=2)
+plot!(p1, 1:N, a, color="red", label="Control", lw=2)
+p2 = plot(1:N, x, color="black", lw=2, label="Agent", ylabel="Elevation")
+plot(p1, p2, layout=(2,1))

diff --git a/v2.16.1/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html b/v2.16.1/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html new file mode 100644 index 000000000..da29e4f32 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html @@ -0,0 +1,143 @@ + +Conjugate-Computational Variational Message Passing (CVI) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Conjugate-Computational Variational Message Passing (CVI)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions

In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.

This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.

An example: nonlinear dynamical system

A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position $z_t$ at time $t$. Instead they have access to the observed squared distance $y_t$ between the object and some reference point $s$. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:

# data generating process
+nr_observations = 50
+reference_point = 53
+hidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)
+measurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);
# plot hidden location and reference frame
+p1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label="hidden location")
+hline!([reference_point], linewidth=3, label="reference point")
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot measurements
+p2 = scatter(1:nr_observations, measurements, linewidth=3, label="measurements")
+xlabel!("time [sec]"), ylabel!("squared distance [cm2]")
+
+plot(p1, p2, size=(1200, 500))

The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model

\[\begin{aligned} + p(\tau) & = \Gamma(\tau \mid \alpha_{\tau}, \beta_{\tau}),\\ + p(\gamma) & = \Gamma(\gamma \mid \alpha_{\gamma}, \beta_{\gamma}),\\ + p(z_t \mid z_{t - 1}, \tau) & = \mathcal{N}(z_t \mid z_{t - 1} + 1, \tau^{-1}),\\ + p(y_t \mid z_t, \gamma) & = \mathcal{N}(y_t \mid (z_t - s)^2, \gamma^{-1}), +\end{aligned}\]

where the researchers put priors on the process and measurement noise parameters, $\tau$ and $\gamma$, respectively. They do this, because they do not know the accuracy of their devices.

The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:

function compute_squared_distance(z)
+    (z - reference_point)^2
+end;
@model function measurement_model(nr_observations)
+
+    # allocate random variables and observations
+    z = randomvar(nr_observations)
+    y = datavar(Float64, nr_observations)
+
+    # set priors on precision parameters
+    τ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    γ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    
+    # specify estimate of initial location
+    z[1] ~ Normal(mean = 0, precision = τ)
+    y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)
+
+    # loop over observations
+    for t in 2:nr_observations
+
+        # specify state transition model
+        z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)
+
+        # specify non-linear observation model
+        y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)
+        
+    end
+
+end

But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).

The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:

@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)
+    compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)
+end;

In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:

@meta function model_meta(...)
+    f() -> CVI(args...)
+end

See ?CVI for more information about the args....

In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.

In the above example, we will assume the following posterior factorization:

@constraints function measurement_constraints()
+    q(z, τ, γ) = q(z)q(τ)q(γ)
+end;

This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as 

@constraints function posterior_constraints() begin
+    q(z, γ) = q(z)q(γ) # CVI
+    q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node
+end

Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.

results = infer(
+    model = measurement_model(nr_observations),
+    data = (y = measurements,),
+    iterations = 5,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = measurement_constraints(),
+    meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),
+    initmessages = (z = NormalMeanVariance(0, 5),),
+    initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),
+)
Inference results:
+  Posteriors       | available for (z)
+  Free Energy:     | Real[1241.91, 429.933, 376.869, 365.774, 362.879]
# plot estimates for location
+p1 = plot(collect(1:nr_observations), hidden_location, label = "hidden location", legend=:topleft, linewidth=3, color = :red)
+plot!(map(mean, results.posteriors[:z]), label = "estimated location (±2σ)", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot Bethe free energy
+p2 = plot(results.free_energy, linewidth=3, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size = (1200, 500))

Requirements

There are several main requirements for the CVI procedure to satisfy:

  1. The out interface of the non-linearity must be independently factorized with respect to other variables in the model.
  2. The messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.

In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as

@model function model(...)
+    ...
+    y ~ f(x1, x2, ..., xN)
+    ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity
+    ... 
+end
+
+@constraints function constraints_meta() begin
+    q(y, z1, ..., zn) = q(y)q(z1,...,zM)
+    ...
+end;
+
+@meta function model_meta(...)
+    f() -> CVI(rng, nr_samples, nr_iterations, optimizer))
+end

Note that not all exponential family distributions are implemented.

Extensions

Using a custom optimizer

CVI only supports Optimisers optimizers out of the box.

Below an explanation on how to extend to it to a custom optimizer.

Suppose we have CustomDescent structure which we want to use inside CVI for optimization.

To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).

ReactiveMP.cvi_update! incapsulates the gradient step:

  1. opt is used to select your optimizer structure
  2. λ is the current value
  3. ∇ is a gradient value computed inside CVI.
struct CustomDescent 
+    learning_rate::Float64
+end
+
+# Must return an optimizer and its initial state
+function ReactiveMP.cvi_setup(opt::CustomDescent, q)
+     return (opt, nothing)
+end
+
+# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)
+function ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)
+    opt, _ = opt_and_state
+    λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))
+    copyto!(new_λ, λ̂)
+    return opt_and_state, new_λ
+end

Let's try to apply it to a model: $\begin{aligned} p(x) & = \mathcal{N}(0, 1),\\ + p(y_{i}\mid x) & = \mathcal{N}(y_i \mid x^2, 1),\\ +\end{aligned}$

Let's generate some synthetic data for the model

# generate data
+y = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)
+histogram(y)

Again we can create the corresponding model as:

# specify non-linearity
+f(x) = x ^ 2
+
+# specify model
+@model function normal_square_model(nr_observations)
+
+    # allocate observations
+    y = datavar(Float64, nr_observations)
+
+    # describe prior on latent state
+    x ~ NormalMeanPrecision(0, 100)
+
+    # transform latent state
+    mean ~ f(x)
+
+    # observation model
+    y .~ NormalMeanVariance(mean, 1)
+
+end
+
+# specify meta
+@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)
+    f() ->  CVI(rng, nr_samples, nr_iterations, optimizer)
+end
normal_square_meta (generic function with 1 method)

We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:

Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.

res = infer(
+    model = normal_square_model(1000),
+    data = (y = y,),
+    iterations = 10,
+    free_energy = true,
+    initmessages = (x = NormalMeanVariance(0, 100),),
+    meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))
+)
+
+mean(res.posteriors[:x][end])
-18.998075156688632

The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working!

Note: $x^2$ can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.

diff --git a/v2.16.1/examples/advanced_examples/GP Regression by SSM/index.html b/v2.16.1/examples/advanced_examples/GP Regression by SSM/index.html new file mode 100644 index 000000000..11e441719 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/GP Regression by SSM/index.html @@ -0,0 +1,99 @@ + +Solve GP regression by SDE · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Solve GP regression by SDE

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this notebook, we solve a GP regression problem by using "Stochastic Differential Equation" (SDE). This method is well described in the dissertation "Stochastic differential equation methods for spatio-temporal Gaussian process regression." by Arno Solin and "Sequential Inference for Latent Temporal Gaussian Process Models" by Jouni Hartikainen. The idea of the method is as follows.

Suppose a function $f(x)$ follows a zero-mean Gaussian Process $\begin{aligned} f(x) \sim \mathcal{GP}(0, k(x,x')). \end{aligned}$

When the dimensionality of $x$ is 1, we can consider $f(x)$ as a stochastic process over time, i.e. $f(t)$. For a certain classses of covariance functions, $f(t)$ is a solution to an $m$-th order linear stochastic differential equation (SDE) $\begin{aligned} a_0 f(t) + a_1 \frac{d f(t)}{dt} + \dots + a_m \frac{d^m f(t)}{dt^m} = w(t) \end{aligned}$

where $w(t)$ is a zero-mean white noise process with spectral density $Q_c$. If we define a vector-valued function $\mathbf{f}(t) = (f(t),\, d/dt f(t),\dots,\, d^{m-1}/dt^{m-1}f(t))$, then we can rewrite the above SDE under the companion form

\[\begin{aligned} +\frac{d \mathbf{f}(t)}{dt} = \mathbf{F}\, \mathbf{f}(t) + \mathbf{L} w(t) \quad (1) +\end{aligned}\]

where $\mathbf{F}$ and $\mathbf{L}$ are defined based on the choice of covariance functions. From (1), we have the following state-space model: $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \quad(2a) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}) \quad(2b). \\ +\end{aligned}$

where $\mathbf{A}_k = \exp{(\mathbf{F}\,\Delta t_k)}$, with $\Delta t_k = t_{k+1} - t_k$, is called the discrete-time state transition matrix, and $\mathbf{Q}_k$ the process noise covariance matrix. For the computation of $\mathbf{Q}_k$, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state $f_0 \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_0)$. For stationary covariance function, the SDE has a stationary state $f_\infty \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_\infty)$, where $\mathbf{P}_\infty$ is the solution to $\begin{aligned} \frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0 \quad (\mathrm{Lyapunov \, equation}). \end{aligned}$

With this stationary condition, the process noise covariance $\mathbf{Q}_k$ is computed as follows $\begin{aligned} \mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T \end{aligned}$

For one-dimensional problem the SDE representation of the GP is defined by the matrices $\mathbf{F}, \, \mathbf{L}, \, \mathbf{Q}_c, \, \mathbf{P}_0$ and $\mathbf{H}$. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.

using RxInfer, Random, Distributions, LinearAlgebra, Plots

Create state space model for GP regression

Here we create a state-space model $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}), \\ +\end{aligned}$ where $y_k$ is the noisy observation of the function $f$ at time $t_k$, and $\sigma^2_{noise}$ is the noise variance and assumed to be known.

@model function gp_regression(n, P∞, A, Q, H, σ²_noise)
+    f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)
+    f = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+    
+    f_prev = f_0
+
+    for i=1:n
+        f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])
+        y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)
+        f_prev = f[i]
+    end
+    return f, y
+end

Generate data

Random.seed!(10)
+n = 100
+σ²_noise = 0.04;
+t = collect(range(-2, 2, length=n)); #timeline
+f_true = sinc.(t); # true process
+f_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process
+
+pos = sort(randperm(75)[1:2:75]); 
+t_obser = t[pos]; # time where we observe data
+
+y_data = Array{Union{Float64,Missing}}(missing, n)
+for i in pos 
+    y_data[i] = f_noisy[i]
+end
+
+θ = [1., 1.]; # store [l, σ²]
+Δt = [t[1]]; # time difference
+append!(Δt, t[2:end] - t[1:end-1]);

Let's visualize our data

plot(t, f_true, label="True process f(t)")
+scatter!(t_obser, y_data[pos], label = "Noisy observations")
+xlabel!("t")
+ylabel!("f(t)")

Covariance function: Matern-3/2

The Matern is a stationary covariance function and defined as follows $\begin{aligned} k(\tau) = \sigma^2 \frac{2^{1-\nu}}{\Gamma(\nu)} \left(\frac{\sqrt{2\nu}\tau}{l} \right)^\nu K_\nu\left(\frac{\sqrt{2\nu}\tau}{l} \right) \end{aligned}$ where $\begin{aligned} \sigma^2: \text{the magnitude scale hyperparameter}\\ +l: \text{the characteristic length-scale}\\ +\nu: \text{the smoothness hyperparameter}\\ +K_\nu(.): \text{the modified Bessel function of the second kind}. \end{aligned}$ When we say the Matern-3/2, we mean $\nu=3/2$. The matrices for the state space model are computed as follows $\begin{aligned} \mathbf{F} = \begin{pmatrix} 0 & 1\\ +-\lambda^2 & -2\lambda \end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} 0 \\ 1 \end{pmatrix}, \quad \quad \mathbf{P}_\infty = \begin{pmatrix} \sigma^2 & 0 \\ 0 & \lambda^2\sigma^2 \end{pmatrix} ,\quad \quad \mathbf{H} = \begin{pmatrix} 1 & 0 \end{pmatrix}, \quad \quad Q_c = 4\lambda^3\sigma^2 \end{aligned}$ where $\lambda = \frac{\sqrt{3}}{l} $. From these matrices, we can define $\mathbf{A}_k$ and $\mathbf{Q}_k$.

λ = sqrt(3)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 1.];
+H = [1., 0.];
+F = [0. 1.; -λ^2 -2λ]
+P∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_32 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Covariance function: Matern-5/2

Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:

\[\begin{aligned} +\mathbf{F} = \begin{pmatrix} +0 & 1 & 0\\ +0 & 0 & 1 \\ +-\lambda^3 & -3\lambda^2 & -3\lambda +\end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} +0 \\ 0 \\ 1 +\end{pmatrix}, \quad \quad \mathbf{H} = \begin{pmatrix} +1 & 0 & 0 +\end{pmatrix}, \quad \quad Q_c = \frac{16}{3} \sigma^2 \lambda^5, +\end{aligned}\]

where $\lambda = \sqrt{5} / l$. To find $\mathbf{P}_\infty$, we solve the Lyapunov equation

\[\begin{aligned} +\frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0, +\end{aligned}\]

of which the solution is

\[\begin{aligned} +vec(\mathbf{P}_\infty) = (\mathbf{I} \otimes \mathbf{F} + \mathbf{F}\otimes\mathbf{I})^{-1}\, vec(-\mathbf{L}Q_c\mathbf{L}^T) +\end{aligned}\]

where $vec(.)$ is the vectorization operator and $\otimes$ denotes the Kronecker product. Now we can find $\mathbf{A}_k$ and $\mathbf{Q}_k$

\[\begin{aligned} +\mathbf{A}_k = \exp{(\mathbf{F}\Delta t_k)} +\end{aligned}\]

\[\begin{aligned} +\mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T +\end{aligned}\]

λ = sqrt(5)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 0., 1.];
+H = [1., 0., 0.];
+F = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]
+Qc = 16/3 * θ[2] * λ^5;
+
+I = diageye(3) ; 
+vec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); 
+P∞ = reshape(vec_P,3,3);
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_52 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Result

slicedim(dim) = (a) -> map(e -> e[dim], a)
+
+plot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M32", title = "Matern-3/2", legend =false, lw = 2)
+plot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M52",legend = :bottomleft, title = "GPRegression by SSM", lw = 2)
+plot!(t, f_true,label="true process", lw = 2)
+scatter!(t_obser, f_noisy[pos], label="Observations")
+xlabel!("t")
+ylabel!("f(t)")

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.

diff --git a/v2.16.1/examples/advanced_examples/Global Parameter Optimisation/index.html b/v2.16.1/examples/advanced_examples/Global Parameter Optimisation/index.html new file mode 100644 index 000000000..26ceb9d90 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Global Parameter Optimisation/index.html @@ -0,0 +1,497 @@ + +Global Parameter Optimisation · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Global Parameter Optimisation

This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.

By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Univariate State Space Model

Let us try use the following simple state space model:

\[\begin{aligned} + {x}_t &= {x}_{t-1} + c \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, p \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Our goal is to optimize parameters $c$ and ${m_{{x}_0}}$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)
+    
+    x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n)
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ x_prev + c
+        y[i] ~ NormalMeanVariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+
+    return x, y
+end
rng = MersenneTwister(42)
+
+P      = 1.0
+n      = 250
+c_real = -5.0
+data   = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);
# c[1] is C
+# c[2] is μ0
+function f(c)
+    x0_prior = NormalMeanVariance(c[2], 100.0)
+    result = infer(
+        model = smoothing(n, x0_prior, c[1], P), 
+        data  = (y = data,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
using Optim
res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     3.651509e+02     1.001412e+03
+ * time: 0.02315521240234375
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     3.645772e+02
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.18e-06 ≰ 0.0e+00
+    |x - x'|/|x'|          = 2.30e-07 ≰ 0.0e+00
+    |f(x) - f(x')|         = 9.13e-07 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00
+    |g(x)|                 = 2.56e-06 ≤ 1.0e-03
+
+ * Work counters
+    Seconds run:   6  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    67
+    ∇f(x) calls:   67
res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)
2-element Vector{Float64}:
+  1.0007749243942134
+ -5.14368311177876
println("Real value vs Optimized")
+println("Real:      ", [ 1.0, c_real ])
+println("Optimized: ", res.minimizer)
Real value vs Optimized
+Real:      [1.0, -5.0]
+Optimized: [1.0007749243942134, -5.14368311177876]

Multivariate state space model

Let us consider the multivariate state space model:

\[\begin{aligned} + \mathbf{x}_t &\sim \mathcal{N}\left(\mathbf{Ax}_{t-1}, \mathbf{Q} \right) \\ + \mathbf{y}_t &\sim \mathcal{N}\left(\mathbf{x}_{t}, \mathbf{P} \right) +\end{aligned}\]

with prior

\[\begin{aligned} +\mathbf{x}_0 \sim \mathcal{N}(\mathbf{m_{{x}_0}}, \mathbf{V_{{x}_0}})\ +\end{aligned}\]

and transition matrix

\[\begin{aligned} +\mathbf{A} = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} +\end{aligned}\]

Covariance matrices $\mathbf{V_{{x}_0}}$, $\mathbf{P}$ and $\mathbf{Q}$ are known. Our goal is to optimize parameters $\mathbf{m_{{x}_0}}$ and $\theta$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)
+    
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    
+    x_prev = x_prior
+    
+    A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)
+        y[i] ~ MvNormalMeanCovariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+    
+end
# Generate data
+function generate_rotate_ssm_data()
+    rng = MersenneTwister(1234)
+
+    θ = π / 8
+    A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+    Q = Matrix(Diagonal(1.0 * ones(2)))
+    P = Matrix(Diagonal(1.0 * ones(2)))
+
+    n = 300
+
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(x[i], Q))
+        
+        x_prev = x[i]
+    end
+
+    return θ, A, Q, P, n, x, y
+end
generate_rotate_ssm_data (generic function with 1 method)
θ, A, Q, P, n, x, y = generate_rotate_ssm_data();
px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+
+plot(px, size = (1200, 450))

function f(θ)
+    x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))
+    result = infer(
+        model = rotate_ssm(n, θ[1], x0, Q, P), 
+        data  = (y = y,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     2.192003e+04     9.032537e+04
+ * time: 7.510185241699219e-5
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.161372e+03
+
+ * Found with
+    Algorithm:     L-BFGS
+
+ * Convergence measures
+    |x - x'|               = 5.09e-09 ≰ 0.0e+00
+    |x - x'|/|x'|          = 4.48e-10 ≰ 0.0e+00
+    |f(x) - f(x')|         = 0.00e+00 ≤ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14
+    |g(x)|                 = 5.63e-07 ≰ 1.0e-12
+
+ * Work counters
+    Seconds run:   18  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    58
+    ∇f(x) calls:   58
println("Real value vs Optimized")
+println("Real:      ", θ)
+println("Optimized: ", res.minimizer[1])
+
+@show sin(θ), sin(res.minimizer[1])
+@show cos(θ), cos(res.minimizer[1])
Real value vs Optimized
+Real:      0.39269908169872414
+Optimized: 0.3929332481380117
+(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)
+(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)
+(0.9238795325112867, 0.9237898955654058)
x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))
+
+result = infer(
+    model = rotate_ssm(n, res.minimizer[1], x0, Q, P), 
+    data  = (y = y,), 
+    free_energy = true
+)
+
+xmarginals = result.posteriors[:x]
+
+px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "inf₁")
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "inf₂")
+
+plot(px, size = (1200, 450))

Learning Kalman filter with LSTM driven dynamic

In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example.

Our objective is to compute the marginal posterior distribution of the latent (hidden) state $x_k$ at each time step $k$, considering the history of measurements up to that time step:

\[ +p(x_k | y_{1:k}). +$$ + +The above expression represents the probability distribution of the latent state $x_k$ given the measurements $y_{1:k}$ up to time step $k$. + +```julia +using RxInfer, BenchmarkTools, Flux, ReverseDiff, Random, Plots, LinearAlgebra, ProgressMeter, JLD, StableRNGs +``` + + + +### Generate data + +```julia +# Lorenz system equations to be used to generate dataset +Base.@kwdef mutable struct Lorenz + dt::Float64 + σ::Float64 + ρ::Float64 + β::Float64 + x::Float64 + y::Float64 + z::Float64 +end + +function step!(l::Lorenz) + dx = l.σ * (l.y - l.x); l.x += l.dt * dx + dy = l.x * (l.ρ - l.z) - l.y; l.y += l.dt * dy + dz = l.x * l.y - l.β * l.z; l.z += l.dt * dz +end +; +``` + + +```julia +# Dataset +rng = StableRNG(999) + +ordered_dataset = [] +ordered_parameters = [] +for σ = 11:15 + for ρ = 23:27 + for β_nom = 6:9 + attractor = Lorenz(0.02, σ, ρ, β_nom/3.0, 1, 1, 1) + noise_free_data = [[1.0, 1.0, 1.0]] + for i=1:99 + step!(attractor) + push!(noise_free_data, [attractor.x, attractor.y, attractor.z]) + end + push!(ordered_dataset, noise_free_data) + push!(ordered_parameters, [σ, ρ, β_nom/3.0]) + end + end +end + +new_order = collect(1:100) +shuffle!(rng,new_order) + +dataset = [] # noisy dataset +noise_free_dataset = [] # noise free dataset +lorenz_parameters = [] + +for i in new_order + local data = [] + push!(noise_free_dataset, ordered_dataset[i]) + push!(lorenz_parameters, ordered_parameters[i]) + for nfd in ordered_dataset[i] + push!(data,nfd+randn(rng,3)) + end + push!(dataset, data) +end + +trainset = dataset[1:60] +validset = dataset[61:80] +testset = dataset[81:end] + +noise_free_trainset = noise_free_dataset[1:60] +noise_free_validset = noise_free_dataset[61:80] +noise_free_testset = noise_free_dataset[81:end] +; +``` + + + +### Data visualization + +```julia +one_nonoise=noise_free_trainset[1] +one=trainset[1] +gx, gy, gz = zeros(100), zeros(100), zeros(100) +rx, ry, rz = zeros(100), zeros(100), zeros(100) +for i=1:100 + rx[i], ry[i], rz[i] = one[i][1], one[i][2], one[i][3] + gx[i], gy[i], gz[i] = one_nonoise[i][1], one_nonoise[i][2], one_nonoise[i][3] +end +p1=plot(rx,ry,label="Noise observations") +p1=plot!(gx,gy,label="True state") +xlabel!("x") +ylabel!("y") +p2=plot(rx,rz,label="Noise observations") +p2=plot!(gx,gz,label="True state") +xlabel!("x") +ylabel!("z") +p3=plot(ry,rz,label="Noise observations") +p3=plot!(gy,gz,label="True state") +xlabel!("y") +ylabel!("z") +plot(p1, p2, p3, size = (800, 200),layout=(1,3)) +``` + +![](../../assets/examples/Global Parameter Optimisation_22_1.png) + + +### Inference + + +We use the following state-space model representation: + +$$\begin{aligned} +x_k \sim p(x_k | x_{k-1}) \\ +y_k \sim p(y_k | x_k). +\end{aligned}\]

where $x_k \sim p(x_k | x_{k-1})$ represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system.

\[\begin{aligned} +A_{k-1}=NN(y_{k-1}) \\ +p(x_k | x_{k-1})=\mathcal{N}(x_k | A_{k-1}x_{k-1}, Q) \\ +p(y_k | x_k)=\mathcal{N}(y_k | Bx_k, R) +\end{aligned}\]

where $NN$ is the neural network. The input is the observation $y_{k-1}$, and output is the trasition matrix $A_{k-1}$. $B$ denote distortion or measurment matrix. $Q$ and $R$ are covariance matrices. Note that the hidden state $x_k$ comprises three coordinates, i.e. $x_k = (rx_k, ry_k, rz_k)$

By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.

# Neural Network model
+mutable struct NN
+    InputLayer
+    OutputLater
+    g
+    params
+    function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+        InputLayer = Dense(W1, b1, relu)
+        Lstm = LSTM(W2_1,W2_2,b2,s2_1)
+        OutputLayer = Dense(W3, b3)
+        g = Chain(InputLayer, OutputLayer);
+        new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))
+    end
+end

Model specification

Note that we treat the trasition matrix $A_{k-1}$ as time-varying.

#State Space Model
+@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior_mean = zeros(3)
+    x_prior_cov  = Matrix(Diagonal(ones(3)))
+    
+    x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)
+    y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }
+    
+    for i in 2:n
+        x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }
+        y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }
+    end
+    
+    return x, y
+end

We set distortion matrix $B$ and the covariance matrices $Q$ and $R$ as identity matrix.

Q = Matrix(Diagonal(ones(3)))*2
+B = Matrix(Diagonal(ones(3)))
+R = Matrix(Diagonal(ones(3)))
+;

We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix $A$ output by the neural network. And the $A$ is treated as a datavar in the inference function.

function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    n = length(data)
+    neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])
+    return As
+end
get_matrix_AS (generic function with 1 method)

The weights of neural network $NN$ are initialized as follows:

# Initial model parameters
+W1, b1 = randn(5, 3)./100, randn(5)./100
+W2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)
+W3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100
+;

Before network training, we show the inference results for the hidden states:

# Performance on an instance from the testset before training
+index = 1
+data=testset[index]
+n=length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300))

Training network

In this part, we use the Free Energy as the objective function to optimize the weights of network.

# free energy objective to be optimized during training
+function fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    fe_ = 0
+    for train_instance in trainset
+        result = infer(
+            model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+            data  = (y = train_instance, ), 
+            returnvars = (x = KeepLast(), ),
+            free_energy = true
+        )
+        fe_ += result.free_energy[end]
+    end
+    return fe_
+end
fe_tot_est (generic function with 1 method)

Training

# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights
+# Uncomment the following code to train the network manually
+# opt = Flux.Optimise.RMSProp(0.006, 0.95)
+# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+# @showprogress for epoch in 1:800
+#     grads = ReverseDiff.gradient(fe_tot_est, params);
+#     for i=1:length(params)
+#         Flux.Optimise.update!(opt,params[i],grads[i])
+#     end
+# end

Test

Import the weights of neural network that we have trained.

W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load("../data/nn_prediction/weights.jld")["data"];
# Performance on an instance from the testset after training
+index = 1
+data = testset[index]
+n = length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+
+gx, gy, gz = zeros(100), zeros(100), zeros(100)
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+plot(p1, p2, p3, size = (1000, 300))

Prediction

In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill $k$ and estimate the future state at time $k+1$, $k+2$, $\dots$,$k+T$.

We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.

\[\begin{aligned} +A_{k}=NN(x_{k}) \\ +p(x_{k+1} | x_{k})=\mathcal{N}(x_{k+1} | A_{k}x_{k}, Q) \\ +\end{aligned}\]

#Define the prediction function
+multiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))
+sumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)
+
+function runForward(A,B,Q,R,mh_old,Vh_old)
+    mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)
+    mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)
+end
+
+function g_predict(mh_old,Vh_old,Q)
+    neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)
+    # Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])
+    As = As[1]
+    return runForward(As,B,Q,R,mh_old,Vh_old), As
+end
g_predict (generic function with 1 method)

After $k=75$, the observations are not available, and we predict the future state from $k=76$ to the end

tt = 75
+mh = mean(x_est[tt])
+Vh = cov(x_est[tt])
+mo_list, Vo_list, A_list = [], [], [] 
+inv_Q = inv(Q)
+for t=1:100-tt
+    (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)
+    push!(mo_list, mo)
+    push!(Vo_list, Vh)
+    push!(A_list, A_t)
+    global mh = mo
+    global Vh = Vo
+end
# Prediction visualization
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+for i=1:tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+for i=tt+1:100
+    ii=i-tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]
+end
+p1 = plot(rx,label="Ground truth rx")
+p1 = plot!(rx_est_m,label="Inffered state rx",ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Ground truth ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index][1:tt], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Ground truth rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)

diff --git a/v2.16.1/examples/advanced_examples/Infinite Data Stream/index.html b/v2.16.1/examples/advanced_examples/Infinite Data Stream/index.html new file mode 100644 index 000000000..2b969475e --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Infinite Data Stream/index.html @@ -0,0 +1,169 @@ + +Infinite Data Stream · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Infinite Data Stream

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:

using RxInfer, Plots, Random, StableRNGs

For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:

mutable struct Environment
+    rng                   :: AbstractRNG
+    current_state         :: Float64
+    observation_precision :: Float64
+    history               :: Vector{Float64}
+    observations          :: Vector{Float64}
+    
+    Environment(current_state, observation_precision; seed = 123) = begin 
+         return new(StableRNG(seed), current_state, observation_precision, [], [])
+    end
+end
+
+function getnext!(environment::Environment)
+    environment.current_state = environment.current_state + 1.0
+    nextstate  = 10sin(0.1 * environment.current_state)
+    observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))
+    push!(environment.history, nextstate)
+    push!(environment.observations, observation)
+    return observation
+end
+
+function gethistory(environment::Environment)
+    return environment.history
+end
+
+function getobservations(environment::Environment)
+    return environment.observations
+end
getobservations (generic function with 1 method)

Model specification

We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:

@model function kalman_filter()
+    
+    # Prior for the previous state
+    x_prev_mean = datavar(Float64)
+    x_prev_var  = datavar(Float64)
+    
+    x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)
+    
+    # Prior for the observation noise
+    τ_shape = datavar(Float64)
+    τ_rate  = datavar(Float64)
+    
+    τ ~ Gamma(shape = τ_shape, rate = τ_rate)
+    
+    # Random walk with fixed precision
+    x_current ~ Normal(mean = x_prev, precision = 1.0)
+    
+    # Noisy observation
+    y = datavar(Float64)
+    y ~ Normal(mean = x_current, precision = τ)
+    
+end
+
+# We assume the following factorisation between variables 
+# in the variational distribution
+@constraints function filter_constraints()
+    q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)
+end
filter_constraints (generic function with 1 method)

Prepare environment

initial_state         = 0.0
+observation_precision = 0.1
0.1

After we have created the environment we can observe how our signal behaves:

testenvironment = Environment(initial_state, observation_precision);
+
+animation = @animate for i in 1:100
+    getnext!(testenvironment)
+    
+    history = gethistory(testenvironment)
+    observations = getobservations(testenvironment)
+    
+    p = plot(size = (1000, 300))
+    
+    p = plot!(p, 1:i, history[1:i], label = "Hidden signal")
+    p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = "Observation")
+end
+
+gif(animation, "../pics/infinite-data-stream.gif", fps = 24, show_msg = false);

Filtering on static dataset

RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:

n                  = 300
+static_environment = Environment(initial_state, observation_precision);
+
+for i in 1:n
+    getnext!(static_environment)
+end
+
+static_history      = gethistory(static_environment)
+static_observations = getobservations(static_environment);
+static_datastream   = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
function run_static(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        keephistory   = 10_000,
+        historyvars   = (x_current = KeepLast(), τ = KeepLast()),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        free_energy   = true,
+        autostart     = true,
+    )
+    
+    return engine
+end
run_static (generic function with 1 method)
result = run_static(static_environment, static_datastream);
static_inference = @animate for i in 1:n
+    estimated = result.history[:x_current]
+    p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = "Estimation")
+    p = plot!(static_history[1:i], label = "Real states")    
+    p = scatter!(static_observations[1:i], ms = 2, label = "Observations")
+    p = plot(p, size = (1000, 300), legend = :bottomright)
+end
+
+gif(static_inference, "../pics/infinite-data-stream-inference.gif", fps = 24, show_msg = false);

plot(result.free_energy_history, label = "Bethe Free Energy (averaged)")

Filtering on realtime dataset

Next lets create a "real" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:

function run_and_plot(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    posteriors = []
+    
+    plotfn = (q_current) -> begin 
+        IJulia.clear_output(true)
+        
+        push!(posteriors, q_current)
+
+        p = plot(mean.(posteriors), ribbon = var.(posteriors), label = "Estimation")
+        p = plot!(gethistory(environment), label = "Real states")    
+        p = scatter!(getobservations(environment), ms = 2, label = "Observations")
+        p = plot(p, size = (1000, 300), legend = :bottomright)
+
+        display(p)
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        autostart     = false,
+    )
+    
+    qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)
+    
+    RxInfer.start(engine)
+    
+    return engine
+end
run_and_plot (generic function with 1 method)
# This example runs in our documentation pipeline, which does not support "real-time" execution context
+# We skip this code if run not in Jupyter notebook (see below an example with gif)
+engine = nothing 
+if isdefined(Main, :IJulia)
+    timegen      = 41 # 41 ms
+    environment  = Environment(initial_state, observation_precision);
+    observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations
+    datastream   = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
+    engine = run_and_plot(environment, datastream)
+end;

The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:

if !isnothing(engine) && isdefined(Main, :IJulia)
+    RxInfer.stop(engine)
+    IJulia.clear_output(true)
+end;
diff --git a/v2.16.1/examples/advanced_examples/Nonlinear Sensor Fusion/index.html b/v2.16.1/examples/advanced_examples/Nonlinear Sensor Fusion/index.html new file mode 100644 index 000000000..3735dc0ad --- /dev/null +++ b/v2.16.1/examples/advanced_examples/Nonlinear Sensor Fusion/index.html @@ -0,0 +1,140 @@ + +Nonlinear Sensor Fusion · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Nonlinear Sensor Fusion

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers
+using DataFrames, DelimitedFiles, StableRNGs

In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.

A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.

To illustrate these noisy measurements, the engineers decided to plot them:

# fetch measurements
+beacon_locations = readdlm("../data/sensor_fusion/beacons.txt")
+distances = readdlm("../data/sensor_fusion/distances.txt")
+position = readdlm("../data/sensor_fusion/position.txt")
+nr_observations = size(distances, 1);
# plot beacon and actual location of WALL-E
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+xlabel!("longitude [m]"), ylabel!("latitude [m]")
+
+# plot noisy distance measurements
+p2 = plot(distances, legend=:topleft, linewidth=3, label=["distance to beacon 1" "distance to beacon 2" "distance to beacon 3"])
+xlabel!("time [sec]"), ylabel!("distance [m]")
+
+plot(p1, p2, size=(1200, 500))

In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time $t$, denoted by $z_t$, follows a 2-dimensional normal random walk:

\[\begin{aligned} + & p(z_t \mid z_{t - 1}) = \mathcal{N}(z_t \mid z_{t-1},~\mathrm{I}_{2}),\\ +\end{aligned}\]

where $\mathrm{I}_2$ denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements $y_t$ as a noisy set of the distances between WALL-E and the beacons, specified by $s_i$:

\[\begin{aligned} + & p(y_t \mid z_t) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~\mathrm{I}_{3}\! \right . \right)\!. +\end{aligned}\]

The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:

# function to compute distance to beacons
+function compute_distances(z)    
+    distance1 = norm(z - beacon_locations[1,:])
+    distance2 = norm(z - beacon_locations[2,:])
+    distance3 = norm(z - beacon_locations[3,:])
+    distances = [distance1, distance2, distance3]
+end;
@model function random_walk_model(nr_observations)
+    
+    # specify precision matrices
+    W = diageye(2)
+    R = diageye(3)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], W)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;

Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.

Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:

    compute_distances(z) -> CVI(..., Val(false), ...)

This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.

@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)
+    compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)
+end;

NOTE: You can try out different meta for approximating the nonlinearity, e.g.

@meta function random_walk_linear_meta()
+    compute_distances(z) -> Linearization()
+end;
@meta function random_walk_unscented_meta()
+    compute_distances(z) -> Unscented()
+end;
results_fast = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),
+);
results_accuracy = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1000, 100, StableRNG(42)),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),
+);

After running this fast inference procedure, the engineers plot the results and evaluate the performance:

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_fast.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Fast (1 sample, 3 iterations)"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot beacon and actual and estimated location of WALL-E (accurate inference)
+p2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_accuracy.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Accurate (1000 samples, 100 iterations)"); p2.series_list[end][:label] = "estimated location ±2σ"
+
+plot(p1, p2, size=(1200, 500))

The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, $Q$ and $R$ respectively. They did this by adding Wishart priors to those matrices:

\[\begin{aligned} + & p(Q) = \mathcal{W}(Q \mid 3, \mathrm{I}_2), \\ + & p(R) = \mathcal{W}(R \mid 4, \mathrm{I}_3), \\ + & p(z_t \mid z_{t - 1}, Q) = \mathcal{N}(z_t \mid z_{t-1}, Q^{-1}),\\ + & p(y_t \mid z_t, R) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~R^{-1}\! \right . \right)\!. +\end{aligned}\]

@model function random_walk_model_wishart(nr_observations)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # set priors on precision matrices
+    Q ~ Wishart(3, diageye(2))
+    R ~ Wishart(4, diageye(3))
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], Q)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;
meta = @meta begin 
+    compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)
+end;

Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:

constraints = @constraints begin
+    q(z, Q, R) = q(z)q(Q)q(R)
+end;

The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.

results_wishart = infer(
+    model = random_walk_model_wishart(nr_observations),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = constraints,
+    meta = meta,
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),
+    initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))
+);

They plot the new estimates and the performance over time, and luckily WALL-E is found!

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_wishart.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot bethe free energy performance
+p2 = plot(results_wishart.free_energy, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size=(1200, 500))

diff --git a/v2.16.1/examples/advanced_examples/overview/index.html b/v2.16.1/examples/advanced_examples/overview/index.html new file mode 100644 index 000000000..301fcce10 --- /dev/null +++ b/v2.16.1/examples/advanced_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Advanced examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Advanced examples contain more complex inference problems.

  • Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.
  • Advanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.
  • Assessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.
  • Chance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.
  • Conjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.
  • Global Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.
  • Solve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.
  • Infinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.
  • Nonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors
diff --git a/v2.16.1/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html b/v2.16.1/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html new file mode 100644 index 000000000..de76b4cb7 --- /dev/null +++ b/v2.16.1/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html @@ -0,0 +1,550 @@ + +Bayesian Linear Regression Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Bayesian Linear Regression Tutorial

This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM

Part 1. Bayesian Linear Regression

John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

He records the speed and fuel consumption for the urban road which is the xdata and ydata.

function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = infer(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (a, b)
+  Free Energy:     | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184
+.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821
+, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]

He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a\mid y)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0,Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b)", c=1, legend = :topleft)
+prb = vline!(prb, [ 25 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b\mid y)", c=2, legend = :topleft)
+psb = vline!(psb, [ 25 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

a = results.posteriors[:a]
+b = results.posteriors[:b]
+
+println("Real a: ", 0.5, " | Estimated a: ", mean_var(a), " | Error: ", abs(mean(a) - 0.5))
+println("Real b: ", 25.0, " | Estimated b: ", mean_var(b), " | Error: ", abs(mean(b) - 25.0))
Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err
+or: 0.001490188462705988
+Real b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error
+: 0.18735789804394898

Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:

# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Univariate regression with unknown noise

Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. $\begin{aligned} p(y_n \mid a, b, s) &= \mathcal{N}(y_n \mid ax_n + b, s)\\ +p(s) &= \mathcal{IG}(s\mid\alpha, \theta)\\ +p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ +p(b) &= \mathcal{N}(b \mid m_b, v_b) \end{aligned}$

@model function linear_regression_unknown_noise(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    s ~ InverseGamma(1.0, 1.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = s)
+end
x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)
+
+scatter(x_data_un, y_data_un, title = "Dateset with unknown noise (mountain road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results_unknown_noise = infer(
+    model           = linear_regression_unknown_noise(length(x_data_un)), 
+    data            = (y = y_data_un, x = x_data_un), 
+    initmessages    = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars      = (a = KeepLast(), b = KeepLast(), s = KeepLast()), 
+    iterations      = 20,
+    constraints     = MeanField(),
+    initmarginals   = (s = vague(InverseGamma), ),
+    free_energy     = true
+)
Inference results:
+  Posteriors       | available for (a, b, s)
+  Free Energy:     | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125
+.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56
+, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]

Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:

plot(results_unknown_noise.free_energy, title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Below he visualizes the obtained posterior distributions for parameters:

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(a)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0, Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(b)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 25.0 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(b)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 25.0 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L"Prior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(s)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 200 ], label=L"True $s$", c = 3)
+psb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L"Posterior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(s)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 200 ], label=L"True $s$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$s$", ylabel=L"$p(s)$", ylims=[0, Inf])

He sees that in the presence of more noise the inference result is more uncertain about the actual values for $a$ and $b$ parameters.

John samples $a$ and $b$ and plot many possible regression lines on the same plot:

as = rand(results_unknown_noise.posteriors[:a], 100)
+bs = rand(results_unknown_noise.posteriors[:b], 100)
+p = scatter(x_data_un, y_data_un, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)
+end
+
+plot(p, size = (900, 400))

From this plot John can see that many lines do fit the data well and there is no definite "best" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.

Multivariate linear regression

In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.

@model function linear_regression_multivariate(dim, nr_samples)
+    a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))
+    b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))
+    W ~ InverseWishart(dim + 2, 100 * diageye(dim))
+
+    # Here is a small trick to make the example work
+    # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`
+    x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)
+    y = datavar(Vector{Float64}, nr_samples)
+    z = randomvar(nr_samples)
+
+    z .~ x .* a .+ b
+    y .~ MvNormal(mean = z, covariance = W)
+
+end

After received all the measurement records, he plots the measurements and performance index:

dim_mv = 6
+nr_samples_mv = 50
+rng_mv = StableRNG(42)
+a_mv = randn(rng_mv, dim_mv)
+b_mv = 10 * randn(rng_mv, dim_mv)
+v_mv = 100 * rand(rng_mv, dim_mv)
+
+x_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));
p = plot(title = "Multivariate linear regression", legend = :topleft)
+
+plt = palette(:tab10)
+
+data_set_label = [""]
+
+for k in 1:dim_mv
+    global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = "Measurement #$k", ms = 2, color = plt[k])
+end
+xlabel!(L"$x$")
+ylabel!(L"$y$")
+p

Before this data can be used to perform inference, John needs to change its format slightly.

x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)
+y_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);
results_mv = infer(
+    model           = linear_regression_multivariate(dim_mv, nr_samples_mv),
+    data            = (y = y_data_mv_processed, x = x_data_mv_processed),
+    initmarginals   = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),
+    initmessages    = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),
+    returnvars      = (a = KeepLast(), b = KeepLast(), W = KeepLast()),
+    free_energy     = true,
+    iterations      = 50,
+    constraints     = MeanField()
+)
Inference results:
+  Posteriors       | available for (a, b, W)
+  Free Energy:     | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7
+22, 712.341, 700.865, 690.782, 682.505  …  664.434, 664.434, 664.434, 664.4
+34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]

Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.

p = plot(title = "Multivariate linear regression", legend = :topleft, xlabel=L"$x$", ylabel=L"$y$")
+
+# how many lines to plot
+r = 50
+
+i_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))
+i_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))
+
+plt = palette(:tab10)
+
+for k in 1:dim_mv
+    x_mv_k = x_data_mv[k]
+    y_mv_k = y_data_mv[k]
+
+    for i in 1:r
+        global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])
+    end
+
+    global p = scatter!(p, x_mv_k, y_mv_k, label = "Measurement #$k", ms = 2, color = plt[k])
+end
+
+# truncate the init step
+f = plot(results_mv.free_energy[2:end], title ="Bethe free energy convergence", label = nothing, xlabel = "Iteration", ylabel = "Bethe free energy [nats]") 
+
+plot(p, f, size = (1000, 400))

He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.

i_a_mv = results_mv.posteriors[:a]
+
+ps_a = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $a_{%$k}$", xlabel=L"$a_{%$k}$", ylabel=L"$p(a_{%$k})$", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])
+
+    local m_a_mv_k = mean(i_a_mv)[k]
+    local v_a_mv_k = std(i_a_mv)[k, k]
+    
+    _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(a_{%$k})$", c=2,)
+    _p = vline!(_p, [ a_mv[k] ], label=L"True $a_{%$k}$", c = 3)
+           
+    push!(ps_a, _p)
+end
+
+plot(ps_a...)

i_b_mv = results_mv.posteriors[:b]
+
+ps_b = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $b_{%$k}$", xlabel=L"$b_{%$k}$", ylabel=L"$p(b_{%$k})$", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])
+    local m_b_mv_k = mean(i_b_mv)[k]
+    local v_b_mv_k = std(i_b_mv)[k, k]
+
+    _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(b_{%$k})$", c=2,)
+    _p = vline!(_p, [ b_mv[k] ], label=L"Real $b_{%$k}$", c = 3)
+           
+    push!(ps_b, _p)
+end
+
+plot(ps_b...)

He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.

scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L"True $s_d$")
+scatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L"$\mathrm{E}[s_d] \pm \sigma$")
+plot!(; xlabel=L"Dimension $d$", ylabel="Variance", title="Estimated variance of the noise")

Part 2. Hierarchical Bayesian Linear Regression

Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro.

The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.

Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].

The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.

# https://www.machinelearningplus.com/linear-regression-in-julia/
+# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb

Understanding the Task

Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.

In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).

Now, let's explore the data and delve deeper into the problem involved.

dataset = CSV.read("../data/hbr/osic_pulmonary_fibrosis.csv", DataFrame);
describe(dataset)
7×7 DataFrame
+ Row │ variable       mean     min                        median   max     
+    ⋯
+     │ Symbol         Union…   Any                        Union…   Any     
+    ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ Patient                 ID00007637202177411956430           ID004266
+372 ⋯
+   2 │ Weeks          31.8618  -5                         28.0     133
+   3 │ FVC            2690.48  827                        2641.0   6399
+   4 │ Percent        77.6727  28.8776                    75.6769  153.145
+   5 │ Age            67.1885  49                         68.0     88      
+    ⋯
+   6 │ Sex                     Female                              Male
+   7 │ SmokingStatus           Currently smokes                    Never sm
+oke
+                                                               3 columns om
+itted
first(dataset, 5)
5×7 DataFrame
+ Row │ Patient                    Weeks  FVC    Percent  Age    Sex      Sm
+oki ⋯
+     │ String31                   Int64  Int64  Float64  Int64  String7  St
+rin ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ ID00007637202177411956430     -4   2315  58.2536     79  Male     Ex
+-sm ⋯
+   2 │ ID00007637202177411956430      5   2214  55.7121     79  Male     Ex
+-sm
+   3 │ ID00007637202177411956430      7   2061  51.8621     79  Male     Ex
+-sm
+   4 │ ID00007637202177411956430      9   2144  53.9507     79  Male     Ex
+-sm
+   5 │ ID00007637202177411956430     11   2069  52.0634     79  Male     Ex
+-sm ⋯
+                                                                1 column om
+itted

The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.

Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:

patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)
patientinfo (generic function with 1 method)
function patientchart(dataset, patient_id; line_kws = true)
+    info = patientinfo(dataset, patient_id)
+    x = info[!, "Weeks"]
+    y = info[!, "FVC"]
+
+    p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)
+    p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = "Weeks", ylabel = "FVC")
+    
+    if line_kws
+        # Use the `GLM.jl` package to estimate linear regression
+        linearFormulae = @formula(FVC ~ Weeks)
+        linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))
+        linearPredicted = predict(linearRegressor)
+        p = plot!(p, x, linearPredicted, color = :red, lw = 3)
+    end
+
+    return p
+end
patientchart (generic function with 1 method)
p1 = patientchart(dataset, "ID00007637202177411956430")
+p2 = patientchart(dataset, "ID00009637202177434476278")
+p3 = patientchart(dataset, "ID00010637202177584971671")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.

Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:

The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].

Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling

In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the "pooled model." On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the "unpooled model," where each patient has completely separate regression lines.

In this analysis, we will adopt a middle ground approach known as "Partial pooling." Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:

Mathematically, the model is described by the following equations:

\[\begin{equation} + \begin{aligned} + \mu_\alpha &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 250000.0) \\ + \sigma_\alpha &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mu_\beta &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 9.0) \\ + \sigma_\beta &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 1.36) \\ + \alpha_i &\sim \mathcal{N}(\mathrm{mean} = \mu_\alpha, \mathrm{precision} = \sigma_\alpha) \\ + \beta &\sim \mathcal{N}(\mathrm{mean} = \mu_\beta, \mathrm{precision} = \sigma_\beta) \\ + \sigma &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mathrm{FVC}_{ij} &\sim \mathcal{N}(\mathrm{mean} = \alpha_i + t \beta_i, \mathrm{precision} = \sigma) + \end{aligned} +\end{equation}\]

where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!

Implementing this model in RxInfer is pretty straightforward:

@model function partially_pooled(patient_codes, weeks)
+    μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β ~ Normal(mean = 0.0, var = 9.0)      # Prior for the mean of β (slope)
+    σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)
+    σ_β ~ Gamma(shape = 1.75, scale = 1.36)  # Prior for the precision of β (slope)
+
+    n_codes = length(patient_codes)            # Total number of data points
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    α = randomvar(n_patients)                # Individual intercepts for each patient
+    β = randomvar(n_patients)                # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution
+        β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54)   # Prior for the standard deviation of the error term
+    
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes) # Observed FVC measurements
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+end

Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.

@constraints function partially_pooled_constraints()
+    # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent
+    q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)
+    # Assume that `μ_α`, `σ_α`, `α` are jointly independent
+    q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)
+    # Assume that `μ_β`, `σ_β`, `β` are jointly independent
+    q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)
+    # Assume that `FVC_est`, `σ` are jointly independent
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_constraints (generic function with 1 method)

These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!

Inference in the model

A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.

Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.

patient_ids          = dataset[!, "Patient"] # get the column of all patients
+patient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));
+patient_code_column  = map(patient -> patient_code_encoder[patient], patient_ids)
+
+dataset[!, :PatientCode] = patient_code_column
+
+first(patient_code_encoder, 5)
5-element Vector{Pair{InlineStrings.String31, Int64}}:
+ "ID00197637202246865691526" => 85
+ "ID00388637202301028491611" => 160
+ "ID00341637202287410878488" => 142
+ "ID00020637202178344345685" => 9
+ "ID00305637202281772703145" => 127
function partially_pooled_inference(dataset)
+
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+
+    results = infer(
+        model = partially_pooled(patient_codes, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+            σ = vague(Gamma),
+            σ_α = vague(Gamma),
+            σ_β = vague(Gamma),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100
+    )
+    
+end
partially_pooled_inference (generic function with 1 method)

We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.

In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. 

partially_pooled_inference_results = partially_pooled_inference(dataset)
Inference results:
+  Posteriors       | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)

Checking the model

Inspecting the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)
+    local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))
+end

Looks like our model learned personalized alphas and betas for each patient!

Visualizing FVC decline curves for some patients

Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.

function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)
+    info            = patientinfo(dataset, patient_id)
+    patient_code_id = encoder[patient_id]
+
+    patient_α = results.posteriors[:α][patient_code_id]
+    patient_β = results.posteriors[:β][patient_code_id]
+
+    estimated_σ = inv(mean(results.posteriors[:σ]))
+    
+    predict_weeks = range(-12, 134)
+
+    predicted = map(predict_weeks) do week
+        pm = mean(patient_α) + mean(patient_β) * week
+        pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ
+        return pm, sqrt(pv)
+    end
+    
+    p = patientchart(dataset, patient_id; kwargs...)
+    
+    return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)
+end
patientchart_bayesian (generic function with 1 method)
p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430")
+p2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278")
+p3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

The results match our expectations perfectly! Let's highlight the observations:

  • The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.

  • The model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.

  • Additionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.

Computing the modified Laplace Log Likelihood and RMSE

As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.

To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:

\[\begin{equation} + \begin{aligned} + \sigma_{\mathrm{clipped}} &= \max(\sigma, 70) \\ + \delta &= \min(\vert \mathrm{FVC}_{\mathrm{true}} - \mathrm{FVC}_{\mathrm{pred}}\vert, 1000) \\ + \mathrm{metric} &= -\frac{\sqrt{2}\delta}{\sigma_{\mathrm{clipped}}} - \mathrm{ln}(\sqrt{2}\sigma_{\mathrm{clipped}}) \\ + \end{aligned} +\end{equation}\]

To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.

function FVC_predict(results)
+    return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s
+        return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)
+    end
+end
FVC_predict (generic function with 1 method)
function compute_rmse(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    return mean((dataset[!, "FVC"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)
+end
+
+function compute_laplace_log_likelihood(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    sigma_c = std.(FVC_predicted)
+    sigma_c[sigma_c .< 70] .= 70
+    delta = abs.(mean.(FVC_predicted) .- dataset[!, "FVC"])
+    delta[delta .> 1000] .= 1000
+    return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))
+end
compute_laplace_log_likelihood (generic function with 1 method)
println("RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))")
RMSE: 124.0313266260767
+Laplace Log Likelihood: -6.15689374755478

What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!

Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.

Add layer to model hierarchy: Smoking Status

We can enhance the model by incorporating the column "SmokingStatus" as a pooling level, where model parameters will be partially pooled within the groups "Never smoked," "Ex-smoker," and "Currently smokes." To achieve this, we need to:

Encode the "SmokingStatus" column. Map the patient encoding to the corresponding "SmokingStatus" encodings. Refine and retrain the model with the additional hierarchical structure.

combine(groupby(dataset, "SmokingStatus"), nrow)
3×2 DataFrame
+ Row │ SmokingStatus     nrow
+     │ String31          Int64
+─────┼─────────────────────────
+   1 │ Ex-smoker          1038
+   2 │ Never smoked        429
+   3 │ Currently smokes     82
smoking_id_mapping   = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, "SmokingStatus"]))))
+smoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id
+    smoking_status = first(unique(patientinfo(dataset, patient_id)[!, "SmokingStatus"]))
+    return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]
+end)
+
+smoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));
@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)
+    μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)
+    σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+    σ_β_global ~ Gamma(shape = 1.75, scale = 1.36)  # Corresponds to half-normal with scale 3.0
+
+    n_codes = length(patient_codes) # Total number of data points
+    n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern
+    μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern
+    
+    for i in 1:n_smoking_statuses
+        μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)
+        μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)
+    end
+    
+    α = randomvar(n_patients) # Individual intercepts for each patient
+    β = randomvar(n_patients) # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)
+        β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes)
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+    
+end
+
+@constraints function partially_pooled_with_smooking_constraints()
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)
+    q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)
+    q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)
+    q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_with_smooking_constraints (generic function with 1 method)
function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+    
+    return infer(
+        model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_with_smooking_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            σ = Gamma(1.75, 45.54),
+            σ_α_global = Gamma(1.75, 45.54),
+            σ_β_global = Gamma(1.75, 1.36),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100,
+    )
+end
partially_pooled_with_smoking (generic function with 2 methods)
partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);

Inspect the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)
+    local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)
+    local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])
+    local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α_global)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β_global)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    local p5 = plot(title = "q(μ_α_smoking_status)...", legend = false)
+    local p6 = plot(title = "q(μ_β_smoking_status)...", legend = false)
+    
+    foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) 
+    foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)
+    
+    plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))
+end

Interpret smoking status model parameters

The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.

smoking_id_mapping
Dict{InlineStrings.String31, Int64} with 3 entries:
+  "Currently smokes" => 3
+  "Ex-smoker"        => 1
+  "Never smoked"     => 2
posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]
+
+println("Trend for")
+foreach(pairs(smoking_id_mapping)) do (key, id)
+    println("  $key: $(mean(posteriors_μ_β_smoking_status[id]))")
+end
Trend for
+  Currently smokes: 1.8157457671008241
+  Ex-smoker: -4.56516461765951
+  Never smoked: -4.446729680170274

Let's look at these curves for individual patients to help interpret these model results.

# Never smoked
+p1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430") 
+# Ex-smoker
+p2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278") 
+# Currently smokes
+p3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184") 
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

Review patients that currently smoke

When plotting each patient with the smoking status "Currently smokes," we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.

Depending on the purpose of the model, we can proceed in different ways:

  • If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.

  • However, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the "Currently smokes" group's parameters closer to the global parameters, or even consider merging the group with "Ex-smokers." Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.

let 
+    local plots = []
+
+    for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==("Currently smokes"), dataset)[!, "Patient"]))
+        push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))
+    end
+
+    plot(plots..., size = (1200, 1200))
+end

Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level

We calculate the metrics for the updated model and compare to the original model.

println("RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))")
RMSE: 124.7845980866563
+Laplace Log Likelihood: -6.165346437287973

Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.

References

[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541

[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.

diff --git a/v2.16.1/examples/basic_examples/Coin Toss Model/index.html b/v2.16.1/examples/basic_examples/Coin Toss Model/index.html new file mode 100644 index 000000000..0e95246f8 --- /dev/null +++ b/v2.16.1/examples/basic_examples/Coin Toss Model/index.html @@ -0,0 +1,42 @@ + +Coin toss model (Beta-Bernoulli) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Coin toss model (Beta-Bernoulli)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example, we are going to perform an exact inference for a coin toss model that can be represented as:

\[\begin{aligned} +p(\theta) &= \mathrm{Beta}(\theta|a, b),\\ +p(y_i|\theta) &= \mathrm{Ber}(y_i|\theta),\\ +\end{aligned}\]

where $y_i \in \{0, 1\}$ is a binary observation induced by Bernoulli likelihood while $\theta$ is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of $\theta$.

We start with importing all needed packages:

using RxInfer, Random

Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:

rng = MersenneTwister(42)
+n = 500
+θ_real = 0.75
+distribution = Bernoulli(θ_real)
+
+dataset = float.(rand(rng, Bernoulli(θ_real), n));
# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(4.0, 8.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+end
result = infer(
+    model = coin_model(length(dataset)), 
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
θestimated = result.posteriors[:θ]
Beta{Float64}(α=365.0, β=147.0)
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+plot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+vline!([θ_real], label="Real θ")

diff --git a/v2.16.1/examples/basic_examples/Hidden Markov Model/index.html b/v2.16.1/examples/basic_examples/Hidden Markov Model/index.html new file mode 100644 index 000000000..3f3b965e4 --- /dev/null +++ b/v2.16.1/examples/basic_examples/Hidden Markov Model/index.html @@ -0,0 +1,132 @@ + +How to train your Hidden Markov Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

How to train your Hidden Markov Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate()
+;

In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment.

First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time $t$, let's call the estimate of the Roomba's position $s_t$.

However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call $A$.

Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.

At time $t$, we will call our observations $x_t$ and encode the mapping from the Roomba's position to the observations in a matrix we call $B$. $B$ also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:

\[\begin{aligned} + s_t & \sim \mathcal{C}at(A s_{t-1}),\\ + x_t & \sim \mathcal{C}at(B s_t).\\ +\end{aligned}\]

This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices $A$ and $B$ so we can use them to track the whereabouts of our little cleaning agent.

using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots

In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).

To generate our observation data, we'll follow these steps:

  1. Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.
  2. Determine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.
  3. Determine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.
  4. Repeat steps 2-3 for as many samples as we want.

The following code implements this process and generates our observation data:

"""
+    rand_vec(rng, distribution::Categorical)
+
+This function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.
+"""
+function rand_vec(rng, distribution::Categorical) 
+    k = ncategories(distribution)
+    s = zeros(k)
+    drawn_category = rand(rng, distribution)
+    s[drawn_category] = 1.0
+    return s
+end
+
+function generate_data(n_samples; seed = 42)
+    
+    rng = MersenneTwister(seed)
+    
+    # Transition probabilities 
+    state_transition_matrix = [0.9 0.0 0.1;
+                                                        0.0 0.9 0.1; 
+                                                        0.05 0.05 0.9] 
+    # Observation noise
+    observation_distribution_matrix = [0.9 0.05 0.05;
+                                                                         0.05 0.9 0.05;
+                                                                         0.05 0.05 0.9] 
+    # Initial state
+    s_initial = [1.0, 0.0, 0.0] 
+    
+    states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states
+    observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations
+    
+    s_prev = s_initial
+    
+    for t = 1:n_samples
+        s_probvec = state_transition_matrix * s_prev
+        states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))
+        obs_probvec = observation_distribution_matrix * states[t]
+        observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))
+        s_prev = states[t]
+    end
+    
+    return observations, states
+end
generate_data (generic function with 1 method)

We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.

# Test data
+N = 100
+x_data, s_data = generate_data(N);
+
+scatter(argmax.(s_data), leg=false, xlabel="Time",yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]))

Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the $A$ and $B$ matrices we can use MatrixDirichlet priors. For the $A$-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on $A$ with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on $B$. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.

Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!

# Model specification
+@model function hidden_markov_model(n)
+    
+    A ~ MatrixDirichlet(ones(3,3))
+    B ~ MatrixDirichlet([ 10.0 1.0 1.0; 
+                                            1.0 10.0 1.0; 
+                                            1.0 1.0 10.0 ])
+    
+    s_0 ~ Categorical(fill(1.0 / 3.0, 3))
+    
+    s = randomvar(n)
+    x = datavar(Vector{Float64}, n)
+    
+    s_prev = s_0
+    
+    for t in 1:n
+        s[t] ~ Transition(s_prev, A) 
+        x[t] ~ Transition(s[t], B)
+        s_prev = s[t]
+    end
+    
+end
+
+# Constraints specification
+@constraints function hidden_markov_model_constraints()
+    q(s_0, s, A, B) = q(s_0, s)q(A)q(B)
+end
hidden_markov_model_constraints (generic function with 1 method)

Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?

We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.

Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!

imodel = hidden_markov_model(N)
+idata = (x = x_data,)
+
+imarginals = (
+    A = vague(MatrixDirichlet, 3, 3), 
+    B = vague(MatrixDirichlet, 3, 3), 
+    s = vague(Categorical, 3)
+)
+
+ireturnvars = (
+    A = KeepLast(),
+    B = KeepLast(),
+    s = KeepLast()
+)
+
+result = infer(
+    model         = imodel, 
+    data          = idata,
+    constraints   = hidden_markov_model_constraints(),
+    initmarginals = imarginals, 
+    returnvars    = ireturnvars, 
+    iterations    = 20, 
+    free_energy   = true
+);

That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over $A$) and about the uncertainty in the roombas observations (A good posterior over $B$). Let's see if it worked

println("Posterior Marginal for A:")
+mean(result.posteriors[:A])
Posterior Marginal for A:
+3×3 Matrix{Float64}:
+ 0.871955   0.0290008  0.0572283
+ 0.0349989  0.817591   0.135675
+ 0.0930457  0.153408   0.807097
println("Posterior Marginal for B:")
+mean(result.posteriors[:B])
Posterior Marginal for B:
+3×3 Matrix{Float64}:
+ 0.949636   0.0974741  0.0518997
+ 0.0244903  0.833632   0.0277884
+ 0.0258734  0.0688939  0.920312

Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. 

p1 = scatter(argmax.(s_data), 
+                        title="Inference results", 
+                        label = "Real", 
+                        ms = 6, 
+                        legend=:right,
+                        xlabel="Time" ,
+                        yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]),
+                        size=(900,550)
+                        )
+
+p1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),
+                        label = "Inferred",
+                        ms = 3
+                        )
+
+p2 = plot(result.free_energy, 
+                    label="Free energy",
+                    xlabel="Iteration Number"
+                    )
+
+plot(p1, p2, layout = @layout([ a; b ]))

Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.

diff --git a/v2.16.1/examples/basic_examples/Kalman filtering and smoothing/index.html b/v2.16.1/examples/basic_examples/Kalman filtering and smoothing/index.html new file mode 100644 index 000000000..f3d586773 --- /dev/null +++ b/v2.16.1/examples/basic_examples/Kalman filtering and smoothing/index.html @@ -0,0 +1,412 @@ + +Kalman filtering and smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Kalman filtering and smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.

We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.

We then solve an identification problem which does not have an analytical solution.

Utimately, we show how RxInfer.jl can deal with missing observations.

Gaussian Linear Dynamical System

LGSSM can be described with the following equations:

\[\begin{aligned} + p(x_i|x_{i - 1}) & = \mathcal{N}(x_i|A * x_{i - 1}, \mathcal{P}),\\ + p(y_i|x_i) & = \mathcal{N}(y_i|B * x_i, \mathcal{Q}), +\end{aligned}\]

where $x_i$ are hidden states, $y_i$ are noisy observations, $A$, $B$ are state transition and observational matrices, $\mathcal{P}$ and $\mathcal{Q}$ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, A, B, Q, P)
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(B * x[i], P))
+        x_prev = x[i]
+    end
+    
+    return x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 1234
+
+rng = MersenneTwister(1234)
+
+# We will model 2-dimensional observations with rotation matrix `A`
+# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`
+# are known and fixed for all time-steps
+θ = π / 35
+A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+B = diageye(2)
+Q = diageye(2)
+P = 25.0 .* diageye(2)
+
+# Number of observations
+n = 300;
x, y = generate_data(rng, A, B, Q, P);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.

px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+px = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)
+
+plot(px)

To create a model we use GraphPPL package and @model macro:

@model function rotate_ssm(n, x0, A, B, Q, P)
+    
+    # We create constvar references for better efficiency
+    cA = constvar(A)
+    cB = constvar(B)
+    cQ = constvar(Q)
+    cP = constvar(P)
+    
+    # `x` is a sequence of hidden states
+    x = randomvar(n)
+    # `y` is a sequence of "clamped" observations
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    x_prev = x_prior
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)
+        y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)
+        x_prev = x[i]
+    end
+
+end

To run inference we also specify prior for out first hidden state:

x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));
# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. 
+# infer(..., options = (limit_stack_depth = 500, ))`
+result = infer(
+    model = rotate_ssm(length(y), x0, A, B, Q, P), 
+    data = (y = y,),
+    free_energy = true
+);
+
+xmarginals  = result.posteriors[:x]
+logevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence
px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :teal)
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :violet)
+
+plot(px)

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:

logevidence
1-element Vector{Float64}:
+ -1882.2434870099778

We may be also interested in performance of our resulting Belief Propagation algorithm:

@benchmark infer(
+    model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), 
+    data = (y = $y,)
+)
BenchmarkTools.Trial: 142 samples with 1 evaluation.
+ Range (min … max):  27.355 ms … 90.160 ms  ┊ GC (min … max): 0.00% … 22.03
+%
+ Time  (median):     32.762 ms              ┊ GC (median):    0.00%
+ Time  (mean ± σ):   35.468 ms ±  9.416 ms  ┊ GC (mean ± σ):  6.92% ± 10.68
+%
+
+   ▃▆██▆█▄    ▁▁▁                                              
+  ████████▅▁▅▅███▁▅▇▅▅▅▁▇▅▁▅▁▁▁▅▁▁▁▁▁▁▅▁▁▁▁▁▁▁▁▅▁▁▁▁▁▁▁▁▁▁▁▁▅ ▅
+  27.4 ms      Histogram: log(frequency) by time      87.8 ms <
+
+ Memory estimate: 9.73 MiB, allocs estimate: 226250.

System Identification Problem

In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:

using RxInfer, Distributions, StableRNGs, Plots
function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)
+
+    rng = StableRNG(seed)
+
+    real_x = Vector{Float64}(undef, n)
+    real_w = Vector{Float64}(undef, n)
+    real_y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))
+        real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))
+        real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))
+
+        x_i_min = real_x[i]
+        w_i_min = real_w[i]
+    end
+    
+    return real_x, real_w, real_y
+end
generate_data (generic function with 2 methods)

The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.

Combination 1: y = x + w

In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:

n = 250
+real_x, real_w, real_y = generate_data(+, n);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, real_x, label = "x")
+pl = plot!(pl, real_w, label = "w")
+
+pr = plot(title = "Combined y = x + w")
+pr = scatter!(pr, real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:

@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x = randomvar(n)
+    w = randomvar(n)
+    s = randomvar(n)
+    y = datavar(Float64, n)
+    
+    x_i_min = x0
+    w_i_min = w0
+    
+    for i in 1:n
+        x[i] ~ Normal(mean = x_i_min, precision = τ_x)
+        w[i] ~ Normal(mean = w_i_min, precision = τ_w)
+        s[i] ~ f(x[i], w[i])
+        y[i] ~ Normal(mean = s[i], precision = τ_y)
+        
+        x_i_min = x[i]
+        w_i_min = w[i]
+    end
+    
+end

RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:

constraints = @constraints begin 
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y
+)
+Options:
+  warn = true

The next step is to assign priors, initialise needed messages and marginals and call the inference function:

m_x_0, τ_x_0 = -20.0, 1.0
+m_w_0, τ_w_0 = 20.0, 1.0
+
+# We set relatively strong priors for random walk noise components
+# and sort of vague prior for the noise of the observations
+a_x, b_x = 0.01, 0.01var(real_x)
+a_w, b_w = 0.01, 0.01var(real_w)
+a_y, b_y = 1.0, 1.0
+
+# We set relatively strong priors for messages
+xinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))
+winit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))
+
+imessages = (x = xinit, w = winit)
+imarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))
+
+result = infer(
+    model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),
+    data  = (y = real_y,), 
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = imessages, 
+    initmarginals = imarginals, 
+    iterations = 50
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)

Let's examine our inference results:

τ_x_marginals = result.posteriors[:τ_x]
+τ_w_marginals = result.posteriors[:τ_w]
+τ_y_marginals = result.posteriors[:τ_y]
+
+smarginals = result.posteriors[:s]
+xmarginals = result.posteriors[:x]
+wmarginals = result.posteriors[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.

Combination 2: y = min(x, w)

In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:

# Smoothed version of `min` without zero-ed derivatives
+function smooth_min(x, y)    
+    if x < y
+        return x + 1e-4 * y
+    else
+        return y + 1e-4 * x
+    end
+end
smooth_min (generic function with 1 method)

RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:

min_meta = @meta begin 
+    # In this example we are going to use a simple `Linearization` method
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true
n = 200
+min_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, min_real_x, label = "x")
+pl = plot!(pl, min_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, min_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

min_m_x_0, min_τ_x_0 = -1.0, 1.0
+min_m_w_0, min_τ_w_0 = 1.0, 1.0
+
+min_a_x, min_b_x = 1.0, 1.0
+min_a_w, min_b_w = 1.0, 1.0
+min_a_y, min_b_y = 1.0, 1.0
+
+min_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))
+min_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))
+
+min_result = infer(
+    model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),
+    data  = (y = min_real_y,), 
+    meta = min_meta,
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = min_imessages, 
+    initmarginals = min_imarginals, 
+    iterations = 100
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)
min_τ_x_marginals = min_result.posteriors[:τ_x]
+min_τ_w_marginals = min_result.posteriors[:τ_w]
+min_τ_y_marginals = min_result.posteriors[:τ_y]
+
+min_smarginals = min_result.posteriors[:s]
+min_xmarginals = min_result.posteriors[:x]
+min_wmarginals = min_result.posteriors[:w]
+
+px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, min_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, min_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, min_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks).

Online (filtering) identification: y = min(x, w)

Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:

@model function rx_identification(f)
+    
+    # We are going to continuosly update our priors
+    # based on new posteriors
+    m_x_0 = datavar(Float64) 
+    τ_x_0 = datavar(Float64)
+    m_w_0 = datavar(Float64) 
+    τ_w_0 = datavar(Float64)
+    a_x   = datavar(Float64) 
+    b_x   = datavar(Float64)
+    a_y   = datavar(Float64) 
+    b_y   = datavar(Float64)
+    a_w   =  datavar(Float64) 
+    b_w   = datavar(Float64)
+    s     = randomvar()
+    y     = datavar(Float64)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x ~ Normal(mean = x0, precision = τ_x)
+    w ~ Normal(mean = w0, precision = τ_w)
+
+    s ~ f(x, w)
+    y ~ Normal(mean = s, precision = τ_y)
+    
+end

We impose structured mean-field assumption for this model as well:

rx_constraints = @constraints begin 
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ
+_y)
+Options:
+  warn = true

Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:

autoupdates = @autoupdates begin 
+    m_x_0, τ_x_0 = mean_precision(q(x))
+    m_w_0, τ_w_0 = mean_precision(q(w))
+    a_x = shape(q(τ_x)) 
+    b_x = rate(q(τ_x))
+    a_y = shape(q(τ_y))
+    b_y = rate(q(τ_y))
+    a_w = shape(q(τ_w)) 
+    b_w = rate(q(τ_w))
+end
(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_
+x = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_
+y)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))

As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):

rx_meta = @meta begin 
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true

Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:

n = 300
+rx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, rx_real_x, label = "x")
+pl = plot!(pl, rx_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

engine = infer(
+    model         = rx_identification(smooth_min),
+    constraints   = rx_constraints,
+    data          = (y = rx_real_y,),
+    autoupdates   = autoupdates,
+    meta          = rx_meta,
+    returnvars    = (:x, :w, :τ_x, :τ_w, :τ_y, :s),
+    keephistory   = 1000,
+    historyvars   =  KeepLast(),
+    initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),
+    iterations    = 10,
+    free_energy = true, 
+    free_energy_diagnostics = nothing,
+    autostart     = true,
+)
RxInferenceEngine:
+  Posteriors stream    | enabled for (w, s, τ_x, τ_w, τ_y, x)
+  Free Energy stream   | enabled
+  Posteriors history   | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)
+  Free Energy history  | available
+  Enabled events       | [  ]
rx_smarginals = engine.history[:s]
+rx_xmarginals = engine.history[:x]
+rx_wmarginals = engine.history[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, rx_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = "Estimated X")
+
+px1 = plot!(px1, rx_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = "Estimated W")
+
+px2 = scatter!(px2, rx_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the "disabled" state, does not infer anything and simply increases its variance (which is expected for the random walk).

Handling Missing Data

An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.

Let us assume that the following model generates the data

\[\begin{aligned} + {x}_t &\sim \mathcal{N}\left({x}_{t-1}, 1.0\right) \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, P \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation $\hat{y}_t \in \mathrm{R}$ we sometimes will catch missing observations.

using RxInfer, Plots
@model function smoothing(n, x0)
+    
+    P ~ Gamma(shape = 0.001, scale = 0.001)
+    x_prior ~ Normal(mean = mean(x0), var = var(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ Normal(mean = x_prev, precision = 1.0)
+        y[i] ~ Normal(mean = x[i], precision = P)
+        
+        x_prev = x[i]
+    end
+
+end

We need to manually extend the set of rules to support ::Missing values

P = 1.0
+n = 250
+
+real_signal     = map(e -> sin(0.05 * e), collect(1:n))
+noisy_data      = real_signal + rand(Normal(0.0, sqrt(P)), n);
+missing_indices = 100:125
+missing_data    = similar(noisy_data, Union{Float64, Missing}, )
+
+copyto!(missing_data, noisy_data)
+
+for index in missing_indices
+    missing_data[index] = missing
+end
constraints = @constraints begin
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+Options:
+  warn = true
x0_prior = NormalMeanVariance(0.0, 1000.0)
+
+result = infer(
+    model = smoothing(n, x0_prior), 
+    data  = (y = missing_data,), 
+    constraints = constraints,
+    initmarginals = (P = Gamma(0.001, 0.001), ),
+    returnvars = (x = KeepLast(),),
+    iterations = 20
+);
plot(real_signal, label = "Noisy signal", legend = :bottomright)
+scatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = "Missing region")
+plot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = "Estimated hidden state")

diff --git a/v2.16.1/examples/basic_examples/Predicting Bike Rental Demand/index.html b/v2.16.1/examples/basic_examples/Predicting Bike Rental Demand/index.html new file mode 100644 index 000000000..c0d33b122 --- /dev/null +++ b/v2.16.1/examples/basic_examples/Predicting Bike Rental Demand/index.html @@ -0,0 +1,193 @@ + +Predicting Bike Rental Demand · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Predicting Bike Rental Demand

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer

Preamble: Enabling Predictions

RxInfer.jl facilitates predictions in two primary ways.

  1. Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.
  2. Explicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.

Example

Consider the following model:

@model function example_model()
+    y = datavar(Float64) where {allow_missing = true}
+
+    h ~ NormalMeanPrecision(0, 1.0)
+    x ~ NormalMeanPrecision(h, 1.0)
+    y ~ NormalMeanPrecision(x, 10.0)
+end
# Implicit Prediction
+result = infer(model = example_model(), data = (y = missing,))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)
# Explicit Prediction
+result = infer(model = example_model(), predictvars = (y = KeepLast(),))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)

Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.

using CSV, DataFrames, Plots

Objective

This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.

Dataset Source

Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.

# Load the data
+df = CSV.read("../data/bike_count/modified_bicycle.csv", DataFrame)
+df[1:10, :]
10×6 DataFrame
+ Row │ datetime            temp     atemp    humidity  windspeed  count
+     │ String31            Float64  Float64  Float64   Float64    Int64
+─────┼──────────────────────────────────────────────────────────────────
+   1 │ 2011-01-01 0:00:00     9.84   14.395      81.0     0.0        16
+   2 │ 2011-01-01 1:00:00     9.02   13.635      80.0     0.0        40
+   3 │ 2011-01-01 2:00:00     9.02   13.635      80.0     0.0        32
+   4 │ 2011-01-01 3:00:00     9.84   14.395      75.0     0.0        13
+   5 │ 2011-01-01 4:00:00     9.84   14.395      75.0     0.0         1
+   6 │ 2011-01-01 5:00:00     9.84   12.88       75.0     6.0032      1
+   7 │ 2011-01-01 6:00:00     9.02   13.635      80.0     0.0         2
+   8 │ 2011-01-01 7:00:00     8.2    12.88       86.0     0.0         3
+   9 │ 2011-01-01 8:00:00     9.84   14.395      75.0     0.0         8
+  10 │ 2011-01-01 9:00:00    13.12   17.425      76.0     0.0        14
# we reserve few samples for prediction
+n_future = 24
+
+X = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]
+y = Union{Float64, Missing}[df[:, "count"]...][1:end-n_future]
+
+state_dim = length(X[1]); # dimensionality of feature space

Generative Model with Priors

We present a generative model that delineates the latent dynamics of feature evolution, represented by $\mathbf{h}_t$, and their link to the bike rental counts, $\mathbf{y}_t$.

Equations and Priors

  1. Feature Dynamics with Prior:

    • Prior: $\mathbf{a} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Dynamics: $\mathbf{h}_t \sim \mathcal{N}(\mathbf{A h}_{t-1}, \mathbf{Q})$

    • \[\mathbf{A}\]

      is the transition matrix, reshaped from the prior vector $\mathbf{a}$, and $\mathbf{Q}$ represents process noise.

  2. Noisy Observations:

    • \[\mathbf{x}_t \sim \mathcal{N}(\mathbf{h}_t, \mathbf{P})\]

    • Represents the observed noisy state of the features.

  3. Count Prediction with Prior:

    • Prior: $\boldsymbol{\theta} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Prediction: $y_t \sim \mathcal{N}(\text{softplus}(\boldsymbol{\theta}^\top\mathbf{h}_t), \sigma^2)$
    • Models the bike rental count as influenced by a non-linear transformation of the hidden state.

Interpretation

  • This framework aims to simultaneously infer the transition matrix $\mathbf{A}$ and the regression parameters $\boldsymbol{\theta}$, providing a comprehensive view of the feature space dynamics and the count prediction.
  • By employing Gaussian priors on both $\mathbf{a}$ and $\boldsymbol{\theta}$, we incorporate beliefs about their distributions.
  • The inference process aims to discover these underlying dynamics, enabling predictions of both features $\mathbf{x}_t$ and counts $y_t$.
# We augument the dataset with missing entries for 24 hours ahead
+append!(X, repeat([missing], n_future))
+append!(y, repeat([missing], n_future));
# Function to perform the state transition in the model.
+# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.
+function transition(a, x)
+    nm, n = length(a), length(x)
+    m = nm ÷ n  # Calculate the number of rows for reshaping 'a' into a matrix
+    A = reshape(a, (m, n))  
+    return A * x
+end
transition (generic function with 1 method)
# The dotsoftplus function combines a dot product and softplus transformation.
+# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,
+# especially if the data suggests other forms of relationships or distributions.
+function dotsoftplus(a, x)
+    log(1 + exp(dot(a, x)))
+end
dotsoftplus (generic function with 1 method)
# model definction
+@model function bicycle_ssm(n, h0, θ0, a0, Q, P)
+
+    # `h` is a sequence of hidden states
+    h = randomvar(n)
+
+    # `x` is a sequence of observed states (features)
+    x = datavar(Vector{Float64}, n) where {allow_missing = true}
+    # `y` is a sequence of "count" bicycles
+    y = datavar(Float64, n) where {allow_missing = true}
+
+    a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))
+
+    θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))
+
+    h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))
+    h_prev = h_prior
+    
+    for i in 1:n
+        
+        h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)
+        
+        x[i] ~ MvNormal(μ=h[i], Σ=P)
+        
+        y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)
+        
+        h_prev = h[i]
+    end
+
+end
# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.
+# However, alternative methods like Unscented or CVI approximations can also be considered.
+transition_meta = @meta begin 
+    transition() -> Linearization()
+    dotsoftplus() -> Linearization()
+end
Meta specification:
+  transition() -> Linearization()
+  dotsoftplus() -> Linearization()
+Options:
+  warn = true
# We define rather uninformative priors 
+prior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))
+prior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))
+prior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))
MvNormalMeanCovariance(
+μ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0
+.0, 0.0]
+Σ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … 
+0.0 1.0]
+)
# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages
+imessages = ( h = prior_h, a = prior_a, θ = prior_θ,)
+
+bicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))
+
+result = infer(
+    model = bicycle_model,
+    data  = (y = y, x=X), 
+    options = (limit_stack_depth = 500, ), 
+    returnvars = KeepLast(),
+    initmessages = imessages,
+    meta = transition_meta,
+    iterations = 20,
+    showprogress=true,
+)
Inference results:
+  Posteriors       | available for (a, h, h_prior, θ)
+  Predictions      | available for (y, x)
# For a sake of this example, we extract only predictions
+mean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])
+mean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])
+
+mean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)
+mean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)
+mean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)
+mean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);
slice = (300, length(y))
+data = df[:, "count"][length(y)-n_future:length(y)]
+
+p = scatter(y, 
+            color=:darkblue, 
+            markerstrokewidth=0,
+            label="Observed Count", 
+            alpha=0.6)
+
+# Plotting the mean prediction with variance ribbon
+plot!(mean_y, ribbon=sqrt.(cov_y), 
+      color=:orange, 
+      fillalpha=0.3,
+      label="Predicted Mean ± Std Dev")
+
+# Adding a vertical line to indicate the start of the future prediction
+vline!([length(y)-n_future], 
+       label="Prediction Start", 
+       linestyle=:dash, 
+       linecolor=:green)
+
+# Future (unobserved) data
+plot!(length(y)-n_future:length(y), data, label="Future Count")
+
+# Adjusting the limits
+xlims!(slice)
+
+# Enhancing the plot with titles and labels
+title!("Bike Rental Demand Prediction")
+xlabel!("Time")
+ylabel!("Bike Count")
+
+# Adjust the legend
+legend=:topright
+
+# Show the final plot
+display(p)

using Plots
+
+# Define a color palette
+palette = cgrad(:viridis)
+
+# Plot the hidden states with observations
+p1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label="Hidden State 1", legend=:topleft)
+plot!(df[!, :temp], color=:grey, label="Temperature")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Temperature vs Hidden State 1")
+
+p2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label="Hidden State 2", legend=:topleft)
+plot!(df[!, :atemp], color=:grey, label="Feels-Like Temp")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="")
+xlabel!("Time")
+ylabel!("Value")
+title!("Feels-Like Temp vs Hidden State 2")
+
+p3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label="Hidden State 3", legend=:topleft)
+plot!(df[!, :humidity], color=:grey, label="Humidity")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Humidity vs Hidden State 3")
+
+p4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label="Hidden State 4", legend=:topleft)
+plot!(df[!, :windspeed], color=:grey, label="Windspeed")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Windspeed vs Hidden State 4")
+
+for p in [p1, p2, p3, p4]
+    xlims!(p, first(slice), last(slice))
+end
+
+plot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))

Conclusion

While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.

The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.

diff --git a/v2.16.1/examples/basic_examples/overview/index.html b/v2.16.1/examples/basic_examples/overview/index.html new file mode 100644 index 000000000..51aa2b71d --- /dev/null +++ b/v2.16.1/examples/basic_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Basic examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Basic examples contain "Hello World!" of Bayesian inference in RxInfer.

  • Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.
  • Bayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.
  • Kalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations
  • Predicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.
  • How to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.
diff --git a/v2.16.1/examples/overview/index.html b/v2.16.1/examples/overview/index.html new file mode 100644 index 000000000..d38c0f25f --- /dev/null +++ b/v2.16.1/examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Examples overview

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

  • Basic examples: Basic examples contain "Hello World!" of Bayesian inference in RxInfer.
  • Advanced examples: Advanced examples contain more complex inference problems.
  • Problem specific: Problem specific examples contain specialized models and inference for various domains.
diff --git a/v2.16.1/examples/problem_specific/Autoregressive Models/index.html b/v2.16.1/examples/problem_specific/Autoregressive Models/index.html new file mode 100644 index 000000000..55e63bb1b --- /dev/null +++ b/v2.16.1/examples/problem_specific/Autoregressive Models/index.html @@ -0,0 +1,311 @@ + +Autoregressive Models · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Autoregressive Models

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:

\[\begin{aligned} +p(\gamma) &= \mathrm{Gamma}(\gamma|a, b),\\ +p(\mathbf{\theta}) &= \mathcal{N}(\mathbf{\theta}|\mathbf{\mu}, \Sigma),\\ +p(x_t|\mathbf{x}_{t-1:t-k}) &= \mathcal{N}(x_t|\mathbf{\theta}^{T}\mathbf{x}_{t-1:t-k}, \gamma^{-1}),\\ +p(y_t|x_t) &= \mathcal{N}(y_t|x_t, \tau^{-1}), +\end{aligned}\]

where $x_t$ is a current state of our system, $\mathbf{x}_{t-1:t-k}$ is a sequence of $k$ previous states, $k$ is an order of autoregression process, $\mathbf{\theta}$ is a vector of transition coefficients, $\gamma$ is a precision of state transition process, $y_k$ is a noisy observation of $x_k$ with precision $\tau$.

For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.

We start with importing all needed packages:

using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters

Let's generate some synthetic dataset, we use a predefined sets of coeffcients for $k$ = 1, 3 and 5 respectively:

# The following coefficients correspond to stable poles
+coefs_ar_1 = [-0.27002517200218096]
+coefs_ar_2 = [0.4511170798064709, -0.05740081602446657]
+coefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];
function generate_ar_data(rng, n, θ, γ, τ)
+    order        = length(θ)
+    states       = Vector{Vector{Float64}}(undef, n + 3order)
+    observations = Vector{Float64}(undef, n + 3order)
+    
+    γ_std = sqrt(inv(γ))
+    τ_std = sqrt(inv(τ))
+    
+    states[1] = randn(rng, order)
+    
+    for i in 2:(n + 3order)
+        states[i]       = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])
+        observations[i] = rand(rng, Normal(states[i][1], τ_std))
+    end
+    
+    return states[1+3order:end], observations[1+3order:end]
+end
generate_ar_data (generic function with 1 method)
# Seed for reproducibility
+seed = 123
+rng  = MersenneTwister(seed)
+
+# Number of observations in synthetic dataset
+n = 500
+
+# AR process parameters
+real_γ = 1.0
+real_τ = 0.5
+real_θ = coefs_ar_5
+
+states, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);

Let's plot our synthetic dataset:

plot(first.(states), label = "Hidden states")
+scatter!(observations, label = "Observations")

Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order $k$ > 1 and for Univariate AR (reduces to simple State-Space-Model) with order $k$ = 1.

@model function lar_model(T::Type, n, order, c, τ)
+    
+     
+    # We create a sequence of random variables for hidden states
+    x = randomvar(n)
+    # As well a sequence of observartions
+    y = datavar(Float64, n)
+    
+    ct = constvar(c)
+    # We assume observation noise to be known
+    cτ = constvar(τ)
+    
+    γ  = randomvar()
+    θ  = randomvar()
+    x0 = randomvar()
+    
+    # Prior for first state
+    if T === Multivariate
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+        x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+    else
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ Normal(μ = 0.0, γ = 1.0)
+        x0 ~ Normal(μ = 0.0, γ = 1.0)
+    end
+    
+    x_prev = x0
+    
+    for i in 1:n
+        
+        x[i] ~ AR(x_prev, θ, γ) 
+        
+        if T === Multivariate
+            y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)
+        else
+            y[i] ~ Normal(μ = ct * x[i], γ = cτ)
+        end
+        
+        x_prev = x[i]
+    end
+
+end
@constraints function ar_constraints() 
+    q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)
+end
ar_constraints (generic function with 1 method)
@meta function ar_meta(artype, order, stype)
+    AR() -> ARMeta(artype, order, stype)
+end
ar_meta (generic function with 1 method)
morder  = 5
+martype = Multivariate
+mc      = ReactiveMP.ar_unit(martype, morder)
+mconstraints = ar_constraints()
+mmeta        = ar_meta(martype, morder, ARsafe())
+
+moptions = (limit_stack_depth = 100, )
+
+mmodel         = lar_model(martype, length(observations), morder, mc, real_τ)
+mdata          = (y = observations, )
+minitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))
+mreturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+# First execution is slow due to Julia's initial compilation 
+# Subsequent runs will be faster (benchmarks are below)
+mresult = infer(
+    model = mmodel, 
+    data  = mdata,
+    constraints   = mconstraints,
+    meta          = mmeta,
+    options       = moptions,
+    initmarginals = minitmarginals,
+    returnvars    = mreturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
@unpack x, γ, θ = mresult.posteriors
Dict{Symbol, Vector} with 3 entries:
+  :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)
+, Ga…
+  :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…
+  :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…

We will use different initial marginals depending on type of our AR process

p1 = plot(first.(states), label="Hidden state")
+p1 = scatter!(p1, observations, label="Observations")
+p1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label="Inferred states", legend = :bottomright)
+
+p2 = plot(mean.(γ), ribbon = std.(γ), label = "Inferred transition precision", legend = :topright)
+p2 = plot!([ real_γ ], seriestype = :hline, label = "Real transition precision")
+
+p3 = plot(mresult.free_energy, label = "Bethe Free Energy")
+
+plot(p1, p2, p3, layout = @layout([ a; b c ]))

Let's also plot a subrange of our results:

subrange = div(n,5):(div(n, 5) + div(n, 5))
+
+plot(subrange, first.(states)[subrange], label="Hidden state")
+scatter!(subrange, observations[subrange], label="Observations")
+plot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label="Inferred states", legend = :bottomright)

It is also interesting to see where our AR coefficients converge to:

let
+    pθ = plot()
+
+    θms = mean.(θ)
+    θvs = var.(θ)
+    
+    l = length(θms)
+
+    edim(e) = (a) -> map(r -> r[e], a)
+
+    for i in 1:length(first(θms))
+        pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = "Estimated θ[$i]")
+    end
+    
+    for i in 1:length(real_θ)
+        pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = "Real θ[$i]")
+    end
+    
+    plot(pθ, legend = :outertopright, size = (800, 300))
+end

println("$(length(real_θ))-order AR inference Bethe Free Energy: ", last(mresult.free_energy))
5-order AR inference Bethe Free Energy: 1024.0775661298358

We can also run a 1-order AR inference on 5-order AR data:

uorder  = 1
+uartype = Univariate
+uc      = ReactiveMP.ar_unit(uartype, uorder)
+uconstraints = ar_constraints()
+umeta        = ar_meta(uartype, uorder, ARsafe())
+
+uoptions = (limit_stack_depth = 100, )
+
+umodel         = lar_model(uartype, length(observations), uorder, uc, real_τ)
+udata          = (y = observations, )
+uinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))
+ureturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+uresult = infer(
+    model = umodel, 
+    data  = udata,
+    meta  = umeta,
+    constraints   = uconstraints,
+    initmarginals = uinitmarginals,
+    returnvars    = ureturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
println("1-order AR inference Bethe Free Energy: ", last(uresult.free_energy))
1-order AR inference Bethe Free Energy: 1025.8792949319954
if uresult.free_energy[end] > mresult.free_energy[end]
+    println("We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.")
+else
+    error("AR-1 performs better than AR-5...") 
+end
We can see that, according to final Bethe Free Energy value, in this exampl
+e 5-order AR process can describe data better than 1-order AR.

Autoregressive Moving Average Model

Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:

\[\begin{aligned} +e_t \sim \mathcal{N}(0, \gamma^{-1}) \quad +\theta &\sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \quad +\eta \sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \\ +\mathbf{h}_0 &\sim \mathcal{MN}\left(\begin{bmatrix} +e_{-1} \\ +e_{-2} +\end{bmatrix}, \mathbf{I}\right) \\ +\mathbf{h}_t &= \mathbf{S}\mathbf{h}_{t-1} + \mathbf{c} e_{t-1} \\ +\mathbf{x}_t &= \boldsymbol{\theta}^\top\mathbf{x}_{t-1} + \boldsymbol{\eta}^\top\mathbf{h}_{t} + e_t +\end{aligned}\]

where shift matrix $\mathbf{S}$ is

\[\begin{aligned} +\mathbf{S} = \begin{pmatrix} +0 & 0 \\ +1 & 0 +\end{pmatrix} +\end{aligned}\]

and unit vector $\mathbf{c}$:

\[\begin{aligned} +\mathbf{c}=[1, 0] +\end{aligned}\]

when MA order is $2$

In this way, $\mathbf{h}_t$ containing errors $e_t$ can be viewed as hidden state.

In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., $\boldsymbol{\eta}^\top\mathbf{h}_{t}$, (2) induced by errors $e_t$ that prevents analytical update of precision parameter $\gamma$ (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.

# Load packages
+using RxInfer, LinearAlgebra, CSV, DataFrames, Plots
# Define shift function
+function shift(dim)
+    S = Matrix{Float64}(I, dim, dim)
+    for i in dim:-1:2
+           S[i,:] = S[i-1, :]
+    end
+    S[1, :] = zeros(dim)
+    return S
+end
shift (generic function with 1 method)
@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)
+        
+    c = zeros(p); c[1] = 1.0; # AR
+    b = zeros(q); b[1] = 1.0; # MA
+    S = shift(q); # MA
+    
+    # initialize variables
+    h  = randomvar(n-1)
+    e  = randomvar(n)
+    z  = randomvar(n)
+    
+    x  = datavar(Float64, n) where { allow_missing = true }
+    
+    # priors
+    γ  ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))
+    η  ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))
+    θ  ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))
+    τ  ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))
+    
+    # initial
+    h_0  ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))
+    z[1] ~ AR(h_0, η, τ)
+    e[1] ~ Normal(mean = 0.0, precision = γ)
+
+    x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]
+    
+    h_prev = h_0
+    for t in 1:n-1
+        
+        e[t+1] ~ Normal(mean = 0.0, precision = γ)
+        h[t]   ~ S*h_prev + b*e[t]
+        z[t+1] ~ AR(h[t], η, τ)
+        x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]
+        h_prev = h[t]
+    end
+end

To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle

x_df = CSV.read("../data/arma/aal_stock.csv", DataFrame)
1259×7 DataFrame
+  Row │ date        open     high     low      close    volume    Name
+      │ Date        Float64  Float64  Float64  Float64  Int64     String3
+──────┼───────────────────────────────────────────────────────────────────
+    1 │ 2013-02-08    15.07    15.12   14.63     14.75   8407500  AAL
+    2 │ 2013-02-11    14.89    15.01   14.26     14.46   8882000  AAL
+    3 │ 2013-02-12    14.45    14.51   14.1      14.27   8126000  AAL
+    4 │ 2013-02-13    14.3     14.94   14.25     14.66  10259500  AAL
+    5 │ 2013-02-14    14.94    14.96   13.16     13.99  31879900  AAL
+    6 │ 2013-02-15    13.93    14.61   13.93     14.5   15628000  AAL
+    7 │ 2013-02-19    14.33    14.56   14.08     14.26  11354400  AAL
+    8 │ 2013-02-20    14.17    14.26   13.15     13.33  14725200  AAL
+  ⋮   │     ⋮          ⋮        ⋮        ⋮        ⋮        ⋮         ⋮
+ 1253 │ 2018-01-30    52.45    53.05   52.36     52.59   4741808  AAL
+ 1254 │ 2018-01-31    53.08    54.71   53.0      54.32   5962937  AAL
+ 1255 │ 2018-02-01    54.0     54.64   53.59     53.88   3623078  AAL
+ 1256 │ 2018-02-02    53.49    53.99   52.03     52.1    5109361  AAL
+ 1257 │ 2018-02-05    51.99    52.39   49.75     49.76   6878284  AAL
+ 1258 │ 2018-02-06    49.32    51.5    48.79     51.18   6782480  AAL
+ 1259 │ 2018-02-07    50.91    51.98   50.89     51.4    4845831  AAL
+                                                         1244 rows omitted
# we will use "close" column
+x_data = filter(!ismissing, x_df[:, 5]);
# Plot data
+plot(x_data, xlabel="day", ylabel="price", label=false)

p_order = 10 # AR
+q_order = 4 # MA
4
# Training set
+train_size = 1000
+x_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]
+x_train = Float64.(x_data[p_order+1:end])[1:train_size];
# Test set
+x_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]
+x_test = Float64.(x_data[p_order+1:end])[train_size+1:end];

Inference

# Constraints are needed for performing VMP
+arma_constraints = @constraints begin
+    q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)
+end;
# This cell defines prior knowledge for model parameters
+h_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+γ_prior = GammaShapeRate(1e4, 1.0)
+τ_prior = GammaShapeRate(1e2, 1.0)
+η_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+θ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));
# Model's graph has structural loops, hence, it requires pre-initialisation
+arma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);
+arma_imessages  = (h_0 = h_prior, h = h_prior);
+arma_meta       = ar_meta(Multivariate, q_order, ARsafe());
result = infer(
+    model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), 
+    data  = (x = x_train, ),
+    initmarginals = arma_imarginals,
+    initmessages  = arma_imessages,
+    constraints   = arma_constraints,
+    meta          = arma_meta,
+    iterations    = 50,
+    options       = (limit_stack_depth = 400, ),
+);
plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = "eₜ")

# extract posteriors
+h_posterior = result.posteriors[:h][end][end]
+γ_posterior = result.posteriors[:γ][end]
+τ_posterior = result.posteriors[:τ][end]
+η_posterior = result.posteriors[:η][end]
+θ_posterior = result.posteriors[:θ][end];

Prediction

Here we are going to use our inference results in order to predict the dataset itself

# The prediction function is aimed at approximating the predictive posterior distribution
+# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)
+function prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)
+    h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))
+    ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))
+    c = zeros(p); c[1] = 1.0
+    b = zeros(q); b[1] = 1.0
+    ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)
+    θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))
+    ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)
+    e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))
+    ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out)  
+    @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out)  
+end
prediction (generic function with 1 method)
predictions = []
+for x_prev in x_prev_test
+    push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))
+    # after every new prediction we can actually "retrain" the model to use the power of Bayesian approach
+    # we will skip this part at this notebook
+end
plot(x_test, label="test data", legend=:topleft)
+plot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label="predicted", xlabel="day", ylabel="price")

diff --git a/v2.16.1/examples/problem_specific/Gamma Mixture/index.html b/v2.16.1/examples/problem_specific/Gamma Mixture/index.html new file mode 100644 index 000000000..2d9d3534c --- /dev/null +++ b/v2.16.1/examples/problem_specific/Gamma Mixture/index.html @@ -0,0 +1,129 @@ + +Gamma Mixture Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gamma Mixture Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.

Load packages

using RxInfer, Random, StatsPlots
# create custom structure for model parameters for simplicity
+struct GammaMixtureModelParameters
+    nmixtures   # number of mixtures
+    priors_as   # tuple of priors for variable a
+    priors_bs   # tuple of priors for variable b
+    prior_s     # prior of variable s
+end

Model specification

@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)
+
+    # fetch information from struct
+    nmixtures = parameters.nmixtures
+    priors_as = parameters.priors_as
+    priors_bs = parameters.priors_bs
+    prior_s   = parameters.prior_s
+
+    # set prior on global selection variable
+    s ~ Dirichlet(probvec(prior_s))
+
+    # allocate vectors of random variables
+    as = randomvar(nmixtures)
+    bs = randomvar(nmixtures)
+
+    # set priors on variables of mixtures
+    for i in 1:nmixtures
+        as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))
+        bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))
+    end
+
+    # introduce random variables for local selection variables and data
+    z = randomvar(nobservations)
+    y = datavar(Float64, nobservations)
+
+    # convert vector to tuples for proper functioning of GammaMixture node
+    tas = tuple(as...)
+    tbs = tuple(bs...)
+
+    # specify local selection variable and data generating process
+    for i in 1:nobservations
+        z[i] ~ Categorical(s)
+        y[i] ~ GammaMixture(z[i], tas, tbs)
+    end
+    
+end
constraints = @constraints begin 
+
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+
+    q(as) = q(as[begin])..q(as[end])
+    q(bs) = q(bs[begin])..q(bs[end])
+    
+    q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])
+end
Constraints:
+  marginals form:
+    q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+    q(as) = q(as[(begin)..(end)])
+    q(bs) = q(bs[(begin)..(end)])
+Options:
+  warn = true
# specify seed and number of data points
+rng = MersenneTwister(43)
+n_samples = 2500
+
+# specify parameters of mixture model that generates the data
+# Note that mixture components have exactly the same means
+mixtures  = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]
+nmixtures = length(mixtures)
+mixing    = rand(rng, nmixtures)
+mixing    = mixing ./ sum(mixing)
+mixture   = MixtureModel(mixtures, mixing)
+
+# generate data set
+dataset = rand(rng, mixture, n_samples);
# specify priors of probabilistic model
+# NOTE: As the means of the mixtures "collide", we specify informative prior for selector variable
+nmixtures = 2
+gpriors = GammaMixtureModelParameters(
+    nmixtures,                                                    # number of mixtures
+    [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ],                         # priors on variables a
+    [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ],      # priors on variables b
+    Dirichlet(1e3*mixing)                                         # prior on variable s
+)
+
+gmodel         = gamma_mixture_model(length(dataset), gpriors)
+gdata          = (y = dataset, )
+ginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))
+greturnvars    = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())
+
+goptions = (
+     
+    default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently
+)
+
+gresult = infer(
+    model         = gmodel, 
+    data          = gdata,
+    constraints   = constraints,
+    options       = (limit_stack_depth = 100,),
+    initmarginals = ginitmarginals,
+    returnvars    = greturnvars,
+    free_energy   = true,
+    iterations    = 250, 
+    showprogress  = true
+);
# extract inferred parameters
+_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])
+_dists   = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))
+_mixing = mean(gresult.posteriors[:s])
+
+# create model from inferred parameters
+_mixture   = MixtureModel(_dists, _mixing);
# report on outcome of inference
+println("Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))")
+println("Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))")
+println("========")
+println("Generated mixing: $(mixing)")
+println("Inferred mixing: $(_mixing)")
Generated means: 0.3333333333333333 and 0.33333333333333337
+Inferred means: 0.33822470398804994 and 0.33305534672666653
+========
+Generated mixing: [0.18923488676601088, 0.8107651132339891]
+Inferred mixing: [0.11395888467453213, 0.8860411153254679]
# plot results
+p1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p1 = plot!(mixture, label=false, title="Generated mixtures", linewidth=3.0)
+
+p2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p2 = plot!(_mixture, label=false, title="Inferred mixtures", linewidth=3.0)
+
+# evaluate the convergence of the algorithm by monitoring the BFE
+p3 = plot(gresult.free_energy, label=false, xlabel="iterations", title="Bethe FE")
+
+plot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))

diff --git a/v2.16.1/examples/problem_specific/Gaussian Mixture/index.html b/v2.16.1/examples/problem_specific/Gaussian Mixture/index.html new file mode 100644 index 000000000..091c3fa48 --- /dev/null +++ b/v2.16.1/examples/problem_specific/Gaussian Mixture/index.html @@ -0,0 +1,170 @@ + +Gaussian Mixture · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gaussian Mixture

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.

Load packages

using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings

Univariate Gaussian Mixture Model

Consider the data set of length $N$ observed below.

function generate_univariate_data(nr_samples; rng = MersenneTwister(123))
+
+    # data generating parameters
+    class        = [1/3, 2/3]
+    mean1, mean2 = -10, 10
+    precision    = 1.777
+
+    # generate data
+    z = rand(rng, Categorical(class), nr_samples)
+    y = zeros(nr_samples)
+    for k in 1:nr_samples
+        y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))
+    end
+
+    return y
+
+end;
data_univariate = generate_univariate_data(100)
+histogram(data_univariate, bins=50, label="data", normed=true)
+xlims!(minimum(data_univariate), maximum(data_univariate))
+ylims!(0, Inf)
+ylabel!("relative occurrence [%]")
+xlabel!("y")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, w, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(w_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Beta}(s \mid \alpha_s, \beta_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \sigma_k^2) \\ p(w_{k}) &= \Gamma(w_k \mid \alpha_k, \beta_k) \\ + p(z_n \mid s) &= \mathrm{Ber}(z_n \mid s) \\ + p(y_n \mid m, w, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, w_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $w = \{ w_1, w_2, \ldots, w_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

Here we implement the following model with uninformative values for the hyperparameters as

@model function univariate_gaussian_mixture_model(nr_samples)
+    
+    s ~ Beta(1.0, 1.0)
+    
+    m1 ~ Normal(mean = -2.0, var = 1e3)
+    w1 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    m2 ~ Normal(mean = 2.0, var = 1e3)
+    w2 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    z = randomvar(nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    for n in 1:nr_samples
+        z[n] ~ Bernoulli(s)
+        y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, w \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, w \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(w_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Beta}(s \mid \hat{\alpha}_s, \hat{\beta}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\sigma}^2_k) \\ + q(w_k) &= \Gamma (w_k \mid \hat{\alpha}_k, \hat{\beta}_k) \\ + q(z_n) &= \mathrm{Ber}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

results_univariate = infer(
+    model = univariate_gaussian_mixture_model(length(data_univariate)), 
+    constraints = MeanField(),
+    data  = (y = data_univariate,), 
+    initmarginals = (
+        s  = vague(Beta), 
+        m1 = NormalMeanVariance(-2.0, 1e3), 
+        m2 = NormalMeanVariance(2.0, 1e3), 
+        w1 = vague(GammaShapeRate), 
+        w2 = vague(GammaShapeRate)
+    ), 
+    iterations  = 10, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m2, m1, s, w2, w1, z)
+  Free Energy:     | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.
+277, 135.277, 135.277, 135.277, 135.277]

Results

Below the inference results can be seen as a function of the iterations

mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L"posterior $m_1$")
+mp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L"posterior $m_2$")
+mp = plot!(mp, [ -10 ], seriestype = :hline, label = L"true $m_1$")
+mp = plot!(mp, [ 10 ], seriestype = :hline, label = L"true $m_2$")
+
+wp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L"posterior $w_1$", legend = :bottomright, ylim = (-1, 3))
+wp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L"posterior $w_2$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_1$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_2$")
+
+swp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L"posterior $s$")
+swp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L"true $s$")
+
+fep = plot(results_univariate.free_energy, label = "Free Energy", legend = :topright)
+
+plot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))
+xlabel!("iteration")

Multivariate Gaussian Mixture Model

The above example can also be extended to the multivariate case. Consider the data set below

function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))
+
+    L         = 50.0
+    nr_mixtures = 6
+
+    probvec = normalize!(ones(nr_mixtures), 1)
+
+    switch = Categorical(probvec)
+
+    gaussians = map(1:nr_mixtures) do index
+        angle      = 2π / nr_mixtures * (index - 1)
+        basis_v    = L * [ 1.0, 0.0 ]
+        R          = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]
+        mean       = R * basis_v 
+        covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))
+        return MvNormal(mean, covariance)
+    end
+
+    z = rand(rng, switch, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+
+    for n in 1:nr_samples
+        y[n] = rand(rng, gaussians[z[n]])
+    end
+
+    return y
+
+end;
data_multivariate = generate_multivariate_data(500)
+
+sdim(n) = (a) -> map(d -> d[n], a) # helper function
+scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)
+xlabel!(L"y_1")
+ylabel!(L"y_2")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, W, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(W_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Dir}(s \mid \alpha_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \Sigma_k) \\ p(W_{k}) &= \mathcal{W}(W_k \mid V_k, \nu_k) \\ + p(z_n \mid s) &= \mathrm{Cat}(z_n \mid s) \\ + p(y_n \mid m, W, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, W_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $W = \{ W_1, W_2, \ldots, W_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)
+    
+    z = randomvar(nr_samples)
+    m = randomvar(nr_mixtures)
+    w = randomvar(nr_mixtures)
+    y = datavar(Vector{Float64}, nr_samples)
+    
+    for k in 1:nr_mixtures        
+        m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])
+        w[k] ~ Wishart(3, 1e2*diagm(ones(2)))
+    end
+    
+    s ~ Dirichlet(ones(nr_mixtures))
+    
+    means = tuple(m...)
+    precs = tuple(w...)
+    
+    for n in 1:nr_samples
+        z[n] ~ Categorical(s) 
+        y[n] ~ NormalMixture(z[n], means, precs)
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, W \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, W \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(W_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Dir}(s \mid \hat{\alpha}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\Sigma}_k) \\ + q(w_k) &= \mathcal{W}(W_k \mid \hat{V}_k, \hat{\nu}_k) \\ + q(z_n) &= \mathrm{Cat}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

rng = MersenneTwister(121)
+m = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]
+results_multivariate = infer(
+    model = multivariate_gaussian_mixture_model(
+        6, 
+        length(data_multivariate), 
+        m,
+        [diagm(1e2 * ones(2)) for k in 1:6]
+    ), 
+    data  = (y = data_multivariate,), 
+    constraints   = MeanField(),
+    initmarginals = (
+        s = vague(Dirichlet, 6), 
+        m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], 
+        w = Wishart(3, diagm(1e2 * ones(2)))
+    ), 
+    iterations  = 50, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m, w, s, z)
+  Free Energy:     | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49  …  3894.49, 3894.49, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]

Results

Below the inference results can be seen

p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title="Data", xlims=(-75, 75), ylims=(-75, 75))
+p_result = plot(xlims = (-75, 75), ylims = (-75, 75), title="Inference result", legend=false, colorbar = false)
+for (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])
+    gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))
+    global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title="Inference result", legend=false, levels = 7, colorbar = false)
+end
+p_fe = plot(results_multivariate.free_energy, label = "Free Energy")
+
+plot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))

diff --git a/v2.16.1/examples/problem_specific/Hierarchical Gaussian Filter/index.html b/v2.16.1/examples/problem_specific/Hierarchical Gaussian Filter/index.html new file mode 100644 index 000000000..cbcc3c164 --- /dev/null +++ b/v2.16.1/examples/problem_specific/Hierarchical Gaussian Filter/index.html @@ -0,0 +1,145 @@ + +Hierarchical Gaussian Filter · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Hierarchical Gaussian Filter

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).

Simple HGF model can be defined as:

\[\begin{aligned} + x^{(j)}_k & \sim \, \mathcal{N}(x^{(j)}_{k - 1}, f_k(x^{(j - 1)}_k)) \\ + y_k & \sim \, \mathcal{N}(x^{(j)}_k, \tau_k) +\end{aligned}\]

where $j$ is an index of layer in hierarchy, $k$ is a time step and $f_k$ is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with $f_k = \exp(\kappa x + \omega)$ variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:

\[\begin{aligned} + z_k & \sim \, \mathcal{N}(z_{k - 1}, \mathcal{\tau_z}) \\ + x_k & \sim \, \mathcal{N}(x_{k - 1}, \exp(\kappa z_k + \omega)) \\ + y_k & \sim \, \mathcal{N}(x_k, \mathcal{\tau_y}) +\end{aligned}\]

In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.

For simplicity we will consider $\tau_z$, $\tau_y$, $\kappa$ and $\omega$ known and fixed, but there are no principled limitations to make them random variables too.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, k, w, zv, yv)
+    z_prev = 0.0
+    x_prev = 0.0
+
+    z = Vector{Float64}(undef, n)
+    v = Vector{Float64}(undef, n)
+    x = Vector{Float64}(undef, n)
+    y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        z[i] = rand(rng, Normal(z_prev, sqrt(zv)))
+        v[i] = exp(k * z[i] + w)
+        x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))
+        y[i] = rand(rng, Normal(x[i], sqrt(yv)))
+
+        z_prev = z[i]
+        x_prev = x[i]
+    end 
+    
+    return z, x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 42
+
+rng = MersenneTwister(seed)
+
+# Parameters of HGF process
+real_k = 1.0
+real_w = 0.0
+z_variance = abs2(0.2)
+y_variance = abs2(0.1)
+
+# Number of observations
+n = 300
+
+z, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.

let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    scatter!(px, 1:n, y, label = "y_i", color = :red, ms = 2, alpha = 0.2)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

To create a model we use the @model macro:

# We create a single-time step of corresponding state-space process to
+# perform online learning (filtering)
+@model function hgf(real_k, real_w, z_variance, y_variance)
+    
+    # Priors from previous time step for `z`
+    zt_min_mean = datavar(Float64)
+    zt_min_var  = datavar(Float64)
+    
+    # Priors from previous time step for `x`
+    xt_min_mean = datavar(Float64)
+    xt_min_var  = datavar(Float64)
+
+    zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)
+    xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)
+
+    # Higher layer is modelled as a random walk 
+    zt ~ NormalMeanVariance(zt_min, z_variance)
+    
+    # Lower layer is modelled with `GCV` node
+    gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)
+    
+    # Noisy observations 
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(xt, y_variance)
+    
+    return gcvnode
+end
+
+@constraints function hgfconstraints() 
+    q(xt, zt, xt_min) = q(xt, xt_min)q(zt)
+end
+
+@meta function hgfmeta()
+    # Lets use 31 approximation points in the Gauss Hermite cubature approximation method
+    GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) 
+end
hgfmeta (generic function with 1 method)
function run_inference(data, real_k, real_w, z_variance, y_variance)
+
+    autoupdates   = @autoupdates begin
+        zt_min_mean, zt_min_var = mean_var(q(zt))
+        xt_min_mean, xt_min_var = mean_var(q(xt))
+    end
+
+    return infer(
+        model         = hgf(real_k, real_w, z_variance, y_variance),
+        constraints   = hgfconstraints(),
+        meta          = hgfmeta(),
+        data          = (y = data, ),
+        autoupdates   = autoupdates,
+        keephistory   = length(data),
+        historyvars    = (
+            xt = KeepLast(),
+            zt = KeepLast()
+        ),
+        initmarginals = (
+            zt = NormalMeanVariance(0.0, 5.0),
+            xt = NormalMeanVariance(0.0, 5.0),
+        ), 
+        iterations    = 5,
+        free_energy   = true,
+        autostart     = true,
+        callbacks     = (
+            after_model_creation = (model, returnval) -> begin 
+                gcvnode = returnval
+                setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))
+            end,
+        )
+    )
+end
run_inference (generic function with 1 method)
result = run_inference(y, real_k, real_w, z_variance, y_variance);
+
+mz = result.history[:zt];
+mx = result.history[:xt];
let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = "estimated z_i", color = :teal)
+    
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = "estimated x_i", color = :violet)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:

plot(result.free_energy_history, label = "Bethe Free Energy")

As we can see BetheFreeEnergy converges nicely to a stable point.

At final, lets check the overall performance of our resulting Variational Message Passing algorithm:

@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)
BenchmarkTools.Trial: 37 samples with 1 evaluation.
+ Range (min … max):  116.366 ms … 196.439 ms  ┊ GC (min … max): 0.00% … 0.0
+0%
+ Time  (median):     134.625 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   137.513 ms ±  14.948 ms  ┊ GC (mean ± σ):  1.41% ± 2.7
+1%
+
+            ▁  █▁▆▁                                              
+  ▄▁▄▁▁▄▁▁▇▇█▄▇████▄▁▁▁▄▄▁▄▁▁▁▁▁▁▁▄▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▄▁▁▁▁▁▁▁▄ ▁
+  116 ms           Histogram: frequency by time          196 ms <
+
+ Memory estimate: 18.78 MiB, allocs estimate: 456888.
diff --git a/v2.16.1/examples/problem_specific/Invertible Neural Network Tutorial/index.html b/v2.16.1/examples/problem_specific/Invertible Neural Network Tutorial/index.html new file mode 100644 index 000000000..829cf1d36 --- /dev/null +++ b/v2.16.1/examples/problem_specific/Invertible Neural Network Tutorial/index.html @@ -0,0 +1,293 @@ + +Invertible neural networks: a tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Invertible neural networks: a tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Table of contents

  1. Introduction
  2. Model specification
  3. Model compilation
  4. Probabilistic inference
  5. Parameter estimation

Introduction

Load required packages

Before we can start, we need to import some packages:

using RxInfer
+using Random
+using StableRNGs
+
+using ReactiveMP        # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality
+using LinearAlgebra     # only used for some matrix specifics
+using Plots             # only used for visualisation
+using Distributions     # only used for sampling from multivariate distributions
+using Optim             # only used for parameter optimisation

Model specification

Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as 

model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Alternatively, the input_dim can also be passed as an InputLayer layer as 

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

In the above AdditiveCouplingLayer layers the input ${\bf{x}} = [x_1, x_2, \ldots, x_N]$ is partitioned into chunks of unit length. These partitions are additively coupled to an output ${\bf{y}} = [y_1, y_2, \ldots, y_N]$ as

\[\begin{aligned} + y_1 &= x_1 \\ + y_2 &= x_2 + f_1(x_1) \\ + \vdots \\ + y_N &= x_N + f_{N-1}(x_{N-1}) +\end{aligned}\]

Importantly, this structure can easily be converted as

\[\begin{aligned} + x_1 &= y_1 \\ + x_2 &= y_2 - f_1(x_1) \\ + \vdots \\ + x_N &= y_N - f_{N-1}(x_{N-1}) +\end{aligned}\]

\[f_n\]

is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.

A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false),
+        PermutationLayer(PermutationMatrix(2)),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Model compilation

In the current models, the layers are setup to work with the passed input dimension. This means that the function $f_n$ is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get

model
FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P
+lanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa
+yerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou
+plingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar
+FlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad
+ditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive
+MP.PlanarFlowEmpty{1}(),), 1)))

The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):

  • FlowModel - specifies that we are dealing with a flow model.
  • 3 - Number of layers.
  • Tuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.
  • Tuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions $f_n$.
  • PermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].

From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as

compiled_model = compile(model)
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(1.2018526210096325, -0.13275455
+874928943, -0.8599072121890323),), 1), PermutationLayer{Int64}(2, [0 1; 1 0
+]), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFl
+ow{Float64, Float64}(-1.1996171058581517, 0.8453788042976358, 2.35925874964
+65023),), 1)))

Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.

compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361
+28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323
+52386),), 1)))

Probabilistic inference

We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.

function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)
+
+    rng = StableRNG(seed)
+    
+    # specify latent sampling distribution
+    dist = MvNormal([1.5, 0.5], I)
+
+    # sample from the latent distribution
+    x = rand(rng, dist, nr_samples)
+
+    # transform data
+    y = zeros(Float64, size(x))
+    for k = 1:nr_samples
+        y[:,k] .= ReactiveMP.forward(model, x[:,k])
+    end
+
+    # return data
+    return y, x
+
+end;
# generate data
+y, x = generate_data(1000, compiled_model)
+
+# plot generated data
+p1 = scatter(x[1,:], x[2,:], alpha=0.3, title="Original data", size=(800,400))
+p2 = scatter(y[1,:], y[2,:], alpha=0.3, title="Transformed data", size=(800,400))
+plot(p1, p2, legend = false)

The probabilistic model for doing inference can be described as 

@model function invertible_neural_network(nr_samples::Int64)
+    
+    # initialize variables
+    z_μ   = randomvar()
+    z_Λ   = randomvar()
+    x     = randomvar(nr_samples)
+    y_lat = randomvar(nr_samples)
+    y     = datavar(Vector{Float64}, nr_samples)
+
+    # specify prior
+    z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))
+    z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)
+
+        # specify transformed latent value
+        y_lat[k] ~ Flow(x[k])
+
+        # specify observations
+        y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))
+
+    end
+
+    # return variables
+    return z_μ, z_Λ, x, y_lat, y
+
+end;

Here the model is passed inside a meta data object of the flow node. Inference then resorts to

observations = [y[:,k] for k=1:size(y,2)]
+
+fmodel         = invertible_neural_network(length(observations))
+data          = (y = observations, )
+initmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))
+returnvars    = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())
+
+constraints = @constraints begin
+    q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)
+end
+
+@meta function fmeta(model)
+    compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
+    Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). 
+                                               # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))
+end
+
+# First execution is slow due to Julia's initial compilation 
+result = infer(
+    model = fmodel, 
+    data  = data,
+    constraints   = constraints,
+    meta          = fmeta(model),
+    initmarginals = initmarginals,
+    returnvars    = returnvars,
+    free_energy   = true,
+    iterations    = 10, 
+    showprogress  = false
+)
Inference results:
+  Posteriors       | available for (z_μ, z_Λ, y_lat, x)
+  Free Energy:     | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357
+0.6, 23570.6, 23570.6, 23570.6, 23570.6]
fe_flow = result.free_energy
+zμ_flow = result.posteriors[:z_μ]
+zΛ_flow = result.posteriors[:z_Λ]
+x_flow  = result.posteriors[:x]
+y_flow  = result.posteriors[:y_lat];

As we can see, the variational free energy decreases inside of our model.

plot(1:10, fe_flow/size(y,2), xlabel="iteration", ylabel="normalized variational free energy [nats/sample]", legend=false)

If we plot a random noisy observation and its approximated transformed uncertainty we obtain:

# pick a random observation
+id = rand(StableRNG(321), 1:size(y,2))
+rand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))
+warped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');
+
+p1 = scatter(x[1,:], x[2,:], alpha=0.1, title="Latent distribution", size=(1200,500), label="generated data")
+contour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)
+scatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color="red", markershape=:x, markersize=5, label="inferred mean")
+contour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors="red", levels=1, linewidth=2, colorbar=false)
+scatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color="red", label="transformed noisy observation")
+p2 = scatter(y[1,:], y[2,:], alpha=0.1, label="generated data")
+scatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color="red", marker=:x, label="inferred mean")
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors="red", levels=1, linewidth=2, label="random noisy observation", colorba=false)
+scatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color="red", label="random noisy observation")
+plot(p1, p2, legend = true)

Parameter estimation

The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+
+    # sample weights
+    w = rand(rng, nr_samples, 2)
+
+    # sample appraisal
+    y = zeros(Float64, nr_samples)
+    for k = 1:nr_samples
+        y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)
+    end
+
+    # return data
+    return y, w
+
+end;
data_y, data_x = generate_data(50);
+scatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel="w1", ylabel="w2", colorbar=false, legend=false)

We will then specify a possible model as

# specify flow model
+model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

The corresponding probabilistic model for the binary classification task can be created as

@model function invertible_neural_network_classifier(nr_samples::Int64)
+    
+    # initialize variables
+    x_lat  = randomvar(nr_samples)
+    y_lat1 = randomvar(nr_samples)
+    y_lat2 = randomvar(nr_samples)
+    y      = datavar(Float64, nr_samples)
+    x      = datavar(Vector{Float64}, nr_samples)
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))
+
+        # specify transformed latent value
+        y_lat1[k] ~ Flow(x_lat[k])
+        y_lat2[k] ~ dot(y_lat1[k], [1, 1])
+
+        # specify observations
+        y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }
+
+    end
+
+    # return variables
+    return x_lat, x, y_lat1, y_lat2, y
+
+end;
fcmodel       = invertible_neural_network_classifier(length(data_y))
+data          = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )
+
+@meta function fmeta(model, params)
+    compiled_model = compile(model, params)
+    Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)
+end
fmeta (generic function with 2 methods)

Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as

For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.

function f(params)
+    Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure
+    result = infer(
+        model                   = fcmodel, 
+        data                    = data,
+        meta                    = fmeta(model, params),
+        free_energy             = true,
+        free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure
+        iterations              = 10, 
+        showprogress            = false
+    );
+    
+    result.free_energy[end]
+end;

Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:

res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)
  • uses finitediff and is slower/less accurate.

or

# create gradient function
+g = (x) -> ForwardDiff.gradient(f, x);
+
+# specify initial params
+params = randn(nr_params(model))
+
+# create custom optimizer (here Adam)
+optimizer = Adam(params; λ=1e-1)
+
+# allocate space for gradient
+∇ = zeros(nr_params(model))
+
+# perform optimization
+for it = 1:10000
+
+    # backward pass
+    ∇ .= ForwardDiff.gradient(f, optimizer.x)
+
+    # gradient update
+    ReactiveMP.update!(optimizer, ∇)
+
+end
+
res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)
Iter     Function value   Gradient norm 
+     0     5.888958e+02     8.943663e+02
+ * time: 5.984306335449219e-5
+   100     1.059826e+01     4.120090e+00
+ * time: 11.85617995262146
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.010332e+01
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.21e-03 ≰ 0.0e+00
+    |x - x'|/|x'|          = 5.80e-04 ≰ 0.0e+00
+    |f(x) - f(x')|         = 6.28e-03 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03
+    |g(x)|                 = 2.07e+00 ≰ 1.0e-08
+
+ * Work counters
+    Seconds run:   14  (vs limit Inf)
+    Iterations:    113
+    f(x) calls:    301
+    ∇f(x) calls:   301

optimization results are then given as

params = Optim.minimizer(res)
+inferred_model = compile(model, params)
+trans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'
+trans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])
+trans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title="original data")
+p2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title="|> warp")
+p3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title="|> dot")
+plot(p1, p2, p3, layout=(1,3), legend=false)

using StatsFuns: normcdf
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title="original labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title="predicted labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title="Classification map", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+plot(p1, p2, p3, layout=(1,3), legend=false)

diff --git a/v2.16.1/examples/problem_specific/Probit Model (EP)/index.html b/v2.16.1/examples/problem_specific/Probit Model (EP)/index.html new file mode 100644 index 000000000..0e6c92634 --- /dev/null +++ b/v2.16.1/examples/problem_specific/Probit Model (EP)/index.html @@ -0,0 +1,76 @@ + +Probit Model (EP) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Probit Model (EP)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable $x_t$ with the discrete variable $y_t$. The model is defined as:

\[\begin{aligned} + u &= 0.1 \\ + x_0 &\sim \mathcal{N}(0, 100) \\ + x_t &\sim \mathcal{N}(x_{t-1}+ u, 0.01) \\ + y_t &\sim \mathrm{Ber}(\Phi(x_t)) +\end{aligned}\]

Import packages

using RxInfer, StableRNGs, Random, Plots
+using StatsFuns: normcdf

Data generation

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+    
+    # hyper parameters
+    u = 0.1
+
+    # allocate space for data
+    data_x = zeros(nr_samples + 1)
+    data_y = zeros(nr_samples)
+    
+    # initialize data
+    data_x[1] = -2
+    
+    # generate data
+    for k = 2:nr_samples + 1
+        
+        # calculate new x
+        data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)
+        
+        # calculate y
+        data_y[k-1] = normcdf(data_x[k]) > rand(rng)
+        
+    end
+    
+    # return data
+    return data_x, data_y
+    
+end;
n = 40
40
data_x, data_y = generate_data(n);
p = plot(xlabel = "t", ylabel = "x, y")
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x")

Model specification

@model function probit_model(nr_samples::Int64)
+    
+    # allocate space for variables
+    x = randomvar(nr_samples + 1)
+    y = datavar(Float64, nr_samples)
+    
+    # specify uninformative prior
+    x[1] ~ Normal(mean = 0.0, precision = 0.01)
+    
+    # create model 
+    for k = 2:nr_samples + 1
+        x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)
+        y[k - 1] ~ Probit(x[k]) where {
+            # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge
+            # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations
+            pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) 
+        }
+    end
+    
+end;

Inference

result = infer(
+    model = probit_model(length(data_y)), 
+    data  = (y = data_y, ), 
+    iterations = 5, 
+    returnvars = (x = KeepLast(),),
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (x)
+  Free Energy:     | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]

Results

mx = result.posteriors[:x]
+
+p = plot(xlabel = "t", ylabel = "x, y", legend = :bottomright)
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x", lw = 2)
+p = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label="x (inferred mean)")
+
+f = plot(xlabel = "t", ylabel = "BFE")
+f = plot!(result.free_energy, label = "Bethe Free Energy")
+
+plot(p, f, size = (800, 400))

diff --git a/v2.16.1/examples/problem_specific/RTS vs BIFM Smoothing/index.html b/v2.16.1/examples/problem_specific/RTS vs BIFM Smoothing/index.html new file mode 100644 index 000000000..9de18f829 --- /dev/null +++ b/v2.16.1/examples/problem_specific/RTS vs BIFM Smoothing/index.html @@ -0,0 +1,242 @@ + +RTS vs BIFM Smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

RTS vs BIFM Smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

___Credits to Martin de Quincey___

This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:

  1. F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762
  2. H. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.

We perform Kalman smoothing in the linear state space model, represented by:

\[\begin{aligned} + Z_{k+1} &= A Z_k + B U_k \\ + Y_k &= C Z_k + W_k +\end{aligned}\]

with observations $Y_k$, latent states $Z_k$ and inputs $U_k$. $W_k$ is the observation noise. $A \in \mathrm{R}^{n \times n}$, $B \in \mathrm{R}^{n \times m}$ and $C \in \mathrm{R}^{d \times n}$ are the transition matrices in the model. Here $n$, $m$ and $d$ denote the dimensionality of the latent, input and output dimension, respectively.

The corresponding probabilistic model can be represented as

\[\begin{aligned} + p(y,\ z,\ u) + &= p(z_0) \prod_{k=1}^N p(y_k \mid z_k)\ p(z_k\mid z_{k-1},\ u_{k-1})\ p(u_{k-1}) \\ + &= \mathcal{N}(z_0 \mid \mu_{z_0}, \Sigma_{z_0}) \left( \prod_{k=1}^N \mathcal{N}(y_k \mid C z_k,\ \Sigma_W)\ \delta(z_k - (Az_{k-1} + Bu_{k-1})) \mathcal{N}(u_{k-1} \mid \mu_{i_{k-1}},\ \Sigma_{u_{k-1}}) \right) +\end{aligned}\]

Import packages

using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs

Data generation

function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)
+    
+    # define noise levels
+    input_noise  = 500.0
+    output_noise = 50.0
+
+    # create random generator for reproducibility
+    rng = MersenneTwister(seed)
+
+    # generate matrices, input statistics and noise matrices
+    A      = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat))                                            # size (dim_lat x dim_lat)
+    B      = rand(dim_lat, dim_in)                                                                              # size (dim_lat x dim_in)
+    C      = rand(dim_out, dim_lat)                                                                             # size (dim_out x dim_lat)
+    μu     = rand(dim_in) .* collect(1:dim_in)                                                                  # size (dim_in x 1)
+    Σu     = input_noise  .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in))))      # size (dim_in x dim_in)
+    Σy     = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out))))   # size (dim_out x dim_out)
+    Wu     = inv(Σu)
+    Wy     = inv(Σy)
+    
+    # return parameters
+    return A, B, C, μu, Σu, Σy, Wu, Wy
+
+end;
function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)
+        
+    # create random data generator
+    rng = StableRNG(seed)
+    
+    # preallocate space for variables
+    z = Vector{Vector{Float64}}(undef, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+    u = rand(rng, MvNormal(μu, Σu), nr_samples)'
+    
+    # set initial value of latent states
+    z_prev = zeros(size(A,1))
+    
+    # generate data
+    for i in 1:nr_samples
+
+        # generate new latent state
+        z[i] = A * z_prev + B * u[i,:]
+
+        # generate new observation
+        y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))
+        
+        # generate new observation
+        z_prev .= z[i]
+        
+    end
+    
+    # return generated data
+    return z, y, u
+    
+end
generate_data (generic function with 1 method)
# specify settings
+nr_samples = 200
+dim_out = 3
+dim_in = 3
+dim_lat = 25
+
+# generate parameters
+A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);
+            
+# generate data
+data_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);
+
+# visualise data
+p = Plots.plot(xlabel = "sample", ylabel = "observations")
+# plot each dimension independently
+for i in 1:dim_out
+    Plots.scatter!(p, getindex.(data_y, i), label = "y_$i", alpha = 0.5, ms = 2)
+end
+p

Model specification

@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+    
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    dim_out = size(C, 1)
+    
+    # initialize variables
+    z = randomvar(nr_samples)                 # hidden states (random variable)
+    u = randomvar(nr_samples)                 # inputs (random variable)
+    y = datavar(Vector{Float64}, nr_samples)  # outputs (observed variables)
+    
+    # set initial hidden state
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    
+    # update last/previous hidden state
+    z_prev = z_prior
+
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i] ~ MvNormalMeanPrecision(μu, Wu)
+        
+        # specify updated hidden state
+        z[i] ~ A * z_prev + B * u[i]
+        
+        # specify observation
+        y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+end
@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    
+    # initialize variables
+    z  = randomvar(nr_samples)                  # latent states
+    yt = randomvar(nr_samples)                  # latent observations
+    y  = datavar(Vector{Float64}, nr_samples)   # actual observations
+    u  = randomvar(nr_samples)                  # inputs
+    
+    # set priors
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    z_tmp   ~ BIFMHelper(z_prior) where { q = MeanField() }
+    
+    # update last/previous hidden state
+    z_prev = z_tmp
+    
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i]   ~ MvNormalMeanPrecision(μu, Wu)
+
+        # specify observation
+        yt[i]  ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }
+        y[i]   ~ MvNormalMeanPrecision(yt[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+    # set final value
+    z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))
+    
+end

Probabilistic inference

function inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+    
+    # In this task the inference is unstable and can diverge
+    meta = @meta begin 
+        *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)
+    end
+    
+    result = infer(
+        model      = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast()),
+        meta = meta
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_RTS (generic function with 1 method)
function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)
+    result = infer(
+        model      = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast())
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_BIFM (generic function with 1 method)

Experiments for 200 observations

z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+z_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);
ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state z")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state z")
+
+mz_RTS = mean.(z_RTS)
+mz_BIFM = mean.(z_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:5
+    Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state u")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state u")
+
+rdata_u = collect(eachrow(data_u))
+mu_RTS = mean.(u_RTS)
+mu_BIFM = mean.(u_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:1
+    Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

Benchmark

# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation
+# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`
+run_benchmark = false
+
+if run_benchmark
+    trials_range = 30
+    trials_n = 500
+    trials_RTS  = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+    trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+
+
+    @showprogress for k = 1 : trials_range
+
+        # generate parameters
+        local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);
+                    
+        # generate data|
+        local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);
+
+        # run inference
+        trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+        trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+
+    end
+
+    m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9
+    q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9
+    m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9
+    q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;
+
+    p = Plots.plot(ylabel = "duration [sec]", xlabel = "latent state dimension", title = "Benchmark", yscale = :log)
+    p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = "blue", label = "mean (RTS)")
+    p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = "orange", label = "mean (BIFM)")
+    Plots.savefig(p, "../pics/rts_bifm_benchmark.png")
+    p
+end

diff --git a/v2.16.1/examples/problem_specific/Simple Nonlinear Node/index.html b/v2.16.1/examples/problem_specific/Simple Nonlinear Node/index.html new file mode 100644 index 000000000..96942f04a --- /dev/null +++ b/v2.16.1/examples/problem_specific/Simple Nonlinear Node/index.html @@ -0,0 +1,67 @@ + +Simple Nonlinear Node · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Simple Nonlinear Node

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, StableRNGs

Here is an example of creating custom node with nonlinear function approximation with samplelist.

Custom node creation

struct NonlinearNode end # Dummy structure just to make Julia happy
+
+struct NonlinearMeta{R, F}
+    rng      :: R
+    fn       :: F   # Nonlinear function, we assume 1 float input - 1 float output
+    nsamples :: Int # Number of samples used in approximation
+end
@node NonlinearNode Deterministic [ out, in ]

We need to define two Sum-product message computation rules for our new custom node

  • Rule for outbound message on out edge given inbound message on in edge
  • Rule for outbound message on in edge given inbound message on out edge
  • Both rules accept optional meta object
# Rule for outbound message on `out` edge given inbound message on `in` edge
+@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin 
+    samples = rand(meta.rng, m_in, meta.nsamples)
+    return SampleList(map(meta.fn, samples))
+end
# Rule for outbound message on `in` edge given inbound message on `out` edge
+@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin     
+    return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))
+end

Model specification

After we have defined our custom node with custom rules we may proceed with a model specification:

\[\begin{aligned} +p(\theta) &= \mathcal{N}(\theta|\mu_{\theta}, \sigma_{\theta}),\\ +p(m) &= \mathcal{N}(\theta|\mu_{m}, \sigma_{m}),\\ +p(w) &= f(\theta),\\ +p(y_i|m, w) &= \mathcal{N}(y_i|m, w), +\end{aligned}\]

Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable $\theta$ through a non-linear transformation $f$ to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of $\theta$. 

@model function nonlinear_estimation(n)
+    
+    θ ~ Normal(mean = 0.0, variance = 100.0)
+    m ~ Normal(mean = 0.0, variance = 1.0)
+    
+    w ~ NonlinearNode(θ)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = m, precision = w)
+    end
+    
+end
@constraints function nconstsraints(nsamples)
+    q(θ) :: SampleList(nsamples, LeftProposal())
+    q(w) :: SampleList(nsamples, RightProposal())
+    
+    q(θ, w, m) = q(θ)q(m)q(w)
+end
nconstsraints (generic function with 1 method)
@meta function nmeta(fn, nsamples)
+    NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)
+end
nmeta (generic function with 1 method)

Here we generate some data

nonlinear_fn(x) = abs(exp(x) * sin(x))
nonlinear_fn (generic function with 1 method)
seed = 123
+rng  = StableRNG(seed)
+
+niters   = 15 # Number of VMP iterations
+nsamples = 5_000 # Number of samples in approximation
+
+n = 500 # Number of IID samples
+μ = -10.0
+θ = -1.0
+w = nonlinear_fn(θ)
+
+data = rand(rng, NormalMeanPrecision(μ, w), n);
result = infer(
+    model = nonlinear_estimation(n),
+    meta =  nmeta(nonlinear_fn, nsamples),
+    constraints = nconstsraints(nsamples),
+    data = (y = data, ), 
+    initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),
+    returnvars = (θ = KeepLast(), ),
+    iterations = niters,  
+    showprogress = true
+)
Inference results:
+  Posteriors       | available for (θ)
θposterior = result.posteriors[:θ]
SampleList(Univariate, 5000)
using Plots, StatsPlots
+
+estimated = Normal(mean_std(θposterior)...)
+
+plot(estimated, title="Posterior for θ", label = "Estimated", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))
+vline!([ θ ], label = "Real value of θ")

diff --git a/v2.16.1/examples/problem_specific/Universal Mixtures/index.html b/v2.16.1/examples/problem_specific/Universal Mixtures/index.html new file mode 100644 index 000000000..8bea8f6e1 --- /dev/null +++ b/v2.16.1/examples/problem_specific/Universal Mixtures/index.html @@ -0,0 +1,94 @@ + +Universal Mixtures · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Universal Mixtures

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Distributions, Random, Plots

John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment

\[p(y_i \mid \theta) = \mathrm{Ber}(y_i \mid \theta),\]

where $y_i \in \{0,1\}$ are the outcomes of the coin tosses, i.e. heads or tails, and where $\theta$ is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter $\theta$, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of $\theta\in[0,1]$ they come up with the prior beliefs:

\[p(\theta \mid \text{John}) = \mathrm{Beta}(\theta \mid 7, 2)\]

\[p(\theta \mid \text{Jane}) = \mathrm{Beta}(\theta \mid 2, 7)\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior beliefs")
+plot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label="P(θ) John", c=1)
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="p(θ) Jane", c=3,)

John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. 

true_coin = Bernoulli(0.25)
+nr_throws = 10
+dataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))
+nr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)
+println("experimental outcome: \n - heads: ", nr_heads, "\n - tails: ", nr_tails);
experimental outcome: 
+ - heads: 3
+ - tails: 7

For computing the posterior beliefs $p(\theta \mid y)$ about the parameter $\theta$, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:

John's model:

\[p(y, \theta \mid \text{John}) = p(\theta \mid \text{John}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_john(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's prior model over θ
+    θ ~ Beta(7.0, 2.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Jane's model:

\[p(y, \theta \mid \text{Jane}) = p(\theta \mid \text{Jane}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_jane(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify Jane's prior model over θ
+    θ ~ Beta(2.0, 7.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy $\mathrm{F}_B$ bounds the model evidence $p(y)$ as

\[\mathrm{F}_B[p,q] \geq - \ln p(y)\]

result_john = infer(
+    model = beta_model_john(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true,
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[8.96366]
result_jane = infer(
+    model = beta_model_jane(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[6.63988]

From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying $\theta$ parameter. They formulate this through the posterior distributions $p(\theta \mid y, \text{John})$ and $p(\theta \mid y, \text{Jane})$:

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior beliefs")
+plot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) John", c=1)
+plot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="p(θ|y) Jane", c=3,)

What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over $\theta$, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as

\[p(y, \theta, c \mid \text{Mary}) = p(c \mid \text{Mary}) \, p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} \prod_{i=1}^N p(y_i \mid \theta),\]

where $c$ describes the probability of John being correct as

\[p(c \mid \text{Mary}) = \mathrm{Ber}(c \mid 0.7)\]

The predictive distribution $p(\theta \mid \text{Mary})$ for $\theta$ (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over $c$ as

\[p(\theta \mid \text{Mary}) = \sum_{c\in\{0,1\}} p(c\mid\text{Mary}) p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} = 0.7 \cdot p(\theta \mid \text{John}) + 0.3 \cdot p(\theta \mid \text{Jane})\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior belief")
+plot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label="P(θ) Mary", c=1)
+plot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label="")
+plot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label="")

She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:

@model function beta_model_mary(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's and Jane's prior models over θ
+    θ_jane ~ Beta(2.0, 7.0)
+    θ_john ~ Beta(7.0, 2.0)
+
+    # specify initial guess as to who is right
+    john_is_right ~ Bernoulli(0.7) 
+
+    # specify mixture prior Distribution
+    θ ~ Mixture(john_is_right, (θ_jane, θ_john))
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

This Mixture node updates the belief over $c$ on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.

result_mary = infer(
+    model = beta_model_mary(nr_throws), 
+    data  = (y = dataset, ),
+    returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),
+    addons = AddonLogScale(),
+    postprocess = UnpackMarginalPostprocess(),
+)
Inference results:
+  Posteriors       | available for (john_is_right, θ_john, θ, θ_jane)

Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over $\theta$ also changed, and as expected the estimate from Jane was more prominent.

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior belief")
+plot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) Mary", c=1)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label="", c=3)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label="", c=3)

diff --git a/v2.16.1/examples/problem_specific/overview/index.html b/v2.16.1/examples/problem_specific/overview/index.html new file mode 100644 index 000000000..0fcf3e5b7 --- /dev/null +++ b/v2.16.1/examples/problem_specific/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Problem specific

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Problem specific examples contain specialized models and inference for various domains.

diff --git a/v2.16.1/index.html b/v2.16.1/index.html new file mode 100644 index 000000000..fdc8b7a27 --- /dev/null +++ b/v2.16.1/index.html @@ -0,0 +1,2 @@ + +Home · RxInfer.jl
GitHub

RxInfer

Julia package for automatic Bayesian inference on a factor graph with reactive message passing.

Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.

Package Features

  • User friendly syntax for specification of probabilistic models.
  • Automatic generation of message passing algorithms including
  • Support for hybrid models combining discrete and continuous latent variables.
  • Support for hybrid distinct message passing inference algorithm under a unified paradigm.
  • Factorisation and functional form constraints specification.
  • Evaluation of Bethe free energy as a model performance measure.
  • Schedule-free reactive message passing API.
  • High performance.
  • Scalability for large models with millions of parameters and observations.
  • Inference procedure is differentiable.
  • Easy to extend with custom nodes and message update rules.

Why RxInfer

Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a "variational Free Energy" cost function. For large models, manual derivation of these gradients might not be feasible, while automated "black-box" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.

RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different "what-if" scenarios and enables very efficient inference in specific cases.

Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.

How to get started?

Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.

Table of Contents

References

Ecosystem

The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:

  • ReactiveMP.jl - core package for efficient and scalable for reactive message passing
  • GraphPPL.jl - package for model and constraints specification
  • Rocket.jl - reactive programming tools

Index

diff --git a/v2.16.1/library/bethe-free-energy/index.html b/v2.16.1/library/bethe-free-energy/index.html new file mode 100644 index 000000000..5bc594189 --- /dev/null +++ b/v2.16.1/library/bethe-free-energy/index.html @@ -0,0 +1,2 @@ + +Bethe Free Energy · RxInfer.jl
GitHub

Bethe Free Energy implementation in RxInfer

The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.

Factorized model

Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, $y = (y_1, \dots, y_j, \dots, y_m)\,,$ and variables that can not be observed directly, also known as latent variables, $x = (x_1, \dots, x_i, \dots, x_n)\,.$ We then define a model that factorizes over consituent smaller factors (functions), as $f(y,x) = \prod_a f_a(y_a,x_a)\,.$

Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).

Variational Free Energy

The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, $F[q](\hat{y}) = \mathbb{E}_{q(x)}\left[\log \frac{q(x)}{f(y=\hat{y}, x)} \right]\,.$ A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.

The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.

Variational inference

The goal of variational inference is to find a variational distibution that minimizes the VFE, $q^{*}(x) = \arg\min_{q\in\mathcal{Q}} F[q](\hat{y})\,.$ This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.

For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.

Bethe approximation

Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.

A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, $q(x) \triangleq \frac{\prod_a q_a(x_a)}{\prod_i q_i(x_i)^{d_i - 1}}\,.$ The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.

The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.

The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.

Bethe Free Energy

The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as $F_B[q](\hat{y}) = \sum_a U_a[q_a](\hat{y}_a) - \sum_a H[q_a] + \sum_i (d_i - 1) H[q_i]\,.$ The first term of the BFE specifies an average energy, $U_a[q_a](\hat{y}_a) = -\mathbb{E}_{q_a(x_a)}\left[\log f_a(y_a=\hat{y}_a, x_a)\right]\,,$ which internalizes the factors of the model. The last two terms specify entropies.

Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.

For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.

For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.

Further reading

  • Pearl (1986) on the original foundations of Bayesian networks and belief propagation;
  • Yedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;
  • Dauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);
  • Senoz et al. (2021) on constraint manipulation and message passing on FFGs.
RxInfer.AbstractScoreObjective — Type
AbstractScoreObjective

Abstract type for functional objectives that can be used in the score function.

Note

score is defined in the ReactiveMP package.

source
RxInfer.BetheFreeEnergy — Type
BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)

Creates Bethe Free Energy values stream when passed to the score function.

source
RxInfer.apply_diagnostic_check — Function
apply_diagnostic_check(check, context, stream)

This function applies a check to the stream. Accepts optional context object for custom error messages.

source
diff --git a/v2.16.1/library/exported-methods/index.html b/v2.16.1/library/exported-methods/index.html new file mode 100644 index 000000000..ea1c84287 --- /dev/null +++ b/v2.16.1/library/exported-methods/index.html @@ -0,0 +1,858 @@ + +Exported methods · RxInfer.jl
GitHub

Using methods from RxInfer

In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:

using RxInfer

A nice explanation about how modules/packages work in Julia can be found in the official documentation.

In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:

import RxInfer: mean

One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:

import RxInfer: mean as mean_from_rxinfer
+import Distributions: mean as mean_from_distributions
+
+mean_from_rxinfer === mean_from_distributions
true

Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.

# It is easier to let Julia resolve names automatically
+# Julia will not overwrite `mean` that is coming from both packages
+using RxInfer, Distributions
mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`
0.0
mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`
0.0

List of available methods

Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.

Note

Some exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.

foreach(println, names(RxInfer))
@autoupdates
+@average_energy
+@call_marginalrule
+@call_rule
+@constraints
+@logscale
+@marginalrule
+@meta
+@model
+@node
+@rule
+AND
+AR
+ARMeta
+ARsafe
+ARunsafe
+AbstractActor
+AbstractActorFactory
+AbstractApproximationMethod
+AbstractFormConstraint
+AbstractMStorage
+AbstractMessage
+AbstractMixtureModel
+AbstractMvNormal
+AbstractOperator
+AbstractPipelineStage
+AbstractSubject
+AbstractSubjectFactory
+AbstractSubscribable
+AbstractVariable
+Actor
+ActorProxy
+ActorSourceProxy
+ActorTrait
+Adam
+AdditiveCouplingLayer
+AddonDebug
+AddonLogScale
+AddonMemory
+Arcsine
+ArrayLikeVariate
+ArrayObservable
+AsapScheduler
+AsyncPipelineStage
+AsyncScheduler
+AutoProposal
+AutoVar
+Autoregressive
+AverageEnergy
+BIFM
+BIFMHelper
+BIFMMeta
+BaseActorTrait
+BayesBase
+BehaviorSubject
+BehaviorSubjectFactory
+Bernoulli
+BernoulliLogit
+Beta
+BetaBinomial
+BetaPrime
+BetheFreeEnergy
+BetheFreeEnergyCheckInfs
+BetheFreeEnergyCheckNaNs
+BetheFreeEnergyDefaultChecks
+BetheFreeEnergyDefaultMarginalSkipStrategy
+Binomial
+Biweight
+BufferActor
+CTMeta
+CTransition
+CVI
+CallableTeardownLogic
+Categorical
+Cauchy
+Chernoff
+Chi
+Chisq
+CholeskyVariate
+CircularKeepActor
+ClosedProd
+CompanionMatrix
+CompanionMatrixTransposed
+CompiledFlowModel
+CompletedObservable
+CompletionActor
+CompletionActorTrait
+CompositeFormConstraint
+CompositePipelineStage
+ConnectableObservable
+ConstVariable
+ConstantBaseMeasure
+ConstraintsSpecification
+Contingency
+Continuous
+ContinuousDistribution
+ContinuousMatrixDistribution
+ContinuousMultivariateDistribution
+ContinuousMultivariateLogPdf
+ContinuousTransition
+ContinuousTransitionMeta
+ContinuousUnivariateDistribution
+ContinuousUnivariateLogPdf
+Cosine
+CountingReal
+CustomProdStrategy
+DataVariable
+DefaultConstraints
+DefaultMeta
+DefaultPostprocess
+DeltaFn
+DeltaFnNode
+DeltaMeta
+Deterministic
+DiagNormal
+DiagNormalCanon
+DifferentialEntropy
+Dirac
+Dirichlet
+DirichletMultinomial
+DiscontinuePipelineStage
+Discrete
+DiscreteDistribution
+DiscreteMatrixDistribution
+DiscreteMultivariateDistribution
+DiscreteNonParametric
+DiscreteUniform
+DiscreteUnivariateDistribution
+Distribution
+Distributions
+Domain
+DoubleExponential
+EdgeworthMean
+EdgeworthSum
+EdgeworthZ
+EmptyPipelineStage
+Epanechnikov
+Erlang
+ErrorActor
+ErrorActorTrait
+Estimator
+Exponential
+ExponentialFamily
+ExponentialFamilyDistribution
+ExponentialFamilyDistributionAttributes
+ExtraArgumentInCompleteCall
+FDist
+FactorBoundFreeEnergy
+FactorGraphModel
+FactorNodeCreationOptions
+FactorNodesCollection
+FactorizedJoint
+FastCholesky
+FaultedObservable
+FirstNotFoundException
+FisherNoncentralHypergeometric
+Flow
+FlowMeta
+FlowModel
+FoldLeftProdStrategy
+FoldRightProdStrategy
+FormConstraintCheckEach
+FormConstraintCheckLast
+FormConstraintCheckPickDefault
+ForwardDiffGrad
+Frechet
+FullFactorisation
+FullNormal
+FullNormalCanon
+FunctionActor
+FunctionObservable
+GCV
+GCVMetadata
+Gamma
+GammaDistributionsFamily
+GammaInverse
+GammaMixture
+GammaMixtureNode
+GammaShapeRate
+GammaShapeScale
+GaussHermiteCubature
+GaussLaguerreQuadrature
+GaussianDistributionsFamily
+GaussianMeanPrecision
+GaussianMeanVariance
+GaussianMixture
+GaussianMixtureNode
+GaussianWeighteMeanPrecision
+GeneralizedExtremeValue
+GeneralizedPareto
+GenericProd
+Geometric
+GraphPPL
+Gumbel
+HalfNormal
+Hypergeometric
+IMPLY
+ImportanceSamplingApproximation
+IncludeAll
+InconsistentActorWithSubscribableDataTypesError
+InconsistentSourceActorDataTypesError
+InconsistentSourceOperatorDataTypesError
+InconsistentSubjectDataTypesError
+InferableOperator
+InferableOperatorTrait
+InferenceResult
+InputLayer
+InvalidActorTrait
+InvalidActorTraitUsageError
+InvalidMultipleTeardownLogicTraitUsageError
+InvalidOperatorTrait
+InvalidOperatorTraitUsageError
+InvalidSubjectTrait
+InvalidSubjectTraitUsageError
+InvalidSubscribableTrait
+InvalidSubscribableTraitUsageError
+InvalidTeardownLogic
+InvalidTeardownLogicTraitUsageError
+InverseGamma
+InverseGaussian
+InverseWishart
+IsoNormal
+IsoNormalCanon
+JohnsonSU
+JointGaussian
+JointNormal
+JointOrderStatistics
+KSDist
+KSOneSided
+KeepActor
+KeepEach
+KeepLast
+Kolmogorov
+Kumaraswamy
+LKJ
+LKJCholesky
+LabeledObservable
+LambdaActor
+Laplace
+LaplaceApproximation
+LastNotFoundException
+LazyObservable
+LeftProposal
+LeftTypedOperator
+LeftTypedOperatorTrait
+Levy
+LimitSubscribersGuard
+Lindley
+Linearization
+LinearizedProductOf
+LocationScale
+LogNormal
+LogUniform
+LoggerActor
+LoggerPipelineStage
+Logistic
+LogitNormal
+MAX_PREGENERATED_MSTORAGE_SIZE
+MILLISECONDS_IN_SECOND
+MLEstimator
+Marginal
+Marginalisation
+MatrixBeta
+MatrixDirichlet
+MatrixDistribution
+MatrixFDist
+MatrixNormal
+MatrixReshaped
+MatrixTDist
+Matrixvariate
+MeanField
+MeanParametersSpace
+MeanToNatural
+Message
+MetaSpecification
+MissingCreateActorFactoryImplementationError
+MissingDataArgumentInNextCall
+MissingErrorArgumentInErrorCall
+MissingOnCallImplementationError
+MissingOnCompleteImplementationError
+MissingOnErrorImplementationError
+MissingOnNextImplementationError
+MissingOnScheduledSubscribeImplementationError
+MissingOnSubscribeImplementationError
+MissingOnUnsubscribeImplementationError
+MissingOperatorRightImplementationError
+Mixture
+MixtureDistribution
+MixtureModel
+MixtureNode
+MomentMatching
+Multinomial
+Multivariate
+MultivariateDistribution
+MultivariateGaussianDistributionsFamily
+MultivariateMixture
+MultivariateNormal
+MultivariateNormalDistributionsFamily
+MvGaussianMeanCovariance
+MvGaussianMeanPrecision
+MvGaussianWeightedMeanPrecision
+MvLogNormal
+MvLogitNormal
+MvNormal
+MvNormalCanon
+MvNormalKnownCov
+MvNormalMeanCovariance
+MvNormalMeanPrecision
+MvNormalMeanScalePrecision
+MvNormalWeightedMeanPrecision
+MvNormalWishart
+MvTDist
+NANOSECONDS_IN_MILLISECOND
+NANOSECONDS_IN_SECOND
+NOT
+NaturalParametersSpace
+NaturalToMean
+NegativeBinomial
+NetworkObservable
+NeverObservable
+NextActor
+NextActorTrait
+NonConstantBaseMeasure
+NonMatrixDistribution
+NoncentralBeta
+NoncentralChisq
+NoncentralF
+NoncentralHypergeometric
+NoncentralT
+NoopPostprocess
+Normal
+NormalCanon
+NormalDistributionsFamily
+NormalGamma
+NormalInverseGaussian
+NormalMeanPrecision
+NormalMeanVariance
+NormalMixture
+NormalMixtureNode
+NormalWeightedMeanPrecision
+OR
+OperatorTrait
+OperatorsComposition
+OrderStatistic
+OverrideHandler
+PGeneralizedGaussian
+Pareto
+PendingScheduler
+PendingSubject
+PendingSubjectFactory
+PermutationLayer
+PermutationMatrix
+PlanarFlow
+PointMass
+Poisson
+PoissonBinomial
+PostponeScheduler
+PreserveTypeLeftProd
+PreserveTypeProd
+PreserveTypeRightProd
+Probit
+ProbitMeta
+ProdCVI
+Product
+ProductOf
+ProxyObservable
+PushEach
+PushEachBut
+PushNew
+PushNewBut
+PushStrategy
+QQPair
+RadialFlow
+RandomVariable
+RandomVariableCreationOptions
+Rayleigh
+ReactiveMP
+RealInterval
+RecentSubject
+RecentSubjectFactory
+ReplaySubject
+ReplaySubjectFactory
+Rician
+RightProposal
+RightTypedOperator
+RightTypedOperatorTrait
+Rocket
+RxInfer
+RxInferenceEngine
+RxInferenceEvent
+SampleList
+SampleListMeta
+Sampleable
+ScheduledSubscribable
+ScheduledSubscribableTrait
+Semicircle
+ServerActor
+SimpleSubscribableTrait
+SingleObservable
+Skellam
+SkewNormal
+SkewedExponentialPower
+SkipClamped
+SkipClampedAndInitial
+SkipInitial
+SoftDot
+Soliton
+SourceProxy
+StandardBasisVector
+Stochastic
+StorageActor
+StudentizedRange
+Subject
+SubjectFactory
+SubjectTrait
+Subscribable
+SubscribableTrait
+SubstituteHandler
+SufficientStats
+SymTriangularDist
+SyncActor
+SyncActorTimedOutException
+SyncFileObservable
+TDist
+TapAfterSubscription
+TapAfterUnsubscription
+TapBeforeSubscription
+TapBeforeUnsubscription
+Teardown
+TeardownLogic
+TerminalProdArgument
+TimerObservable
+Transition
+TriangularDist
+Triweight
+Truncated
+TruncatedNormal
+TypedOperator
+TypedOperatorTrait
+UT
+Uniform
+Uninformative
+Univariate
+UnivariateDistribution
+UnivariateGMM
+UnivariateGaussianDistributionsFamily
+UnivariateMixture
+UnivariateNormalDistributionsFamily
+UnpackMarginalPostprocess
+Unscented
+UnscentedTransform
+UnspecifiedConstraints
+UnspecifiedDimension
+UnspecifiedDomain
+UnspecifiedFormConstraint
+UnspecifiedMeta
+UnsubscribableTeardownLogic
+ValidSubjectTrait
+ValueSupport
+VariableBoundEntropy
+VariablesCollection
+VariateForm
+VariationalMessage
+VoidActor
+VoidTeardown
+VoidTeardownLogic
+VonMises
+VonMisesFisher
+WalleniusNoncentralHypergeometric
+Weibull
+Wishart
+WishartDistributionsFamily
+ZeroMeanDiagNormal
+ZeroMeanDiagNormalCanon
+ZeroMeanFullNormal
+ZeroMeanFullNormalCanon
+ZeroMeanIsoNormal
+ZeroMeanIsoNormalCanon
+accumulated
+actor_extract_type
+actor_proxy!
+apply_pipeline_stage
+approximation_name
+approximation_short_name
+as_actor
+as_marginal
+as_message
+as_operator
+as_subject
+as_subscribable
+as_teardown
+as_variable
+async
+basemeasure
+buffer
+call_operator!
+call_operator_composition!
+canonform
+catch_error
+ccdf
+cdf
+censored
+cf
+cgf
+cholinv
+cholinv_logdet
+chollogdet
+cholsqrt
+circularkeep
+circvar
+clamplog
+collectLatest
+combineLatest
+combineLatestUpdates
+compile
+complete!
+completed
+component
+components
+componentwise_logpdf
+componentwise_pdf
+compute_logscale
+concat
+concat_map
+concat_map_to
+concentration
+connect
+connectable
+constrain_form
+constvar
+convert_paramfloattype
+convolve
+cor
+count
+cov
+cquantile
+create_actor
+create_model
+create_subject
+datavar
+debounce_time
+deep_eltype
+default_form_check_strategy
+default_if_empty
+default_prod_constraint
+default_prod_rule
+defer
+degree
+delay
+diageye
+dim
+dimension
+discontinue
+distribution_typewrapper
+dof
+dot
+dtanh
+entropy
+enumerate
+error!
+error_if
+error_if_empty
+error_if_not
+estimate
+exhaust_map
+expected_logdet
+factorisation
+failprob
+fastcholesky
+fastcholesky!
+faulted
+file
+filter
+filter_type
+find
+find_index
+first
+fisherinformation
+fit
+fit_mle
+from
+functional_dependencies
+functionalform
+fuse_supports
+generate
+getapproximation
+getattributes
+getbasemeasure
+getconditioner
+getconst
+getconstant
+getconstraints
+getdata
+getfisherinformation
+getlayers
+getlogpartition
+getlogscale
+getmapping
+getmarginal
+getmarginals
+getmemory
+getmeta
+getmodel
+getnaturalparameters
+getnode_ids
+getnodes
+getoptions
+getprediction
+getpredictions
+getrandom
+getsufficientstatistics
+getsupport
+getvalues
+getvardict
+getvariables
+ghcubature
+gradlogpdf
+hasconstvar
+hasdatavar
+hasfinitesupport
+hasrandomvar
+huge
+ignore
+infer
+inference
+insupport
+interfaces
+interval
+invcov
+invlogccdf
+invlogcdf
+invscale
+is_clamped
+is_initial
+is_marginalisation
+is_moment_matching
+is_point_mass_form_constraint
+isbasemeasureconstant
+isbounded
+isconnected
+isdeterministic
+isequal_typeof
+isleptokurtic
+islowerbounded
+ismesokurtic
+isplatykurtic
+isprobvec
+isproper
+isstochastic
+isupperbounded
+iterable
+keep
+kldivergence
+kurtosis
+labeled
+lambda
+laplace
+last
+lazy
+limit_subscribers
+localmarginalnames
+localmarginals
+location
+location!
+logccdf
+logcdf
+logdetcov
+logdiffcdf
+logger
+loglikelihood
+logmvbeta
+logpartition
+logpdf
+logpdf!
+logpdf_optimized
+logpdf_sampling_optimized
+lowercase
+make
+make_form_constraint
+make_node
+map
+map_to
+marginalrule
+max
+mean
+mean_cov
+mean_invcov
+mean_precision
+mean_std
+mean_var
+meandir
+meanform
+meanlogx
+median
+merge_map
+merged
+metadata
+mgf
+min
+mirrorlog
+mode
+model_name
+modes
+moment
+multicast
+mvtrigamma
+name
+ncategories
+ncomponents
+network
+never
+next!
+noop
+nr_params
+nsamples
+ntrials
+of
+on_call!
+on_complete!
+on_error!
+on_next!
+on_subscribe!
+on_unsubscribe!
+operator_right
+override
+pairwise
+parallel
+paramfloattype
+params
+params!
+partype
+pdf
+pdf!
+pdfsquaredL2norm
+precision
+probs
+probval
+probvec
+prod
+prod!
+product_distribution
+promote_paramfloattype
+promote_samplefloattype
+promote_sampletype
+promote_variate_type
+proxy
+publish
+publish_behavior
+publish_recent
+publish_replay
+qqbuild
+quantile
+race
+rand
+rand!
+randomvar
+rate
+reduce
+ref_count
+release!
+rerun
+resolve_prod_strategy
+rule
+rxinference
+safe
+sample
+sample!
+samplefloattype
+sampler
+sampletype
+sampling_optimized
+scale
+scale!
+scan
+schedule_on
+scheduled
+score
+sdtype
+server
+set!
+setTimeout
+setmarginal!
+setmarginals!
+setmessage!
+setmessages!
+shape
+share
+share_recent
+share_replay
+skewness
+skip_complete
+skip_error
+skip_next
+skipindex
+softdot
+some
+source_proxy!
+span
+sqmahal
+sqmahal!
+srcubature
+start_with
+std
+stdlogx
+storage
+subscribable_extract_type
+subscribe!
+substitute
+succprob
+sufficientstatistics
+suffstats
+sum
+support
+switch_map
+switch_map_to
+sync
+take
+take_until
+tap
+tap_on_complete
+tap_on_subscribe
+tap_on_unsubscribe
+teardown!
+throwError
+timer
+tiny
+to_array
+truncated
+tuple_with_left
+tuple_with_right
+unsubscribe!
+update!
+uppercase
+vague
+value_support
+var
+variate_form
+varlogx
+void
+voidTeardown
+weightedmean
+weightedmean_cov
+weightedmean_invcov
+weightedmean_precision
+weightedmean_std
+weightedmean_var
+weights
+with_latest
+wsample
+wsample!
+xtlog
+zipped
diff --git a/v2.16.1/library/functional-forms/index.html b/v2.16.1/library/functional-forms/index.html new file mode 100644 index 000000000..7ef73f9f7 --- /dev/null +++ b/v2.16.1/library/functional-forms/index.html @@ -0,0 +1,26 @@ + +Built-in functional form constraints · RxInfer.jl
GitHub

Built-in Functional Forms

This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.

Custom functional forms

See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.

UnspecifiedFormConstraint

Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.

@constraints begin 
+    q(x) :: Nothing # This is the default setting
+end

PointMassFormConstraint

The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. 

@constraints begin 
+    q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object
+end
RxInfer.PointMassFormConstraint — Type
PointMassFormConstraint

One of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.

Keyword arguments

  • optimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer
  • starting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point
  • boundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries

Custom optimizer callback interface

# This is an example of the `custom_optimizer` interface
+function custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # should return argmin of the -logpdf(distribution)
+end

Custom starting point callback interface

# This is an example of the `custom_starting_point` interface
+function custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # built-in optimizer expects an array, even for a univariate distribution
+    return [ 0.0 ] 
+end

Custom boundaries callback interface

# This is an example of the `custom_boundaries` interface
+function custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # returns a tuple of `lower` and `upper` boundaries
+    return (-Inf, Inf)
+end

Traits

  • is_point_mass_form_constraint = true
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = PointMass (for use in @constraints macro)
source

SampleListFormConstraint

SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.

@constraints begin 
+    q(x) :: SampleList(1000)
+    # or 
+    q(y) :: SampleList(1000, LeftProposal())
+end
RxInfer.SampleListFormConstraint — Type
SampleListFormConstraint(rng, strategy, method)

One of the form constraint objects. Approximates DistProduct with a SampleList object.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = SampleList (for use in @constraints macro)
source
RxInfer.LeftProposal — Type

Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.

source
RxInfer.RightProposal — Type

Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.

source

FixedMarginalFormConstraint

Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.

@constraints function block_updates(x_posterior = nothing) 
+    # `nothing` returns the computed posterior marginal
+    q(x) :: Marginal(x_posterior)
+end
RxInfer.FixedMarginalFormConstraint — Type
FixedMarginalFormConstraint

One of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = Marginal (for use in @constraints macro)
source

CompositeFormConstraint

It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:

form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()
@constraints begin 
+    q(x) :: SampleList(1000) :: PointMass()
+end
diff --git a/v2.16.1/library/model-specification/index.html b/v2.16.1/library/model-specification/index.html new file mode 100644 index 000000000..8ed15b307 --- /dev/null +++ b/v2.16.1/library/model-specification/index.html @@ -0,0 +1,4 @@ + +Model specification · RxInfer.jl
GitHub

Model specification in RxInfer

RxInfer.@model — Macro
@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model description
+end

@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.

Supported alias in the model specification

  • a || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).
  • a && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • a -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • ¬a and !a: alias for NOT(a) node (Unicode \neg, operator precedence ||, &&, -> and ! is the same as in Julia).
  • a + b + c: alias for (a + b) + c
  • a * b * c: alias for (a * b) * c
  • Normal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.
  • Normal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.
  • MvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • Gamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.
  • Gamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.
source
RxInfer.ModelGenerator — Type
ModelGenerator

ModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.

See also: infer

source
RxInfer.create_model — Function
create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)

Creates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.

Returns a tuple of 2 values:

    1. an instance of FactorGraphModel
    1. return value from the @model macro function definition
source
RxInfer.ModelInferenceOptions — Type
ModelInferenceOptions(; kwargs...)

Creates model inference options object. The list of available options is present below.

Options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.
  • warn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.

Advanced options

  • pipeline: changes the default pipeline for each factor node in the graph
  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

See also: infer

source
diff --git a/v2.16.1/manuals/background/index.html b/v2.16.1/manuals/background/index.html new file mode 100644 index 000000000..b836d8161 --- /dev/null +++ b/v2.16.1/manuals/background/index.html @@ -0,0 +1,2 @@ + +Background: variational inference · RxInfer.jl
GitHub
diff --git a/v2.16.1/manuals/comparison/index.html b/v2.16.1/manuals/comparison/index.html new file mode 100644 index 000000000..5e6ff0dfb --- /dev/null +++ b/v2.16.1/manuals/comparison/index.html @@ -0,0 +1,28 @@ + +RxInfer.jl vs. Others · RxInfer.jl
GitHub

Comparison to other packages

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.

DISCLAIMER:

  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, and we'll be more than willing to rectify.
  2. The comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.
ToolboxUniversalityEfficiencyExpressivenessDebugging & VisualizationModularityInference EngineLanguageCommunity & Ecosystem
RxInfer.jl~✓✓~✗Message-passingJulia✗
ForneyLab.jl✗~✗~✗Message-passingJulia✗
Infer.net~✓✗✓✗Message-passingC#✗
PGMax✗✓✗✓✗Message-passingPython✗
Turing.jl✓✗✓~✗SamplingJulia✓
PyMC✓✗✓✓✗SamplingPython✓
NumPyro✓✓~✓✗SamplingPython✓
TensorFlow Probability✓✗~✓✗SamplingPython✓
Stan✓✗✓✓✗SamplingStan✓

(Date of creation: 20/10/2023)

Legend

  • ✓ : Full capability or feature is present.
  • ~ : Partial capability or feature is present.
  • ✗ : No capability or feature.

Notes:

  • Universality: Denotes the capability to depict a vast array of probabilistic models.
  • Efficiency: Highlights computational competence. A "–" in this context suggests perceived slowness.
  • Expressiveness: Assesses the ability to concisely formulate intricate probabilistic models.
  • Debugging & Visualization: Evaluates the suite of tools for model debugging and visualization.
  • Modularity: Reflects the potential to create models by integrating smaller models.
  • Inference Engines: Pinpoints the primary inference strategy employed by the toolbox.
  • Language: Identifies the programming language integral to the toolbox.
  • Community & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.

RxInfer.jl breakdown

  • Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.

  • Efficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.

  • Modularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:

@model function inner_inner(τ, y)
+    y ~ Normal(τ[1], τ[2])
+end
+
+@model function inner(θ, α)
+    β ~ Normal(0, 1)
+    α ~ Gamma(β, 1)
+    α ~ inner_inner(τ = θ)
+end
+
+@model function outer()
+    local w
+    for i = 1:5
+        w[i] ~ inner(θ = Gamma(1, 1))
+    end
+    y ~ inner(θ = w[2:3])
+end
  • Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(0.0, 1.0)\\ + w & \sim \mathrm{InverseGamma}(1.0, 1.0)\\ + y & \sim \mathrm{Normal}(x, w) +\end{aligned}\]

The model then is expressed in RxInfer.jl as follows:

using RxInfer
+
+@model function example_model()
+    x ~ Normal(mean=0.0, var=1.0)
+    w ~ InverseGamma(α = 1, θ = 1)
+    y ~ Normal(mean = x, var = w)
+end
  • Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.
diff --git a/v2.16.1/manuals/constraints-specification/index.html b/v2.16.1/manuals/constraints-specification/index.html new file mode 100644 index 000000000..a30dca95e --- /dev/null +++ b/v2.16.1/manuals/constraints-specification/index.html @@ -0,0 +1,111 @@ + +Constraints specification · RxInfer.jl
GitHub

Constraints Specification

RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.

using RxInfer

General syntax

@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:


+# `functional` style
+@constraints function create_my_constraints(arg1, arg2)
+    ...
+end
+
+# `block` style
+myconstraints = @constraints begin 
+    ...
+end
+

In the first case it returns a function that return constraints upon calling, e.g. 

@constraints function make_constraints(mean_field)
+    q(x) :: PointMass
+
+    if mean_field
+        q(x, y) = q(x)q(y)
+    end
+end
+
+myconstraints = make_constraints(true)
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

and in the second case it evaluates automatically and returns constraints object directly.

myconstraints = @constraints begin
+    q(x) :: PointMass
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

Options specification

@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

myconstraints = @constraints [ warn = false ] begin 
+   ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/constraints specification

Marginal and messages form constraints

To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)

The following constraint:

@constraints begin
+    q(x) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:

\[\mathrm{approximate~} q(x) = \frac{\overrightarrow{\mu}(x)\overleftarrow{\mu}(x)}{\int \overrightarrow{\mu}(x)\overleftarrow{\mu}(x) \mathrm{d}x}\mathrm{~as~PointMass}\]

Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):

@constraints begin
+    q(x) :: PointMass
+    μ(x) :: SampleList(1000)
+    # it is possible to assign different form constraints on the same variable
+    # both for the marginal and for the messages
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+    μ(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) [ prod_constraint = GenericProd() ]
+  factorisation:
+Options:
+  warn = true
+

@constraints macro understands "stacked" form constraints. For example the following form constraint

@constraints begin
+    q(x) :: SampleList(1000) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass.

Note

Not all combinations of "stacked" form constraints are compatible between each other.

You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.

Factorisation constraints on posterior distribution q()

@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:

For example:

@constraints begin
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.

@constraints begin
+    q(x) = q(x[begin])..q(x[end])
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x) = q(x[(begin)..(end)])
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables $x_i$.

Note

@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])

It is possible to write more complex factorisation constraints, for example:

@constraints begin
+    q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x[(begin)..(end)], y[(begin)..(end)])
+Options:
+  warn = true
+

specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is

@constraints function make_constraints(k)
+    q(x) = q(x[begin:k])q(x[k+1:end])
+end
make_constraints (generic function with 1 method)

In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end].

To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+constraints = @constraints begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); constraints = constraints)

Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument.

diff --git a/v2.16.1/manuals/custom-node/c3238098.svg b/v2.16.1/manuals/custom-node/c3238098.svg new file mode 100644 index 000000000..5bb5bd78d --- /dev/null +++ b/v2.16.1/manuals/custom-node/c3238098.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/custom-node/index.html b/v2.16.1/manuals/custom-node/index.html new file mode 100644 index 000000000..3fc10ee3d --- /dev/null +++ b/v2.16.1/manuals/custom-node/index.html @@ -0,0 +1,86 @@ + +Defining a custom node and rules · RxInfer.jl
GitHub

Creating your own custom nodes

Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.

To create a custom node in RxInfer, 4 steps are required:

  1. Create your custom node in RxInfer using the @node macro.
  2. Define the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.
  3. Specify computations for marginal distributions of the relevant variables with the @marginalrule macro.
  4. Implement the computation of the Free Energy in a node with the @average_energy macro.

Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!

Problem statement

Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin $K=20$ times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment $x_k\in\{0,1\}$ using the Bernoulli distribution as

\[p(x_k \mid \pi) = \mathrm{Ber}(x_k \mid \pi) = \pi^{x_k} (1-\pi)^{1-x_k},\]

where $\pi \in[0,1]$ denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of $\pi$ which she models using the Beta distribution as

\[p(\pi) = \mathrm{Beta}(\pi \mid 4, 8).\]

With this prior belief, the total probabilistic model that she has for this experiment is given by

\[p(x_{1:K}, \pi) = p(\pi) \prod_{k=1}^K p(x_k \mid \pi).\]

Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of $\pi$, $p(\pi \mid x_{1:K})$, denoting how $\pi$ is distributed after we have seen the data.

Step 1: Creating the custom node

Note

In this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.

First things first, let's import RxInfer:

using RxInfer

In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:

  1. The name of the node. (::Type)
  2. Whether the node is Deterministic or Stochastic.
  3. The interfaces of the node and any potential aliases. (::Vector)

For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as

# struct for Bernoulli distribution with success probability π
+struct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution
+    π :: T
+    new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError("π must be between 0 and 1"))
+end
+
+# for simplicity, let's also specify the mean of the distribution
+Distributions.mean(d::MyBernoulli) = d.π

In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.

Note

You can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)

For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of $\pi$, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.

The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.

Concluding, we can create the MyBernoulli factor node as

@node MyBernoulli Stochastic [out, (π, aliases = [p])]

Cool! Step 1 is done, we have created a custom node.

Step 2: Defining rules for our node

In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as $p(\pi\mid x_{1:K})$, we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.

Sum-product message passing update rules

In sum-product message passing we compute outgoing messages to our node as

\[\vec{\mu}(x) \propto \int \mathrm{Ber}(x\mid \pi) \vec{\mu}(\pi) \mathrm{d}x\]

\[\overleftarrow{\mu}(\pi) \propto \sum_{x \in \{0,1\}} \mathrm{Ber}(x\mid \pi) \overleftarrow{\mu}(x)\]

This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.

For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain $\pi = \frac{\alpha}{\alpha + \beta}$, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as

@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))

Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for "the incoming message on interface π". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.

The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):

@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))

Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:

\[\overleftarrow{\mu}(π) \propto \mathrm{Beta}(1 + x, 2 - x)\]

Which gives us the following update rule:

@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin
+    p = mean(m_out)
+    Beta(one(p) + p, 2one(p) - p)
+end

Variational message passing update rules

We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as

\[\vec{\nu}(x) \propto \exp \int q(\pi) \ln \mathrm{Ber}(x\mid \pi) \mathrm{d}x\]

\[\overleftarrow{\nu}(\pi) \propto \exp \sum_{x \in \{0,1\}} q(x) \ln \mathrm{Ber}(x\mid \pi)\]

These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.

#rules towards out
+@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))
+
+@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin
+    rho_1 = mean(log, q_π)          # E[ln(x)]
+    rho_2 = mean(mirrorlog, q_π)    # E[log(1-x)]
+    m = max(rho_1, rho_2)
+    tmp = exp(rho_1 - m)
+    p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))
+    return Bernoulli(p)
+end
+
+#rules towards π
+@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin
+    p = mean(q_out)
+    return Beta(one(p) + p, 2one(p) - p)
+end
Node

Typically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.

In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.

Step 3: Defining joint marginals for our node

The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by

\[F[q,f] = - \sum_{a\in\mathcal{V}} \mathrm{H}[q_a(s_a)] - \sum_{a\in\mathcal{V}}\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)] + \sum_{i\in\mathcal{E}}\mathrm{H}[q_i(s_i)]\]

Here we call $q_a(s_a)$ the joint marginals around a node and $-\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)]$ we term the average energy.

In order to be able to compute the Bethe free energy, we need to first describe how to compute $q_a(s_a)$, defined in our case as

\[q(x_k, \pi) = \vec{\mu}(\pi) \overleftarrow{\mu}(x_k) \mathrm{Ber}(x_k \mid \pi)\]

To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:

@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin
+    r = mean(m_out)
+    p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)
+    return (out = m_out, p = p)
+end

In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as $q(x_k, \pi) = q(x_k)q(\pi)$. These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing $q(\pi)$ we need to compute the product $\vec{\mu}(\pi)\overleftarrow{\mu}(\pi)$. We already know how $\overleftarrow{\mu}(\pi)$ looks like from the previous step, so we can just use the prod function.

Step 4: Defining the average energy for our node

To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as $-\mathrm{E}_{q(x_k, \pi)}[\ln p(x_k \mid \pi)]$, however, because we know that we observe $x_k$ and therefore $q(x_k, \pi)$ factorizes, we can instead compute $\begin{aligned} -\mathrm{E}_{q(x_k)q(\pi)}[\ln p(x_k \mid \pi)] &= -\mathrm{E}_{q(x_k)q(\pi)} [\ln (\pi^{x_k} (1-\pi)^{1 - x_k})] \\ +&= -\mathrm{E}_{q(x_k)q(\pi)} [x_k \ln(\pi) + (1-x_k) \ln(1-\pi)] \\ +&= -\mathrm{E}_{q(x_k)}[x_k] \mathrm{E}_{q(\pi)} [\ln(\pi)] - (1-\mathrm{E}_{q(x_k)}[x_k]) \mathrm{E}_{q(\pi)}[\ln(1-\pi)] \end{aligned}$

Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to $\mathrm{E}_{q(x)}[1-\log{x}]$.

@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)

In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....

Using our node in a model

With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:

using Random
+
+rng = MersenneTwister(42)
+n = 500
+π_real = 0.75
+distribution = Bernoulli(π_real)
+
+dataset = float.(rand(rng, distribution, n))

Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:

@model function coin_model_mybernoulli(n)
+
+    # `datavar` creates data 'inputs' in our model
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    π ~ Beta(4.0, 8.0)
+
+    # We assume that outcome of each coin flip is governed by the MyBernoulli distribution
+    for i in 1:n
+        y[i] ~ MyBernoulli(π)
+    end
+
+end

Finally, we can run inference with this model and the generated dataset:

result_mybernoulli = infer(
+    model = coin_model_mybernoulli(length(dataset)),
+    data  = (y = dataset, ),
+)
Inference results:
+  Posteriors       | available for (π)
+

We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.

using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label="p(π|x)", c=3)
+vline!([π_real], label="Real π")
Example block output

As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.

@model function coin_model(n)
+
+    y = datavar(Float64, n)
+    p ~ Beta(4.0, 8.0)
+
+    for i in 1:n
+        y[i] ~ Bernoulli(p)
+    end
+
+end
+
+result_bernoulli = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, ),
+)
+
+if !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])
+    error("Results are not identical")
+else
+    println("Results are identical 🎉🎉🎉")
+end
Results are identical 🎉🎉🎉

Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.

diff --git a/v2.16.1/manuals/debugging/5104ce82.svg b/v2.16.1/manuals/debugging/5104ce82.svg new file mode 100644 index 000000000..ae9be21ad --- /dev/null +++ b/v2.16.1/manuals/debugging/5104ce82.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/debugging/d343be14.svg b/v2.16.1/manuals/debugging/d343be14.svg new file mode 100644 index 000000000..a5c9cc989 --- /dev/null +++ b/v2.16.1/manuals/debugging/d343be14.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/debugging/index.html b/v2.16.1/manuals/debugging/index.html new file mode 100644 index 000000000..c5913ff67 --- /dev/null +++ b/v2.16.1/manuals/debugging/index.html @@ -0,0 +1,60 @@ + +Debugging · RxInfer.jl
GitHub

Debugging

Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. 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

We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a "Memory Addon". Below is an example explaining how you can extract this history and use it to fix a bug.

Consider the coin toss example from earlier in the documentation. We model the binary outcome $x$ (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the $\theta$ parameter, with a known shape 𝑎 and rate 𝑏 parameter.

\[x_i \sim \mathrm{Bernoulli}(\theta)\]

\[\theta \sim \mathrm{Beta}(a, b)\]

where $x_i \in {0, 1}$ are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:

using RxInfer, Random, Plots
+
+n = 4
+θ_real = 0.3
+dataset = convert.(Int64, rand(Bernoulli(θ_real), n))
+
+@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, huge)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+

The model will run without errors. But when we plot the posterior distribution for $\theta$, something's wrong. The posterior seems to be a flat distribution:

rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+    addons = (AddonMemory(),)
+)
Inference results:
+  Posteriors       | available for (θ)
+

Now we have access to the messages that led to the marginal posterior:

Addons_messages

The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:

\[\underbrace{\overrightarrow{\mu}_{θ}(θ)}_{\substack{ \text{outgoing}\\ \text{message}}} = \sum_{x_1,\ldots,x_n} \underbrace{\overrightarrow{\mu}_{X_1}(x_1)\cdots \overrightarrow{\mu}_{X_n}(x_n)}_{\substack{\text{incoming} \\ \text{messages}}} \cdot \underbrace{f(θ,x_1,\ldots,x_n)}_{\substack{\text{node}\\ \text{function}}}\]

Graph

Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of $\theta$ we used in the code block above. So why does the posterior have this rate parameter?

All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.

@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, 100)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+
rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

Now the posterior is visible in the plot.

diff --git a/v2.16.1/manuals/delta-node/index.html b/v2.16.1/manuals/delta-node/index.html new file mode 100644 index 000000000..5fa1a0795 --- /dev/null +++ b/v2.16.1/manuals/delta-node/index.html @@ -0,0 +1,59 @@ + +Delta node · RxInfer.jl
GitHub

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.

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:

  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.
  3. Stacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.

The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:

MethodsGaussian NodesExponential Family NodesStacking Delta Nodes
Linearization✓✗✓
Unscented✓✗✓
CVI✓✓✗

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.

For clarity, consider the following example:

using RxInfer
+
+@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=0.0, var=1.0)
+    y ~ tanh(x)
+    z ~ Normal(mean=y, var=1.0)
+end

To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:

delta_meta = @meta begin
+    tanh() -> Linearization()
+end
Meta specification:
+  tanh() -> Linearization()
+Options:
+  warn = true

or

delta_meta = @meta begin
+    tanh() -> Unscented()
+end
Meta specification:
+  tanh() -> Unscented{Float64, Float64, Float64, Nothing}(0.001, 2.0, 0.0, nothing)
+Options:
+  warn = true

For a deeper understanding of the Unscented method and its parameters, consult the docstrings.

Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:

delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)
+end
Meta specification:
+  tanh() -> DeltaMeta{Linearization, typeof(atanh)}(Linearization(), atanh)
+Options:
+  warn = true

To execute the inference procedure:

infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))
Inference results:
+  Posteriors       | available for (y, x)
+

This methodology is consistent even when the delta node is associated with multiple nodes. For instance:

f(x, g) = x*tanh(g)
f (generic function with 1 method)
@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=1.0, var=1.0)
+    g ~ Normal(mean=1.0, var=1.0)
+    y ~ f(x, g)
+    z ~ Normal(mean=y, var=0.1)
+end

The corresponding meta specification is:

delta_meta = @meta begin
+    f() -> DeltaMeta(method = Linearization())
+end
Meta specification:
+  f() -> DeltaMeta{Linearization, Nothing}(Linearization(), nothing)
+Options:
+  warn = true

or simply

delta_meta = @meta begin
+    f() -> Linearization()
+end
Meta specification:
+  f() -> Linearization()
+Options:
+  warn = true

If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:

delta_meta = @meta begin 
+    f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))
+end

Exponential Family Case

When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:

using RxInfer
+
+@model function delta_node_example1()
+    z = datavar(Float64)
+    x ~ Gamma(shape=1.0, rate=1.0)
+    y ~ tanh(x)
+    z ~ Bernoulli(y)
+end

The corresponding meta specification can be represented as:

using StableRNGs
+using Optimisers
+
+delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))
+end
Meta specification:
+  tanh() -> DeltaMeta{ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}, Nothing}(ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}(StableRNGs.LehmerRNG(state=0x00000000000000000000000000000055), 100, 100, Optimisers.Descent{Float64}(0.01), ForwardDiffGrad{0}(), 1, Val{true}(), true), nothing)
+Options:
+  warn = true

Consult the ProdCVI docstrings for a detailed explanation of these parameters.

diff --git a/v2.16.1/manuals/getting-started/c8031912.svg b/v2.16.1/manuals/getting-started/c8031912.svg new file mode 100644 index 000000000..c255d595c --- /dev/null +++ b/v2.16.1/manuals/getting-started/c8031912.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/getting-started/ee1adb21.svg b/v2.16.1/manuals/getting-started/ee1adb21.svg new file mode 100644 index 000000000..ff62e36de --- /dev/null +++ b/v2.16.1/manuals/getting-started/ee1adb21.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/getting-started/index.html b/v2.16.1/manuals/getting-started/index.html new file mode 100644 index 000000000..e74e13ad7 --- /dev/null +++ b/v2.16.1/manuals/getting-started/index.html @@ -0,0 +1,91 @@ + +Getting started · RxInfer.jl
GitHub

Getting started

RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.

RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.

This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.

Installation

Install RxInfer through the Julia package manager:

] add RxInfer

Importing RxInfer

To add RxInfer package (and all associated packages) into a running Julia session simply run:

using RxInfer

Read more about about using in the Using methods from RxInfer section of the documentation.

Example: Inferring the bias of a coin

The RxInfer approach to solving inference problems consists of three phases:

  1. Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.
  2. Inference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.
  3. Inference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.

Coin flip simulation

Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).

First let's setup our environment by importing all needed packages:

using RxInfer, Distributions, Random

Next, let's define our dataset:

rng = MersenneTwister(42)
+n = 10
+p = 0.75
+distribution = Bernoulli(p)
+
+dataset = float.(rand(rng, Bernoulli(p), n))
10-element Vector{Float64}:
+ 1.0
+ 1.0
+ 1.0
+ 1.0
+ 0.0
+ 0.0
+ 1.0
+ 1.0
+ 0.0
+ 1.0

Model specification

In 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.

Likelihood

We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.

\[y_i \sim \mathrm{Bernoulli}(\theta),\]

where $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]$.

Prior

We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.

\[\theta \sim Beta(a, b),\]

where $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.

Joint probability

The joint probability is given by the multiplication of the likelihood and the prior, i.e.

\[P(y_{1:N}, θ) = P(θ) \prod_{i=1}^N P(y_i | θ).\]

Now let's see how to specify this model using GraphPPL's package syntax.

# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during inference step
+    return y, θ
+end

As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create "clamped" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Inference specification

Automatic inference specification

Once 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 inference function that supports static datasets.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
+
θestimated = result.posteriors[:θ]
Beta{Float64}(α=9.0, β=10.0)
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803

Read more information about the inference function in the Static Inference documentation section.

Manual inference specification

There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:

  1. Return variables of interests from model specification
  2. Subscribe on variables of interests posterior marginal updates
  3. Pass data to the model
  4. Unsubscribe

Here is an example of inference procedure:

function custom_inference(data)
+    n = length(data)
+
+    # `coin_model` function from `@model` macro returns a reference to the model generator object
+    # we need to use the `create_model` function to get actual model object
+    model, (y, θ) = create_model(coin_model(n))
+
+    # Reference for future posterior marginal
+    mθ = nothing
+
+    # `getmarginal` function returns an observable of future posterior marginal updates
+    # We use `Rocket.jl` API to subscribe on this observable
+    # As soon as posterior marginal update is available we just save it in `mθ`
+    subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)
+
+    # `update!` function passes data to our data inputs
+    update!(y, data)
+
+    # It is always a good practice to unsubscribe and to
+    # free computer resources held by the subscription
+    unsubscribe!(subscription)
+
+    # Here we return our resulting posterior marginal
+    return mθ
+end
custom_inference (generic function with 1 method)

Inference execution

Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.

θestimated = custom_inference(dataset)
Marginal(Beta{Float64}(α=9.0, β=10.0))
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title="Prior", fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+p2 = plot(rθ, (x) -> pdf(θestimated, x), title="Posterior", fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+
+plot(p1, p2, layout = @layout([ a; b ]))
Example block output

In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:

dataset_100   = float.(rand(rng, Bernoulli(p), 100))
+dataset_1000  = float.(rand(rng, Bernoulli(p), 1000))
+dataset_10000 = float.(rand(rng, Bernoulli(p), 10000))
θestimated_100   = custom_inference(dataset_100)
+θestimated_1000  = custom_inference(dataset_1000)
+θestimated_10000 = custom_inference(dataset_10000)
p3 = plot(title = "Posterior", legend = :topleft)
+
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_100)", c = 4)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_1000)", c = 5)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_10000)", c = 6)
+
+plot(p1, p3, layout = @layout([ a; b ]))
Example block output

With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.

println("mean: ", mean(θestimated_10000))
+println("std:  ", std(θestimated_10000))
mean: 0.7529223698671196
+std:  0.004310967761308469

Where to go next?

There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.

diff --git a/v2.16.1/manuals/inference/infer/index.html b/v2.16.1/manuals/inference/infer/index.html new file mode 100644 index 000000000..158b8470f --- /dev/null +++ b/v2.16.1/manuals/inference/infer/index.html @@ -0,0 +1,120 @@ + +Static vs Streamline inference · RxInfer.jl
GitHub

Automatic Inference Specification

RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors.

It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.

For details on manual inference specification, see the Manual Inference section.

RxInfer.infer — Function
infer(
+    model; 
+    data = nothing,
+    datastream = nothing,
+    autoupdates = nothing,
+    initmarginals = nothing,
+    initmessages = nothing,
+    constraints = nothing,
+    meta = nothing,
+    options = nothing,
+    returnvars = nothing, 
+    predictvars = nothing, 
+    historyvars = nothing,
+    keephistory = nothing,
+    iterations = nothing,
+    free_energy = false,
+    free_energy_diagnostics = BetheFreeEnergyDefaultChecks,
+    showprogress = false,
+    callbacks = nothing,
+    addons = nothing,
+    postprocess = DefaultPostprocess(),
+    warn = true,
+    events = nothing,
+    uselock = false,
+    autostart = true,
+    catch_exception = false
+)

This function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.

Arguments

For more information about some of the arguments, please check below.

  • model: specifies a model generator, required
  • data: NamedTuple or Dict with data, required (or datastream or predictvars)
  • datastream: A stream of NamedTuple with data, required (or data)
  • autoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates
  • initmarginals = nothing: NamedTuple or Dict with initial marginals, optional
  • initmessages = nothing: NamedTuple or Dict with initial messages, optional
  • constraints = nothing: constraints specification object, optional, see @constraints
  • meta = nothing: meta specification object, optional, may be required for some models, see @meta
  • options = nothing: model creation options, optional, see ModelInferenceOptions
  • returnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information
  • predictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)
  • historyvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)
  • keephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)
  • iterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information
  • free_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl
  • free_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.
  • showprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)
  • catch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)
  • callbacks = nothing: inference cycle callbacks, optional, see below for more info
  • addons = nothing: inject and send extra computation information along messages, see below for more info
  • postprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info
  • events = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)
  • uselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)
  • autostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)
  • warn = true: enables/disables warnings

Note on NamedTuples

When passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.

The model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:

@model function coin_toss(some_argument, some_keyword_argument = 3)
+    ...
+end
+
+result = infer(
+    model = coin_toss(some_argument; some_keyword_argument = 3)
+)

Note: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.

  • data

Either data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.

Note: The behavior of the data keyword argument depends on the inference setting (batch or streamline).

The data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.

  • streamline setting

All entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.

  • datastream

The datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.

Note: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.

For specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as

infer(...
+    initmarginals = (
+        # initialize the marginal distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)
+
+This argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.
+
+- ### `initmessages`
+
+For specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as

julia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )

  • options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.

  • pipeline: changes the default pipeline for each factor node in the graph

  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

  • returnvars

returnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.

Batch inference:

  • Accepts a NamedTuple or Dict of return variable specifications.
  • Two specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).
  • When iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).
  • Use iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.

Example:

result = infer(
+    ...,
+    returnvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    )
+)

Shortcut for setting the same option for all variables:

result = infer(
+    ...,
+    returnvars = KeepLast()  # or KeepEach()
+)

Streamline inference:

  • For each symbol in returnvars, infer creates an observable stream of posterior updates.
  • Agents can subscribe to these updates using the Rocket.jl package.

Example:

engine = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    returnvars = (:x, :τ),
+    autostart  = false
+)
  • predictvars

predictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.

Similar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    predictvars = (
+        o = KeepLast(),
+        τ = KeepEach()
+    )
+)

Note: The predictvars argument is exclusive for batch setting.

  • historyvars

historyvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.

historyvars accepts a NamedTuple or Dict or return var specification. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    ),
+    keephistory = 10
+)

It is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.

Example:

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = KeepLast(),
+    keephistory = 10
+)
  • keep_history

Specifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.

  • iterations

Specifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration.

  • free_energy

Streamline inference:

Specifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.

  • When free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.
    • engine.free_energy_history: Averaged BFE history over VMP iterations.
    • engine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.
    • engine.free_energy_raw_history: Raw BFE history.

Batch inference:

Specifies if the infer function should return Bethe Free Energy (BFE) values.

  • Optionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.

  • free_energy_diagnostics

This settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.

  • catch_exception

The catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.

  • callbacks

The inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.

result = infer(
+    ...,
+    callbacks = (
+        on_marginal_update = (model, name, update) -> println("$(name) has been updated: $(update)"),
+        after_inference    = (args...) -> println("Inference has been completed")
+    )
+)

The callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:

  • on_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)
  • before_model_creation: args: ()
  • after_model_creation: args: (model::FactorGraphModel, returnval)
  • before_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • before_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • after_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)
  • after_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)

before_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.

  • addons

The addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.

  • postprocess

The postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.

source
RxInfer.InferenceResult — Type
InferenceResult

This structure is used as a return value from the infer function.

Public Fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.
  • free_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.
  • error: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.

See also: infer

source
RxInfer.start — Function
start(engine::RxInferenceEngine)

Starts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.stop

source
RxInfer.stop — Function
stop(engine::RxInferenceEngine)

Stops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.start

source
RxInfer.@autoupdates — Macro
@autoupdates

Creates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification.

Each line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.

For example:

@autoupdates begin 
+    x = f(q(z))
+end

This structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically.

As an example consider the following model and auto-update specification:

@model function kalman_filter()
+    x_current_mean = datavar(Float64)
+    x_current_var  = datavar(Float64)
+
+    x_current ~ Normal(mean = x_current_mean, var = x_current_var)
+
+    x_next ~ Normal(mean = x_current, var = 1.0)
+
+    y = datavar(Float64)
+    y ~ Normal(mean = x_next, var = 1.0)
+end

This model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:

autoupdates = @autoupdates begin
+    x_current_mean, x_current_var = mean_cov(q(x_next))
+end

This structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.

See also: infer

source
RxInfer.RxInferenceEngine — Type
RxInferenceEngine

The return value of the rxinference function.

Public fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.
  • free_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.
  • history: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.
  • free_energy_history: (optional) Free energy history, average over variational iterations
  • free_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)
  • free_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)
  • events: (optional) A stream of events send by the inference engine. See the events argument for the infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.

Use the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.

See also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop

source
RxInfer.RxInferenceEvent — Type
RxInferenceEvent{T, D}

The RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.

The events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:

using Rocket
+
+struct MyEventListener <: Rocket.Actor{RxInferenceEvent}
+    # ... extra fields
+end
+
+function Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })
+    model, iteration = event
+    println("Iteration $(iteration) has been finished.")
+end
+
+function Rocket.on_error!(listener::MyEventListener, err)
+    # ...
+end
+
+function Rocket.on_complete!(listener::MyEventListener)
+    # ...
+end
+

and later on:

engine = infer(events = Val((:after_iteration, )), ...)
+
+subscription = subscribe!(engine.events, MyEventListener(...))

See also: infer, RxInferenceEngine

source
diff --git a/v2.16.1/manuals/inference/manual/257ebff1.svg b/v2.16.1/manuals/inference/manual/257ebff1.svg new file mode 100644 index 000000000..5d3fecf7d --- /dev/null +++ b/v2.16.1/manuals/inference/manual/257ebff1.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/inference/manual/35e1bbae.svg b/v2.16.1/manuals/inference/manual/35e1bbae.svg new file mode 100644 index 000000000..4c85a6ce0 --- /dev/null +++ b/v2.16.1/manuals/inference/manual/35e1bbae.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/inference/manual/8f2d7448.svg b/v2.16.1/manuals/inference/manual/8f2d7448.svg new file mode 100644 index 000000000..e10837a44 --- /dev/null +++ b/v2.16.1/manuals/inference/manual/8f2d7448.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.1/manuals/inference/manual/index.html b/v2.16.1/manuals/inference/manual/index.html new file mode 100644 index 000000000..e27ff9e11 --- /dev/null +++ b/v2.16.1/manuals/inference/manual/index.html @@ -0,0 +1,103 @@ + +Manual inference specification · RxInfer.jl
GitHub

Manual inference

For advanced use cases it is advised to use manual inference specification.

Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:

  1. Create a model with @model macro and get a references to random variables and data inputs
  2. Subscribe to random variable posterior marginal updates
  3. Subscribe to Bethe Free Energy updates (optional)
  4. Feed model with observations
  5. Unsubscribe from posterior marginal updates (optional)

It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.

Model creation

During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.

using RxInfer, Distributions, Random
+
+@model function my_model()
+    m2 ~ NormalMeanVariance(0.0, 1.0)
+    m1 ~ NormalMeanVariance(m2, 1.0)
+
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(m1, 1.0)
+
+    # Return variables of interests, optional
+    return m1, y
+end

And later on we may create our model with the create_model function and obtain references for variables of interests:

model, (m1, y) = create_model(my_model())

Alternatively, it is possible to query any variable using squared brackets on model object:

model[:m1] # m1
+model[:y]  # y

@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.

Posterior marginal updates

The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.

We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:

m1_posterior_updates = getmarginal(m1)

After that we can subscribe on new updates and perform some actions based on new values:

m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin
+    println("New posterior for m1: ", new_posterior)
+end)

Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.

@model function my_model()
+    ...
+    m_n = randomvar(n)
+    ...
+    return m_n, ...
+end
+
+model, (m_n, ...) = create_model(my_model())
+
+m_n_updates = getmarginals(m_n)

Feeding observations

By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.

To feed an observation for a specific data input we use update! function:

update!(y, 0.0)
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:

update!(y, 0.0) # Observation didn't change, should result in the same posterior
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

If y is an array of data inputs it is possible to pass an array of observation to update! function:

for i in 1:length(data)
+    update!(y[i], data[i])
+end
+# is an equivalent of
+update!(y, data)

Variational Message Passing

Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.

using RxInfer, Distributions, Random
real_mean      = -4.0
+real_precision = 0.2
+rng            = MersenneTwister(1234)
+
+n    = 100
+data = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)
@model function normal_estimation(n)
+    m ~ NormalMeanVariance(0.0, 10.0)
+    w ~ Gamma(0.1, 10.0)
+
+    y = datavar(Float64, n)
+
+    for i in 1:n
+        y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }
+    end
+
+    return m, w, y
+end

We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:

model, (m, w, y) = create_model(normal_estimation(n))
+
+# We use vague initial marginals
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))

To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:

m_marginals = []
+w_marginals = []
+
+subscriptions = subscribe!([
+    (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),
+    (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),
+])
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(subscriptions)

As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.

using Plots
+
+p1    = plot(title = "'Mean' posterior marginals")
+grid1 = -6.0:0.01:4.0
+
+for iter in [ 1, 2, 10 ]
+
+    estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = "Estimated mean after $iter VMP iterations")
+
+end
+
+plot!(p1, [ real_mean ], seriestype = :vline, label = "Real mean", color = :red4, opacity = 0.7)
Example block output
p2    = plot(title = "'Precision' posterior marginals")
+grid2 = 0.01:0.001:0.35
+
+for iter in [ 2, 3, 10 ]
+
+    estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = "Estimated precision after $iter VMP iterations")
+
+end
+
+plot!(p2, [ real_precision ], seriestype = :vline, label = "Real precision", color = :red4, opacity = 0.7)
Example block output

Computing Bethe Free Energy

VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.

The RxInfer package exports score function for an observable of free energy values:

fe_observable = score(model, BetheFreeEnergy())
# Reset posterior marginals for `m` and `w`
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))
+
+fe_values = []
+
+fe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(fe_subscription)
plot(fe_values, label = "Bethe Free Energy", xlabel = "Iteration #")
Example block output
diff --git a/v2.16.1/manuals/inference/overview/index.html b/v2.16.1/manuals/inference/overview/index.html new file mode 100644 index 000000000..630187177 --- /dev/null +++ b/v2.16.1/manuals/inference/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Inference execution

The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):

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.

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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.

Automatic inference specification on static datasets

RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section.

Automatic inference specification on real-time datasets

RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section.

Manual inference specification

While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.

diff --git a/v2.16.1/manuals/inference/postprocess/index.html b/v2.16.1/manuals/inference/postprocess/index.html new file mode 100644 index 000000000..3b1c235ff --- /dev/null +++ b/v2.16.1/manuals/inference/postprocess/index.html @@ -0,0 +1,2 @@ + +Inference results postprocessing · RxInfer.jl
GitHub

Inference results postprocessing

infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:

diff --git a/v2.16.1/manuals/meta-specification/index.html b/v2.16.1/manuals/meta-specification/index.html new file mode 100644 index 000000000..709241953 --- /dev/null +++ b/v2.16.1/manuals/meta-specification/index.html @@ -0,0 +1,122 @@ + +Meta specification · RxInfer.jl
GitHub

Meta Specification

Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.

General syntax

@meta macro accepts either regular Julia function or a single begin ... end block:

@meta function MyModelMeta(arg1, arg2)
+    Node(y,x) -> MetaObject(arg1, arg2)
+end
+
+my_meta = @meta begin 
+    Node(y,x) -> MetaObject(arg1, arg2)
+end

In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order $5$ can be specified as follows:

@meta function ARmodel_meta(num_order)
+    AR() -> ARMeta(Univariate, num_order, ARsafe())
+end
+
+my_meta = ARmodel_meta(5)

In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:

num_order = 5
+
+my_meta = @meta begin 
+    AR() -> ARMeta(Multivariate, num_order, ARsafe())
+end

Both syntax variations provide the same meta specification and there is no preference given to one over the other.

Options specification

@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

my_meta = @meta [ warn = false ] begin 
+   ...
+end
+
+@meta [ warn = false ] function MyModelMeta()
+    ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/meta specification

Meta specification

First, let's start with an example:

my_meta = @meta begin 
+    GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))
+end

This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.

You can have a list of as many meta specification entries as possible for different nodes:

my_meta = @meta begin 
+    GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))
+    AR() -> ARMeta(Multivariate, 5, ARsafe())
+    MyCustomNode() -> MyCustomMetaObject(arg1, arg2)
+end

To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+my_meta = @meta begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); meta = my_meta)

Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:

inferred_result = infer(
+    model = my_model(arguments...),
+    meta = my_meta,
+    ...
+)

Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:

@model function my_model()
+    ...
+
+    y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }
+
+    ...
+end

If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.

Create your own meta

Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:

# create your own meta structure for your custom node
+struct MyCustomMeta
+    arg1 
+    arg2 
+end
+
+# apply the new meta structure to your node
+@meta function model_meta(arg1, arg2)
+    MyCustomNode() -> MyCustomMeta(arg1,arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

or create different meta structures for a node, e.g. AR node:

# create your own meta structure for the AR node
+struct MyARMeta
+    arg1
+    arg2
+end
+
+# apply the new meta structure to the AR node
+@meta function model_meta(arg1, arg2)
+    AR() -> MyARMeta(arg1, arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.

Example

This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(2.5, 0.5)\\ + y & \sim \mathrm{Normal}(2*x, 2.0) +\end{aligned}\]

where $y$ is observable data and $x$ is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.

using RxInfer
+
+#create data
+y_data = 4.0
+
+#make model
+@model function gaussian_model()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+#do inference
+inference_result = infer(
+    model = gaussian_model(),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (x)
+

However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean $m$ clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:

#create your new meta structure for Normal node
+struct MetaConstrainedMeanNormal{T}
+    lower_limit :: T
+    upper_limit :: T
+end
+
+#define rules with meta for the Normal node
+@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
+
+@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
#make model
+@model function gaussian_model_with_meta()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+custom_meta = @meta begin
+    NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)
+end
+
+#do inference
+inference_result = inference(
+    model = gaussian_model(),
+    data = (y = y_data,),
+    meta = custom_meta
+)
Inference results:
+  Posteriors       | available for (x)
+

Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.

diff --git a/v2.16.1/manuals/model-specification/index.html b/v2.16.1/manuals/model-specification/index.html new file mode 100644 index 000000000..c339e6bee --- /dev/null +++ b/v2.16.1/manuals/model-specification/index.html @@ -0,0 +1,117 @@ + +Model specification · RxInfer.jl
GitHub

Model Specification

The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: 

@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model specification here
+    return ...
+end

Model options, model_arguments and model_keyword_arguments are optional and may be omitted:

@model function model_name()
+    # model specification here
+    return ...
+end

The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:

@model function my_model(model_arguments...)
+    # model specification here
+    # ...
+    return x, y
+end
generator = my_model(model_arguments...)

In order to create an instance of the model object we should use the create_model function:

model, (x, y) = create_model(generator)

It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.

A full example before diving in

Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:

@model function state_space_model(n_observations, noise_variance)
+
+    c = constvar(1.0)
+    x = randomvar(n_observations)
+    y = datavar(Float64, n_observations)
+
+    x[1] ~ NormalMeanVariance(0.0, 100.0)
+
+    for i in 2:n_observations
+       x[i] ~ x[i - 1] + c
+       y[i] ~ NormalMeanVariance(x[i], noise_var)
+    end
+
+    return x, y
+end

Graph variables creation

Constants

Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).

You can create a constant within a model specification macro with constvar() function. For example:

@model function model_name(...)
+    ...
+    c = constvar(1.0)
+
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0
+    end
+    ...
+end
Note

constvar() function is supposed to be used only within the @model macro.

Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:

@model function model_name(nsamples::Int, c::ConstVariable)
+    ...
+    # no need to call for a constvar() here
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`
+    end
+    ...
+end
Note

::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.

Data variables

It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.

Examples: 

@model function model_name(...)
+    ...
+    y = datavar(Float64) # Creates a single data input with `y` as identificator
+    y = datavar(Float64, n) # Returns a vector of  `y_i` data input objects with length `n`
+    y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`
+    y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

datavar() function is supposed to be used only within the @model macro.

datavar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = datavar(Float64, n) where { allow_missing = true }
+    ...
+end

Data variables available options

  • allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.

Random variables

There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.

Examples: 

@model function model_name(...)
+    ...
+    x = randomvar() # Returns a single random variable which can be used later in the model
+    x = randomvar(n) # Returns an vector of random variables with length `n`
+    x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`
+    x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

randomvar() function is supposed to be used only within the @model macro.

randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = randomvar() where { prod_constraint = ProdGeneric() }
+    ...
+end

Random variables available options

  • prod_constraint
  • prod_strategy
  • marginal_form_constraint
  • marginal_form_check_strategy
  • messages_form_constraint
  • messages_form_check_strategy
  • pipeline

The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.

Node creation

Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables.

Distributions.jl compatibility

For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:

  1. Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.
  2. Depending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.
  3. In certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.

Tilde syntax

We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define

@model function model_name(...)
+    ...
+    m = randomvar()
+    v = randomvar()
+    y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically
+    ...
+end

Another example, but using a deterministic relation between random variables:

@model function model_name(...)
+    ...
+    a = randomvar()
+    b = randomvar()
+    c ~ a + b
+    ...
+end
Note

The RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.

The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:

noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.

It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.

Note

It is forbidden to use random variable within square brackets in the model specification.

y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.
+
+y ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.

It is also possible to return a node reference from the ~ operator. Use the following syntax:

node, y ~ NormalMeanVariance(mean, var)

Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.

Broadcasting syntax

Note

Broadcasting syntax requires at least v2.1.0 of GraphPPL.jl

GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:

y = datavar(Float64, n)
+y .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations

More complex expression are also allowed:

m ~ NormalMeanPrecision(0.0, 0.0001)
+t ~ Gamma(1.0, 1.0)
+
+y = randomvar(Float64, n)
+y .~ NormalMeanPrecision(m, t)
A = constvar(...)
+x = randomvar(n)
+y = datavar(Vector{Float64}, n)
+
+w         ~ Wishart(3, diageye(2))
+x[1]      ~ MvNormalMeanPrecision(zeros(2), diageye(2))
+x[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A
+y        .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix

Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:

# Suppose `x` is a 2-dimensional Gaussian distribution
+z .~ x .+ constvar([ 1, 1 ])
+# Which is equivalent to 
+for i in 1:n
+   z[i] ~ x[i] + constvar([ 1, 1 ])
+end

Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:

# Without explicit `constvar`
+z .~ x .+ [ 1, 1 ]
+# Which is equivalent to 
+array = [1, 1]
+for i in 1:n
+   z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian 
+end

Read more about how broadcasting machinery works in Julia in the official documentation.

Node creation options

To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q

A list of the available options specific to the ReactiveMP inference engine is presented below.

Factorisation constraint option

See also Constraints Specification section.

Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:

variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }

where RecognitionFactorisationConstraint can be the following

  1. MeanField()

Automatically specifies a mean-field factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }
  1. FullFactorisation()

Automatically specifies a full factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }
  1. q(μ)q(v)q(out) or q(μ) * q(v) * q(out)

A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.

Examples: 

# Using interface names of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names for some node
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }
+
+# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names aliases for some node
+# In general aliases correspond to the function names for distribution parameters
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }
+
+# Using random variables names from `~` operator expression
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }
+
+# All methods can be combined easily
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }

Metadata option

Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.

z ~ f(x, y) where { meta = ... }
diff --git a/v2.16.1/search_index.js b/v2.16.1/search_index.js new file mode 100644 index 000000000..f6f236135 --- /dev/null +++ b/v2.16.1/search_index.js @@ -0,0 +1,3 @@ +var documenterSearchIndex = {"docs": +[{"location":"manuals/delta-node/#delta-node-manual","page":"Delta node","title":"Delta node manual","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/#Features-and-Supported-Inference-Scenarios","page":"Delta node","title":"Features and Supported Inference Scenarios","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Gaussian Nodes: For delta nodes linked to strictly multivariate or univariate Gaussian distributions, the recommended methods are Linearization or Unscented transforms.\nExponential Family Nodes: For the delta node connected to nodes from the exponential family, the CVI (Conjugate Variational Inference) is the method of choice.\nStacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Methods Gaussian Nodes Exponential Family Nodes Stacking Delta Nodes\nLinearization ✓ ✗ ✓\nUnscented ✓ ✗ ✓\nCVI ✓ ✓ ✗","category":"page"},{"location":"manuals/delta-node/#Gaussian-Case","page":"Delta node","title":"Gaussian Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For clarity, consider the following example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=0.0, var=1.0)\n y ~ tanh(x)\n z ~ Normal(mean=y, var=1.0)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Unscented()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For a deeper understanding of the Unscented method and its parameters, consult the docstrings.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To execute the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"This methodology is consistent even when the delta node is associated with multiple nodes. For instance:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"f(x, g) = x*tanh(g)","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=1.0, var=1.0)\n g ~ Normal(mean=1.0, var=1.0)\n y ~ f(x, g)\n z ~ Normal(mean=y, var=0.1)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification is:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization())\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or simply","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))\nend","category":"page"},{"location":"manuals/delta-node/#Exponential-Family-Case","page":"Delta node","title":"Exponential Family Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example1()\n z = datavar(Float64)\n x ~ Gamma(shape=1.0, rate=1.0)\n y ~ tanh(x)\n z ~ Bernoulli(y)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification can be represented as:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using StableRNGs\nusing Optimisers\n\ndelta_meta = @meta begin \n tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Consult the ProdCVI docstrings for a detailed explanation of these parameters.","category":"page"},{"location":"manuals/inference/postprocess/#user-guide-inference-postprocess","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"","category":"section"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:","category":"page"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"DefaultPostprocess\nUnpackMarginalPostprocess\nNoopPostprocess","category":"page"},{"location":"manuals/inference/postprocess/#RxInfer.DefaultPostprocess","page":"Inference results postprocessing","title":"RxInfer.DefaultPostprocess","text":"DefaultPostprocess picks the most suitable postprocessing step automatically\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.UnpackMarginalPostprocess","page":"Inference results postprocessing","title":"RxInfer.UnpackMarginalPostprocess","text":"This postprocessing step removes the Marginal wrapper type from the result\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.NoopPostprocess","page":"Inference results postprocessing","title":"RxInfer.NoopPostprocess","text":"This postprocessing step does nothing\n\n\n\n\n\n","category":"type"},{"location":"manuals/model-specification/#user-guide-model-specification","page":"Model specification","title":"Model Specification","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Model options, model_arguments and model_keyword_arguments are optional and may be omitted:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name()\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function my_model(model_arguments...)\n # model specification here\n # ...\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"generator = my_model(model_arguments...)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"In order to create an instance of the model object we should use the create_model function:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"model, (x, y) = create_model(generator)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.","category":"page"},{"location":"manuals/model-specification/#A-full-example-before-diving-in","page":"Model specification","title":"A full example before diving in","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function state_space_model(n_observations, noise_variance)\n\n c = constvar(1.0)\n x = randomvar(n_observations)\n y = datavar(Float64, n_observations)\n\n x[1] ~ NormalMeanVariance(0.0, 100.0)\n\n for i in 2:n_observations\n x[i] ~ x[i - 1] + c\n y[i] ~ NormalMeanVariance(x[i], noise_var)\n end\n\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/#Graph-variables-creation","page":"Model specification","title":"Graph variables creation","text":"","category":"section"},{"location":"manuals/model-specification/#user-guide-model-specification-constant-variables","page":"Model specification","title":"Constants","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"You can create a constant within a model specification macro with constvar() function. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n c = constvar(1.0)\n\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nconstvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(nsamples::Int, c::ConstVariable)\n ...\n # no need to call for a constvar() here\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\n::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-data-variables","page":"Model specification","title":"Data variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64) # Creates a single data input with `y` as identificator\n y = datavar(Float64, n) # Returns a vector of `y_i` data input objects with length `n`\n y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`\n y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\ndatavar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"datavar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64, n) where { allow_missing = true }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Data-variables-available-options","page":"Model specification","title":"Data variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-random-variables","page":"Model specification","title":"Random variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n x = randomvar() # Returns a single random variable which can be used later in the model\n x = randomvar(n) # Returns an vector of random variables with length `n`\n x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`\n x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nrandomvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = randomvar() where { prod_constraint = ProdGeneric() }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Random-variables-available-options","page":"Model specification","title":"Random variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"prod_constraint\nprod_strategy\nmarginal_form_constraint\nmarginal_form_check_strategy\nmessages_form_constraint\nmessages_form_check_strategy\npipeline","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.","category":"page"},{"location":"manuals/model-specification/#Node-creation","page":"Model specification","title":"Node creation","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables. ","category":"page"},{"location":"manuals/model-specification/#Distributions.jl-compatibility","page":"Model specification","title":"Distributions.jl compatibility","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.\nDepending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.\nIn certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.","category":"page"},{"location":"manuals/model-specification/#Tilde-syntax","page":"Model specification","title":"Tilde syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n m = randomvar()\n v = randomvar()\n y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Another example, but using a deterministic relation between random variables:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n a = randomvar()\n b = randomvar()\n c ~ a + b\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nThe RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nIt is forbidden to use random variable within square brackets in the model specification.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.\n\ny ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is also possible to return a node reference from the ~ operator. Use the following syntax:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"node, y ~ NormalMeanVariance(mean, var)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.","category":"page"},{"location":"manuals/model-specification/#Broadcasting-syntax","page":"Model specification","title":"Broadcasting syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nBroadcasting syntax requires at least v2.1.0 of GraphPPL.jl ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y = datavar(Float64, n)\ny .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"More complex expression are also allowed:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"m ~ NormalMeanPrecision(0.0, 0.0001)\nt ~ Gamma(1.0, 1.0)\n\ny = randomvar(Float64, n)\ny .~ NormalMeanPrecision(m, t)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A = constvar(...)\nx = randomvar(n)\ny = datavar(Vector{Float64}, n)\n\nw ~ Wishart(3, diageye(2))\nx[1] ~ MvNormalMeanPrecision(zeros(2), diageye(2))\nx[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A\ny .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Suppose `x` is a 2-dimensional Gaussian distribution\nz .~ x .+ constvar([ 1, 1 ])\n# Which is equivalent to \nfor i in 1:n\n z[i] ~ x[i] + constvar([ 1, 1 ])\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Without explicit `constvar`\nz .~ x .+ [ 1, 1 ]\n# Which is equivalent to \narray = [1, 1]\nfor i in 1:n\n z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian \nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Read more about how broadcasting machinery works in Julia in the official documentation.","category":"page"},{"location":"manuals/model-specification/#Node-creation-options","page":"Model specification","title":"Node creation options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A list of the available options specific to the ReactiveMP inference engine is presented below.","category":"page"},{"location":"manuals/model-specification/#Factorisation-constraint-option","page":"Model specification","title":"Factorisation constraint option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"See also Constraints Specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"where RecognitionFactorisationConstraint can be the following","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"MeanField()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a mean-field factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"FullFactorisation()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a full factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"q(μ)q(v)q(out) or q(μ) * q(v) * q(out)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Using interface names of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names for some node\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }\n\n# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names aliases for some node\n# In general aliases correspond to the function names for distribution parameters\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }\n\n# Using random variables names from `~` operator expression\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }\n\n# All methods can be combined easily\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }","category":"page"},{"location":"manuals/model-specification/#Metadata-option","page":"Model specification","title":"Metadata option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"z ~ f(x, y) where { meta = ... }","category":"page"},{"location":"examples/overview/#examples-overview","page":"Overview","title":"Examples overview","text":"","category":"section"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"Basic examples: Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.\nAdvanced examples: Advanced examples contain more complex inference problems.\nProblem specific: Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference","page":"Manual inference specification","title":"Manual inference","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"For advanced use cases it is advised to use manual inference specification. ","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Create a model with @model macro and get a references to random variables and data inputs\nSubscribe to random variable posterior marginal updates \nSubscribe to Bethe Free Energy updates (optional)\nFeed model with observations \nUnsubscribe from posterior marginal updates (optional)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-model-creation","page":"Manual inference specification","title":"Model creation","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random\n\n@model function my_model()\n m2 ~ NormalMeanVariance(0.0, 1.0)\n m1 ~ NormalMeanVariance(m2, 1.0)\n\n y = datavar(Float64)\n y ~ NormalMeanVariance(m1, 1.0)\n\n # Return variables of interests, optional\n return m1, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"And later on we may create our model with the create_model function and obtain references for variables of interests:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m1, y) = create_model(my_model())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Alternatively, it is possible to query any variable using squared brackets on model object:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model[:m1] # m1\nmodel[:y] # y\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-marginal-updates","page":"Manual inference specification","title":"Posterior marginal updates","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_updates = getmarginal(m1)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"After that we can subscribe on new updates and perform some actions based on new values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin\n println(\"New posterior for m1: \", new_posterior)\nend)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function my_model()\n ...\n m_n = randomvar(n)\n ...\n return m_n, ...\nend\n\nmodel, (m_n, ...) = create_model(my_model())\n\nm_n_updates = getmarginals(m_n)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-observations","page":"Manual inference specification","title":"Feeding observations","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To feed an observation for a specific data input we use update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0) # Observation didn't change, should result in the same posterior\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"If y is an array of data inputs it is possible to pass an array of observation to update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"for i in 1:length(data)\n update!(y[i], data[i])\nend\n# is an equivalent of\nupdate!(y, data)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp","page":"Manual inference specification","title":"Variational Message Passing","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"real_mean = -4.0\nreal_precision = 0.2\nrng = MersenneTwister(1234)\n\nn = 100\ndata = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function normal_estimation(n)\n m ~ NormalMeanVariance(0.0, 10.0)\n w ~ Gamma(0.1, 10.0)\n\n y = datavar(Float64, n)\n\n for i in 1:n\n y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }\n end\n\n return m, w, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m, w, y) = create_model(normal_estimation(n))\n\n# We use vague initial marginals\nsetmarginal!(m, vague(NormalMeanVariance)) \nsetmarginal!(w, vague(Gamma))\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m_marginals = []\nw_marginals = []\n\nsubscriptions = subscribe!([\n (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),\n (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),\n])\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(subscriptions)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using Plots\n\np1 = plot(title = \"'Mean' posterior marginals\")\ngrid1 = -6.0:0.01:4.0\n\nfor iter in [ 1, 2, 10 ]\n\n estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = \"Estimated mean after $iter VMP iterations\")\n\nend\n\nplot!(p1, [ real_mean ], seriestype = :vline, label = \"Real mean\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"p2 = plot(title = \"'Precision' posterior marginals\")\ngrid2 = 0.01:0.001:0.35\n\nfor iter in [ 2, 3, 10 ]\n\n estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = \"Estimated precision after $iter VMP iterations\")\n\nend\n\nplot!(p2, [ real_precision ], seriestype = :vline, label = \"Real precision\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp-bfe","page":"Manual inference specification","title":"Computing Bethe Free Energy","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer package exports score function for an observable of free energy values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"fe_observable = score(model, BetheFreeEnergy())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"# Reset posterior marginals for `m` and `w`\nsetmarginal!(m, vague(NormalMeanVariance))\nsetmarginal!(w, vague(Gamma))\n\nfe_values = []\n\nfe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(fe_subscription)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"plot(fe_values, label = \"Bethe Free Energy\", xlabel = \"Iteration #\")","category":"page"},{"location":"contributing/new-package/#Contributing-to-the-dependencies","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.","category":"page"},{"location":"contributing/new-package/#The-benefits-of-small-packages-for-the-ecosystem","page":"Contributing to the dependencies","title":"The benefits of small packages for the ecosystem","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.\nCollaboration: Teams can work on different packages concurrently, speeding up development.\nVersion Control: Precise versioning and fewer dependencies lead to leaner projects.\nPerformance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.\nFlexibility: Developers can select and customize packages for their needs.\nCommunity: Smaller packages attract contributors, fostering collaboration and faster feedback.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.","category":"page"},{"location":"contributing/new-package/#Use-[PkgTemplates](https://github.com/JuliaCI/PkgTemplates.jl)","page":"Contributing to the dependencies","title":"Use PkgTemplates","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> using PkgTemplates\n\njulia> USER = \"your github user name\" # Use `reactivebayes` if developing within the ReactiveBayes organisation\n\njulia> template = Template(\n user = USER, \n plugins = [\n CompatHelper(), \n ProjectFile(), \n SrcDir(), \n Git(), \n License(), \n Readme(), \n Tests(), \n GitHubActions(), \n Codecov(), \n Documenter{GitHubActions}(), \n Formatter(style=\"blue\"), \n BlueStyleBadge(), \n PkgEvalBadge()\n])\n\njulia> template(\"MyNewCoolPackage\")","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the minimum supported version of Julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9.2\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Try to be conservative and set as low version of Julia as possible.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the authors of the package","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The authors field is present in the Project.toml, e.g ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"authors = [\"John Wick \", ...]","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Add requires dependencies and their [compat] bounds","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"or ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] activate .","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Then, add dependencies like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] add SomeCoolDependency, SomeOtherCoolDependency","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9\"\nSomeCoolDependency = \"0.19.2\"\nSomeOtherCoolDependency = \"1.3.12\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For more details on compat bounds, check the official Julia documentation.","category":"page"},{"location":"contributing/new-package/#Adjust-README.md","page":"Contributing to the dependencies","title":"Adjust README.md","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"note: Note\nSome badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.","category":"page"},{"location":"contributing/new-package/#Write-code-and-tests","page":"Contributing to the dependencies","title":"Write code and tests","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.","category":"page"},{"location":"contributing/new-package/#Simplify-Testing-with-ReTestItems","page":"Contributing to the dependencies","title":"Simplify Testing with ReTestItems","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.","category":"page"},{"location":"contributing/new-package/#Write-code-and-the-documentation","page":"Contributing to the dependencies","title":"Write code and the documentation","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=docs docs/make.jl","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.","category":"page"},{"location":"contributing/new-package/#Hosting-Documentation-with-GitHub-Actions","page":"Contributing to the dependencies","title":"Hosting Documentation with GitHub Actions","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.","category":"page"},{"location":"contributing/new-package/#Enable-GitHub-Pages-in-Repository-Settings","page":"Contributing to the dependencies","title":"Enable GitHub Pages in Repository Settings","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Navigate to the GitHub Pages settings of your repository.\nChoose the Deploy from a branch option.\nSelect the gh-pages branch.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#examples-assessing-people’s-skills","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of \"Model-Based Machine Learning\" by Winn et al.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Problem-Statement","page":"Assessing People’s Skills","title":"Problem Statement","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We model the result for question i as a continuous variable r_iin01, and skill/attitude as a binary variable s_i in 0 1, where s_1 represents whether the student has partied, and s_2 and s_3 represent whether the student has studied the chapters for the corresponding questions.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We assume the following logic:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"If the student is alert (has not partied), then they will score on the first question;\nIf the student is alert or has studied chapter two, then they will score on question two;\nIf the student can answer question two and has studied chapter three, then they will score on question three.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Definition","page":"Assessing People’s Skills","title":"Generative Model Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"To model the probability for correct answers, we assume a latent state variable t_i in 01. The dependencies between the variables can then be modeled by the following Bayesian network:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"(s_1) (s_2) (s_3)\n | | |\n v v v\n(t_1)-->(t_2)-->(t_3)\n | | |\n v v v\n(r_1) (r_2) (r_3)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"As prior beliefs, we assume that a student is equally likely to study/party or not: s_i sim Ber(05) for all i. Next, we model the domain logic as beginaligned t_1 = s_1\n t_2 = t_1 s_2\n t_3 = t_2 s_3 endaligned For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as t_i sim Ber(s_i) for all i.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Custom-Nodes-and-Rules","page":"Assessing People’s Skills","title":"Custom Nodes and Rules","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"using RxInfer, Random\n\n# Create Score node\nstruct Score end\n\n@node Score Stochastic [out, in]","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Adding update rule for the Score node\n@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin \n return Bernoulli(mean(q_out))\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Specification","page":"Assessing People’s Skills","title":"Generative Model Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now build the full generative model.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# GraphPPL.jl exports the `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function skill_model()\n s = randomvar(3)\n t = randomvar(3)\n r = datavar(Float64, 3)\n\n # Priors\n for i=1:3\n s[i] ~ Bernoulli(0.5)\n end\n\n # Domain logic\n t[1] ~ ¬s[1]\n t[2] ~ t[1] || s[2]\n t[3] ~ t[2] && s[3]\n \n # Results\n for i=1:3\n r[i] ~ Score(t[i])\n end\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Inference-Specification","page":"Assessing People’s Skills","title":"Inference Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"test_results = [0.1, 0.1, 0.1]\ninference_result = infer(\n model = skill_model(),\n data = (r = test_results, )\n)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Inference results:\n Posteriors | available for (s, t)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Results","page":"Assessing People’s Skills","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Inspect the results\nmap(params, inference_result.posteriors[:s])","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"3-element Vector{Tuple{Float64}}:\n (0.9872448979591837,)\n (0.06377551020408162,)\n (0.4719387755102041,)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"These results suggest that this particular student was very likely out on the town last night.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#examples-predicting-bike-rental-demand","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using RxInfer","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Preamble:-Enabling-Predictions","page":"Predicting Bike Rental Demand","title":"Preamble: Enabling Predictions","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"RxInfer.jl facilitates predictions in two primary ways. ","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.\nExplicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Example","page":"Predicting Bike Rental Demand","title":"Example","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Consider the following model:","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"@model function example_model()\n y = datavar(Float64) where {allow_missing = true}\n\n h ~ NormalMeanPrecision(0, 1.0)\n x ~ NormalMeanPrecision(h, 1.0)\n y ~ NormalMeanPrecision(x, 10.0)\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Implicit Prediction\nresult = infer(model = example_model(), data = (y = missing,))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Explicit Prediction\nresult = infer(model = example_model(), predictvars = (y = KeepLast(),))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using CSV, DataFrames, Plots","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Objective","page":"Predicting Bike Rental Demand","title":"Objective","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Dataset-Source","page":"Predicting Bike Rental Demand","title":"Dataset Source","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Load the data\ndf = CSV.read(\"../data/bike_count/modified_bicycle.csv\", DataFrame)\ndf[1:10, :]","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"10×6 DataFrame\n Row │ datetime temp atemp humidity windspeed count\n │ String31 Float64 Float64 Float64 Float64 Int64\n─────┼──────────────────────────────────────────────────────────────────\n 1 │ 2011-01-01 0:00:00 9.84 14.395 81.0 0.0 16\n 2 │ 2011-01-01 1:00:00 9.02 13.635 80.0 0.0 40\n 3 │ 2011-01-01 2:00:00 9.02 13.635 80.0 0.0 32\n 4 │ 2011-01-01 3:00:00 9.84 14.395 75.0 0.0 13\n 5 │ 2011-01-01 4:00:00 9.84 14.395 75.0 0.0 1\n 6 │ 2011-01-01 5:00:00 9.84 12.88 75.0 6.0032 1\n 7 │ 2011-01-01 6:00:00 9.02 13.635 80.0 0.0 2\n 8 │ 2011-01-01 7:00:00 8.2 12.88 86.0 0.0 3\n 9 │ 2011-01-01 8:00:00 9.84 14.395 75.0 0.0 8\n 10 │ 2011-01-01 9:00:00 13.12 17.425 76.0 0.0 14","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# we reserve few samples for prediction\nn_future = 24\n\nX = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]\ny = Union{Float64, Missing}[df[:, \"count\"]...][1:end-n_future]\n\nstate_dim = length(X[1]); # dimensionality of feature space","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Generative-Model-with-Priors","page":"Predicting Bike Rental Demand","title":"Generative Model with Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"We present a generative model that delineates the latent dynamics of feature evolution, represented by mathbfh_t, and their link to the bike rental counts, mathbfy_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Equations-and-Priors","page":"Predicting Bike Rental Demand","title":"Equations and Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Feature Dynamics with Prior:\nPrior: mathbfa sim mathcalN(mathbf0 mathbfI)\nDynamics: mathbfh_t sim mathcalN(mathbfA h_t-1 mathbfQ)\nmathbfA\nis the transition matrix, reshaped from the prior vector mathbfa, and mathbfQ represents process noise.\nNoisy Observations:\nmathbfx_t sim mathcalN(mathbfh_t mathbfP)\nRepresents the observed noisy state of the features.\nCount Prediction with Prior:\nPrior: boldsymboltheta sim mathcalN(mathbf0 mathbfI)\nPrediction: y_t sim mathcalN(textsoftplus(boldsymboltheta^topmathbfh_t) sigma^2)\nModels the bike rental count as influenced by a non-linear transformation of the hidden state.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Interpretation","page":"Predicting Bike Rental Demand","title":"Interpretation","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This framework aims to simultaneously infer the transition matrix mathbfA and the regression parameters boldsymboltheta, providing a comprehensive view of the feature space dynamics and the count prediction.\nBy employing Gaussian priors on both mathbfa and boldsymboltheta, we incorporate beliefs about their distributions.\nThe inference process aims to discover these underlying dynamics, enabling predictions of both features mathbfx_t and counts y_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We augument the dataset with missing entries for 24 hours ahead\nappend!(X, repeat([missing], n_future))\nappend!(y, repeat([missing], n_future));","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Function to perform the state transition in the model.\n# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.\nfunction transition(a, x)\n nm, n = length(a), length(x)\n m = nm ÷ n # Calculate the number of rows for reshaping 'a' into a matrix\n A = reshape(a, (m, n)) \n return A * x\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"transition (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# The dotsoftplus function combines a dot product and softplus transformation.\n# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,\n# especially if the data suggests other forms of relationships or distributions.\nfunction dotsoftplus(a, x)\n log(1 + exp(dot(a, x)))\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"dotsoftplus (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# model definction\n@model function bicycle_ssm(n, h0, θ0, a0, Q, P)\n\n # `h` is a sequence of hidden states\n h = randomvar(n)\n\n # `x` is a sequence of observed states (features)\n x = datavar(Vector{Float64}, n) where {allow_missing = true}\n # `y` is a sequence of \"count\" bicycles\n y = datavar(Float64, n) where {allow_missing = true}\n\n a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))\n\n θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))\n\n h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))\n h_prev = h_prior\n \n for i in 1:n\n \n h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)\n \n x[i] ~ MvNormal(μ=h[i], Σ=P)\n \n y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)\n \n h_prev = h[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.\n# However, alternative methods like Unscented or CVI approximations can also be considered.\ntransition_meta = @meta begin \n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Meta specification:\n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We define rather uninformative priors \nprior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))\nprior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))\nprior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"MvNormalMeanCovariance(\nμ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0\n.0, 0.0]\nΣ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … \n0.0 1.0]\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages\nimessages = ( h = prior_h, a = prior_a, θ = prior_θ,)\n\nbicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))\n\nresult = infer(\n model = bicycle_model,\n data = (y = y, x=X), \n options = (limit_stack_depth = 500, ), \n returnvars = KeepLast(),\n initmessages = imessages,\n meta = transition_meta,\n iterations = 20,\n showprogress=true,\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (a, h, h_prior, θ)\n Predictions | available for (y, x)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# For a sake of this example, we extract only predictions\nmean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])\nmean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])\n\nmean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)\nmean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)\nmean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)\nmean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"slice = (300, length(y))\ndata = df[:, \"count\"][length(y)-n_future:length(y)]\n\np = scatter(y, \n color=:darkblue, \n markerstrokewidth=0,\n label=\"Observed Count\", \n alpha=0.6)\n\n# Plotting the mean prediction with variance ribbon\nplot!(mean_y, ribbon=sqrt.(cov_y), \n color=:orange, \n fillalpha=0.3,\n label=\"Predicted Mean ± Std Dev\")\n\n# Adding a vertical line to indicate the start of the future prediction\nvline!([length(y)-n_future], \n label=\"Prediction Start\", \n linestyle=:dash, \n linecolor=:green)\n\n# Future (unobserved) data\nplot!(length(y)-n_future:length(y), data, label=\"Future Count\")\n\n# Adjusting the limits\nxlims!(slice)\n\n# Enhancing the plot with titles and labels\ntitle!(\"Bike Rental Demand Prediction\")\nxlabel!(\"Time\")\nylabel!(\"Bike Count\")\n\n# Adjust the legend\nlegend=:topright\n\n# Show the final plot\ndisplay(p)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using Plots\n\n# Define a color palette\npalette = cgrad(:viridis)\n\n# Plot the hidden states with observations\np1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label=\"Hidden State 1\", legend=:topleft)\nplot!(df[!, :temp], color=:grey, label=\"Temperature\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Temperature vs Hidden State 1\")\n\np2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label=\"Hidden State 2\", legend=:topleft)\nplot!(df[!, :atemp], color=:grey, label=\"Feels-Like Temp\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Feels-Like Temp vs Hidden State 2\")\n\np3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label=\"Hidden State 3\", legend=:topleft)\nplot!(df[!, :humidity], color=:grey, label=\"Humidity\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Humidity vs Hidden State 3\")\n\np4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label=\"Hidden State 4\", legend=:topleft)\nplot!(df[!, :windspeed], color=:grey, label=\"Windspeed\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Windspeed vs Hidden State 4\")\n\nfor p in [p1, p2, p3, p4]\n xlims!(p, first(slice), last(slice))\nend\n\nplot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Conclusion","page":"Predicting Bike Rental Demand","title":"Conclusion","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.","category":"page"},{"location":"manuals/comparison/#comparison","page":"RxInfer.jl vs. Others","title":"Comparison to other packages","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"DISCLAIMER: ","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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, and we'll be more than willing to rectify.\nThe comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Toolbox Universality Efficiency Expressiveness Debugging & Visualization Modularity Inference Engine Language Community & Ecosystem\nRxInfer.jl ~ ✓ ✓ ~ ✗ Message-passing Julia ✗\nForneyLab.jl ✗ ~ ✗ ~ ✗ Message-passing Julia ✗\nInfer.net ~ ✓ ✗ ✓ ✗ Message-passing C# ✗\nPGMax ✗ ✓ ✗ ✓ ✗ Message-passing Python ✗\nTuring.jl ✓ ✗ ✓ ~ ✗ Sampling Julia ✓\nPyMC ✓ ✗ ✓ ✓ ✗ Sampling Python ✓\nNumPyro ✓ ✓ ~ ✓ ✗ Sampling Python ✓\nTensorFlow Probability ✓ ✗ ~ ✓ ✗ Sampling Python ✓\nStan ✓ ✗ ✓ ✓ ✗ Sampling Stan ✓","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"(Date of creation: 20/10/2023)","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Legend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"✓ : Full capability or feature is present.\n~ : Partial capability or feature is present.\n✗ : No capability or feature.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Notes:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: Denotes the capability to depict a vast array of probabilistic models.\nEfficiency: Highlights computational competence. A \"–\" in this context suggests perceived slowness.\nExpressiveness: Assesses the ability to concisely formulate intricate probabilistic models.\nDebugging & Visualization: Evaluates the suite of tools for model debugging and visualization.\nModularity: Reflects the potential to create models by integrating smaller models.\nInference Engines: Pinpoints the primary inference strategy employed by the toolbox.\nLanguage: Identifies the programming language integral to the toolbox.\nCommunity & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"","category":"page"},{"location":"manuals/comparison/#RxInfer.jl-breakdown","page":"RxInfer.jl vs. Others","title":"RxInfer.jl breakdown","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.\nEfficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.\nModularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"@model function inner_inner(τ, y)\n y ~ Normal(τ[1], τ[2])\nend\n\n@model function inner(θ, α)\n β ~ Normal(0, 1)\n α ~ Gamma(β, 1)\n α ~ inner_inner(τ = θ)\nend\n\n@model function outer()\n local w\n for i = 1:5\n w[i] ~ inner(θ = Gamma(1, 1))\n end\n y ~ inner(θ = w[2:3])\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"beginaligned\n x sim mathrmNormal(00 10)\n w sim mathrmInverseGamma(10 10)\n y sim mathrmNormal(x w)\nendaligned","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"The model then is expressed in RxInfer.jl as follows:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"using RxInfer\n\n@model function example_model()\n x ~ Normal(mean=0.0, var=1.0)\n w ~ InverseGamma(α = 1, θ = 1)\n y ~ Normal(mean = x, var = w)\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#examples-infinite-data-stream","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"using RxInfer, Plots, Random, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"mutable struct Environment\n rng :: AbstractRNG\n current_state :: Float64\n observation_precision :: Float64\n history :: Vector{Float64}\n observations :: Vector{Float64}\n \n Environment(current_state, observation_precision; seed = 123) = begin \n return new(StableRNG(seed), current_state, observation_precision, [], [])\n end\nend\n\nfunction getnext!(environment::Environment)\n environment.current_state = environment.current_state + 1.0\n nextstate = 10sin(0.1 * environment.current_state)\n observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))\n push!(environment.history, nextstate)\n push!(environment.observations, observation)\n return observation\nend\n\nfunction gethistory(environment::Environment)\n return environment.history\nend\n\nfunction getobservations(environment::Environment)\n return environment.observations\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"getobservations (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Model-specification","page":"Infinite Data Stream","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"@model function kalman_filter()\n \n # Prior for the previous state\n x_prev_mean = datavar(Float64)\n x_prev_var = datavar(Float64)\n \n x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)\n \n # Prior for the observation noise\n τ_shape = datavar(Float64)\n τ_rate = datavar(Float64)\n \n τ ~ Gamma(shape = τ_shape, rate = τ_rate)\n \n # Random walk with fixed precision\n x_current ~ Normal(mean = x_prev, precision = 1.0)\n \n # Noisy observation\n y = datavar(Float64)\n y ~ Normal(mean = x_current, precision = τ)\n \nend\n\n# We assume the following factorisation between variables \n# in the variational distribution\n@constraints function filter_constraints()\n q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"filter_constraints (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Prepare-environment","page":"Infinite Data Stream","title":"Prepare environment","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"initial_state = 0.0\nobservation_precision = 0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"After we have created the environment we can observe how our signal behaves:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"testenvironment = Environment(initial_state, observation_precision);\n\nanimation = @animate for i in 1:100\n getnext!(testenvironment)\n \n history = gethistory(testenvironment)\n observations = getobservations(testenvironment)\n \n p = plot(size = (1000, 300))\n \n p = plot!(p, 1:i, history[1:i], label = \"Hidden signal\")\n p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = \"Observation\")\nend\n\ngif(animation, \"../pics/infinite-data-stream.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-static-dataset","page":"Infinite Data Stream","title":"Filtering on static dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"n = 300\nstatic_environment = Environment(initial_state, observation_precision);\n\nfor i in 1:n\n getnext!(static_environment)\nend\n\nstatic_history = gethistory(static_environment)\nstatic_observations = getobservations(static_environment);\nstatic_datastream = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_static(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n keephistory = 10_000,\n historyvars = (x_current = KeepLast(), τ = KeepLast()),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n free_energy = true,\n autostart = true,\n )\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_static (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"result = run_static(static_environment, static_datastream);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"static_inference = @animate for i in 1:n\n estimated = result.history[:x_current]\n p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = \"Estimation\")\n p = plot!(static_history[1:i], label = \"Real states\") \n p = scatter!(static_observations[1:i], ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\nend\n\ngif(static_inference, \"../pics/infinite-data-stream-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"plot(result.free_energy_history, label = \"Bethe Free Energy (averaged)\")","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-realtime-dataset","page":"Infinite Data Stream","title":"Filtering on realtime dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"Next lets create a \"real\" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_and_plot(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n posteriors = []\n \n plotfn = (q_current) -> begin \n IJulia.clear_output(true)\n \n push!(posteriors, q_current)\n\n p = plot(mean.(posteriors), ribbon = var.(posteriors), label = \"Estimation\")\n p = plot!(gethistory(environment), label = \"Real states\") \n p = scatter!(getobservations(environment), ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\n\n display(p)\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n autostart = false,\n )\n \n qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)\n \n RxInfer.start(engine)\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_and_plot (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# This example runs in our documentation pipeline, which does not support \"real-time\" execution context\n# We skip this code if run not in Jupyter notebook (see below an example with gif)\nengine = nothing \nif isdefined(Main, :IJulia)\n timegen = 41 # 41 ms\n environment = Environment(initial_state, observation_precision);\n observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations\n datastream = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));\n engine = run_and_plot(environment, datastream)\nend;","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"if !isnothing(engine) && isdefined(Main, :IJulia)\n RxInfer.stop(engine)\n IJulia.clear_output(true)\nend;","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#examples-universal-mixtures","page":"Universal Mixtures","title":"Universal Mixtures","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"using RxInfer, Distributions, Random, Plots","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y_i mid theta) = mathrmBer(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where y_i in 01 are the outcomes of the coin tosses, i.e. heads or tails, and where theta is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter theta, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of thetain01 they come up with the prior beliefs:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJohn) = mathrmBeta(theta mid 7 2)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJane) = mathrmBeta(theta mid 2 7)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior beliefs\")\nplot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) John\", c=1)\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"p(θ) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"true_coin = Bernoulli(0.25)\nnr_throws = 10\ndataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))\nnr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)\nprintln(\"experimental outcome: \\n - heads: \", nr_heads, \"\\n - tails: \", nr_tails);","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"experimental outcome: \n - heads: 3\n - tails: 7","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"For computing the posterior beliefs p(theta mid y) about the parameter theta, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#John's-model:","page":"Universal Mixtures","title":"John's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJohn) = p(theta mid textJohn) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_john(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's prior model over θ\n θ ~ Beta(7.0, 2.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#Jane's-model:","page":"Universal Mixtures","title":"Jane's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJane) = p(theta mid textJane) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_jane(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify Jane's prior model over θ\n θ ~ Beta(2.0, 7.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy mathrmF_B bounds the model evidence p(y) as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"mathrmF_Bpq geq - ln p(y)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_john = infer(\n model = beta_model_john(nr_throws), \n data = (y = dataset, ),\n free_energy = true,\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[8.96366]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_jane = infer(\n model = beta_model_jane(nr_throws), \n data = (y = dataset, ),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[6.63988]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying theta parameter. They formulate this through the posterior distributions p(theta mid y textJohn) and p(theta mid y textJane):","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior beliefs\")\nplot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) John\", c=1)\nplot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"p(θ|y) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over theta, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta c mid textMary) = p(c mid textMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where c describes the probability of John being correct as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(c mid textMary) = mathrmBer(c mid 07)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"The predictive distribution p(theta mid textMary) for theta (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over c as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textMary) = sum_cin01 p(cmidtextMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c = 07 cdot p(theta mid textJohn) + 03 cdot p(theta mid textJane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior belief\")\nplot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) Mary\", c=1)\nplot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label=\"\")\nplot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label=\"\")","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_mary(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's and Jane's prior models over θ\n θ_jane ~ Beta(2.0, 7.0)\n θ_john ~ Beta(7.0, 2.0)\n\n # specify initial guess as to who is right\n john_is_right ~ Bernoulli(0.7) \n\n # specify mixture prior Distribution\n θ ~ Mixture(john_is_right, (θ_jane, θ_john))\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This Mixture node updates the belief over c on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_mary = infer(\n model = beta_model_mary(nr_throws), \n data = (y = dataset, ),\n returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),\n addons = AddonLogScale(),\n postprocess = UnpackMarginalPostprocess(),\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (john_is_right, θ_john, θ, θ_jane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over theta also changed, and as expected the estimate from Jane was more prominent.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior belief\")\nplot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) Mary\", c=1)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label=\"\", c=3)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label=\"\", c=3)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/overview/#examples-basic_examples-overview","page":"Overview","title":"Basic examples","text":"","category":"section"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.\nBayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.\nKalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations\nPredicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.\nHow to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#examples-global-parameter-optimisation","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Univariate-State-Space-Model","page":"Global Parameter Optimisation","title":"Univariate State Space Model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us try use the following simple state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n x_t = x_t-1 + c \n y_t sim mathcalNleft(x_t p right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Our goal is to optimize parameters c and m_x_0.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)\n \n x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n)\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ x_prev + c\n y[i] ~ NormalMeanVariance(x[i], P)\n \n x_prev = x[i]\n end\n\n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"rng = MersenneTwister(42)\n\nP = 1.0\nn = 250\nc_real = -5.0\ndata = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# c[1] is C\n# c[2] is μ0\nfunction f(c)\n x0_prior = NormalMeanVariance(c[2], 100.0)\n result = infer(\n model = smoothing(n, x0_prior, c[1], P), \n data = (y = data,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using Optim","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 3.651509e+02 1.001412e+03\n * time: 0.02315521240234375\n * Status: success\n\n * Candidate solution\n Final objective value: 3.645772e+02\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.18e-06 ≰ 0.0e+00\n |x - x'|/|x'| = 2.30e-07 ≰ 0.0e+00\n |f(x) - f(x')| = 9.13e-07 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00\n |g(x)| = 2.56e-06 ≤ 1.0e-03\n\n * Work counters\n Seconds run: 6 (vs limit Inf)\n Iterations: 9\n f(x) calls: 67\n ∇f(x) calls: 67","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"2-element Vector{Float64}:\n 1.0007749243942134\n -5.14368311177876","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", [ 1.0, c_real ])\nprintln(\"Optimized: \", res.minimizer)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: [1.0, -5.0]\nOptimized: [1.0007749243942134, -5.14368311177876]","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Multivariate-state-space-model","page":"Global Parameter Optimisation","title":"Multivariate state space model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us consider the multivariate state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n mathbfx_t sim mathcalNleft(mathbfAx_t-1 mathbfQ right) \n mathbfy_t sim mathcalNleft(mathbfx_t mathbfP right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfx_0 sim mathcalN(mathbfm_x_0 mathbfV_x_0)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"and transition matrix ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfA = beginbmatrix costheta -sintheta sintheta costheta endbmatrix\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Covariance matrices mathbfV_x_0, mathbfP and mathbfQ are known. Our goal is to optimize parameters mathbfm_x_0 and theta.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)\n \n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n \n x_prev = x_prior\n \n A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)\n y[i] ~ MvNormalMeanCovariance(x[i], P)\n \n x_prev = x[i]\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Generate data\nfunction generate_rotate_ssm_data()\n rng = MersenneTwister(1234)\n\n θ = π / 8\n A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\n Q = Matrix(Diagonal(1.0 * ones(2)))\n P = Matrix(Diagonal(1.0 * ones(2)))\n\n n = 300\n\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n \n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(x[i], Q))\n \n x_prev = x[i]\n end\n\n return θ, A, Q, P, n, x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"generate_rotate_ssm_data (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"θ, A, Q, P, n, x, y = generate_rotate_ssm_data();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function f(θ)\n x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))\n result = infer(\n model = rotate_ssm(n, θ[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 2.192003e+04 9.032537e+04\n * time: 7.510185241699219e-5\n * Status: success\n\n * Candidate solution\n Final objective value: 1.161372e+03\n\n * Found with\n Algorithm: L-BFGS\n\n * Convergence measures\n |x - x'| = 5.09e-09 ≰ 0.0e+00\n |x - x'|/|x'| = 4.48e-10 ≰ 0.0e+00\n |f(x) - f(x')| = 0.00e+00 ≤ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14\n |g(x)| = 5.63e-07 ≰ 1.0e-12\n\n * Work counters\n Seconds run: 18 (vs limit Inf)\n Iterations: 9\n f(x) calls: 58\n ∇f(x) calls: 58","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", θ)\nprintln(\"Optimized: \", res.minimizer[1])\n\n@show sin(θ), sin(res.minimizer[1])\n@show cos(θ), cos(res.minimizer[1])","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: 0.39269908169872414\nOptimized: 0.3929332481380117\n(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)\n(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)\n(0.9238795325112867, 0.9237898955654058)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))\n\nresult = infer(\n model = rotate_ssm(n, res.minimizer[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n)\n\nxmarginals = result.posteriors[:x]\n\npx = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"inf₁\")\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"inf₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Learning-Kalman-filter-with-LSTM-driven-dynamic","page":"Global Parameter Optimisation","title":"Learning Kalman filter with LSTM driven dynamic","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Our objective is to compute the marginal posterior distribution of the latent (hidden) state x_k at each time step k, considering the history of measurements up to that time step:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"\np(x_k y_1k)\n\n\nThe above expression represents the probability distribution of the latent state x_k given the measurements y_1k up to time step k\n\njulia\nusing RxInfer BenchmarkTools Flux ReverseDiff Random Plots LinearAlgebra ProgressMeter JLD StableRNGs\n\n\n\n\n Generate data\n\njulia\n Lorenz system equations to be used to generate dataset\nBasekwdef mutable struct Lorenz\n dtFloat64\n σFloat64\n ρFloat64\n βFloat64\n xFloat64\n yFloat64\n zFloat64\nend\n\nfunction step(lLorenz)\n dx = lσ * (ly - lx) lx += ldt * dx\n dy = lx * (lρ - lz) - ly ly += ldt * dy\n dz = lx * ly - lβ * lz lz += ldt * dz\nend\n\n\n\n\njulia\n Dataset\nrng = StableRNG(999)\n\nordered_dataset = \nordered_parameters = \nfor σ = 1115\n for ρ = 2327\n for β_nom = 69\n attractor = Lorenz(002 σ ρ β_nom30 1 1 1)\n noise_free_data = 10 10 10\n for i=199\n step(attractor)\n push(noise_free_data attractorx attractory attractorz)\n end\n push(ordered_dataset noise_free_data)\n push(ordered_parameters σ ρ β_nom30)\n end\n end\nend\n\nnew_order = collect(1100)\nshuffle(rngnew_order)\n\ndataset = noisy dataset\nnoise_free_dataset = noise free dataset\nlorenz_parameters = \n\nfor i in new_order\n local data = \n push(noise_free_dataset ordered_dataseti)\n push(lorenz_parameters ordered_parametersi)\n for nfd in ordered_dataseti\n push(datanfd+randn(rng3))\n end\n push(dataset data)\nend\n\ntrainset = dataset160\nvalidset = dataset6180\ntestset = dataset81end\n\nnoise_free_trainset = noise_free_dataset160\nnoise_free_validset = noise_free_dataset6180\nnoise_free_testset = noise_free_dataset81end\n\n\n\n\n\n Data visualization\n\njulia\none_nonoise=noise_free_trainset1\none=trainset1\ngx gy gz = zeros(100) zeros(100) zeros(100)\nrx ry rz = zeros(100) zeros(100) zeros(100)\nfor i=1100\n rxi ryi rzi = onei1 onei2 onei3\n gxi gyi gzi = one_nonoisei1 one_nonoisei2 one_nonoisei3\nend\np1=plot(rxrylabel=Noise observations)\np1=plot(gxgylabel=True state)\nxlabel(x)\nylabel(y)\np2=plot(rxrzlabel=Noise observations)\np2=plot(gxgzlabel=True state)\nxlabel(x)\nylabel(z)\np3=plot(ryrzlabel=Noise observations)\np3=plot(gygzlabel=True state)\nxlabel(y)\nylabel(z)\nplot(p1 p2 p3 size = (800 200)layout=(13))\n\n\n(assetsexamplesGlobal Parameter Optimisation_22_1png)\n\n\n Inference\n\n\nWe use the following state-space model representation\n\nbeginaligned\nx_k sim p(x_k x_k-1) \ny_k sim p(y_k x_k)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where x_k sim p(x_k x_k-1) represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k-1=NN(y_k-1) \np(x_k x_k-1)=mathcalN(x_k A_k-1x_k-1 Q) \np(y_k x_k)=mathcalN(y_k Bx_k R)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where NN is the neural network. The input is the observation y_k-1, and output is the trasition matrix A_k-1. B denote distortion or measurment matrix. Q and R are covariance matrices. Note that the hidden state x_k comprises three coordinates, i.e. x_k = (rx_k ry_k rz_k)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Neural Network model\nmutable struct NN\n InputLayer\n OutputLater\n g\n params\n function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n InputLayer = Dense(W1, b1, relu)\n Lstm = LSTM(W2_1,W2_2,b2,s2_1)\n OutputLayer = Dense(W3, b3)\n g = Chain(InputLayer, OutputLayer);\n new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))\n end\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Model-specification","page":"Global Parameter Optimisation","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Note that we treat the trasition matrix A_k-1 as time-varying.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#State Space Model\n@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)\n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior_mean = zeros(3)\n x_prior_cov = Matrix(Diagonal(ones(3)))\n \n x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)\n y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }\n \n for i in 2:n\n x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }\n y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }\n end\n \n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We set distortion matrix B and the covariance matrices Q and R as identity matrix.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Q = Matrix(Diagonal(ones(3)))*2\nB = Matrix(Diagonal(ones(3)))\nR = Matrix(Diagonal(ones(3)))\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix A output by the neural network. And the A is treated as a datavar in the inference function.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n n = length(data)\n neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])\n return As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"get_matrix_AS (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"The weights of neural network NN are initialized as follows:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Initial model parameters\nW1, b1 = randn(5, 3)./100, randn(5)./100\nW2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)\nW3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Before network training, we show the inference results for the hidden states:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset before training\nindex = 1\ndata=testset[index]\nn=length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training-network","page":"Global Parameter Optimisation","title":"Training network","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this part, we use the Free Energy as the objective function to optimize the weights of network.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# free energy objective to be optimized during training\nfunction fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n fe_ = 0\n for train_instance in trainset\n result = infer(\n model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = train_instance, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n )\n fe_ += result.free_energy[end]\n end\n return fe_\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"fe_tot_est (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training","page":"Global Parameter Optimisation","title":"Training","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights\n# Uncomment the following code to train the network manually\n# opt = Flux.Optimise.RMSProp(0.006, 0.95)\n# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n# @showprogress for epoch in 1:800\n# grads = ReverseDiff.gradient(fe_tot_est, params);\n# for i=1:length(params)\n# Flux.Optimise.update!(opt,params[i],grads[i])\n# end\n# end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Test","page":"Global Parameter Optimisation","title":"Test","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Import the weights of neural network that we have trained.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load(\"../data/nn_prediction/weights.jld\")[\"data\"];","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset after training\nindex = 1\ndata = testset[index]\nn = length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\n\ngx, gy, gz = zeros(100), zeros(100), zeros(100)\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Prediction","page":"Global Parameter Optimisation","title":"Prediction","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill k and estimate the future state at time k+1, k+2, dots,k+T.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k=NN(x_k) \np(x_k+1 x_k)=mathcalN(x_k+1 A_kx_k Q) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#Define the prediction function\nmultiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))\nsumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)\n\nfunction runForward(A,B,Q,R,mh_old,Vh_old)\n mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)\n mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)\nend\n\nfunction g_predict(mh_old,Vh_old,Q)\n neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)\n # Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])\n As = As[1]\n return runForward(As,B,Q,R,mh_old,Vh_old), As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"g_predict (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"After k=75, the observations are not available, and we predict the future state from k=76 to the end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"tt = 75\nmh = mean(x_est[tt])\nVh = cov(x_est[tt])\nmo_list, Vo_list, A_list = [], [], [] \ninv_Q = inv(Q)\nfor t=1:100-tt\n (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)\n push!(mo_list, mo)\n push!(Vo_list, Vh)\n push!(A_list, A_t)\n global mh = mo\n global Vh = Vo\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Prediction visualization\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\nfor i=1:tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\nfor i=tt+1:100\n ii=i-tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]\nend\np1 = plot(rx,label=\"Ground truth rx\")\np1 = plot!(rx_est_m,label=\"Inffered state rx\",ribbon=rx_est_var)\np1 = scatter!(first.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Ground truth ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index][1:tt], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Ground truth rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#examples-autoregressive-models","page":"Autoregressive Models","title":"Autoregressive Models","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\np(gamma) = mathrmGamma(gammaa b)\np(mathbftheta) = mathcalN(mathbfthetamathbfmu Sigma)\np(x_tmathbfx_t-1t-k) = mathcalN(x_tmathbftheta^Tmathbfx_t-1t-k gamma^-1)\np(y_tx_t) = mathcalN(y_tx_t tau^-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where x_t is a current state of our system, mathbfx_t-1t-k is a sequence of k previous states, k is an order of autoregression process, mathbftheta is a vector of transition coefficients, gamma is a precision of state transition process, y_k is a noisy observation of x_k with precision tau.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's generate some synthetic dataset, we use a predefined sets of coeffcients for k = 1, 3 and 5 respectively:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The following coefficients correspond to stable poles\ncoefs_ar_1 = [-0.27002517200218096]\ncoefs_ar_2 = [0.4511170798064709, -0.05740081602446657]\ncoefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"function generate_ar_data(rng, n, θ, γ, τ)\n order = length(θ)\n states = Vector{Vector{Float64}}(undef, n + 3order)\n observations = Vector{Float64}(undef, n + 3order)\n \n γ_std = sqrt(inv(γ))\n τ_std = sqrt(inv(τ))\n \n states[1] = randn(rng, order)\n \n for i in 2:(n + 3order)\n states[i] = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])\n observations[i] = rand(rng, Normal(states[i][1], τ_std))\n end\n \n return states[1+3order:end], observations[1+3order:end]\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"generate_ar_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Seed for reproducibility\nseed = 123\nrng = MersenneTwister(seed)\n\n# Number of observations in synthetic dataset\nn = 500\n\n# AR process parameters\nreal_γ = 1.0\nreal_τ = 0.5\nreal_θ = coefs_ar_5\n\nstates, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's plot our synthetic dataset:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(first.(states), label = \"Hidden states\")\nscatter!(observations, label = \"Observations\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order k > 1 and for Univariate AR (reduces to simple State-Space-Model) with order k = 1.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function lar_model(T::Type, n, order, c, τ)\n \n \n # We create a sequence of random variables for hidden states\n x = randomvar(n)\n # As well a sequence of observartions\n y = datavar(Float64, n)\n \n ct = constvar(c)\n # We assume observation noise to be known\n cτ = constvar(τ)\n \n γ = randomvar()\n θ = randomvar()\n x0 = randomvar()\n \n # Prior for first state\n if T === Multivariate\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n else\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ Normal(μ = 0.0, γ = 1.0)\n x0 ~ Normal(μ = 0.0, γ = 1.0)\n end\n \n x_prev = x0\n \n for i in 1:n\n \n x[i] ~ AR(x_prev, θ, γ) \n \n if T === Multivariate\n y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)\n else\n y[i] ~ Normal(μ = ct * x[i], γ = cτ)\n end\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@constraints function ar_constraints() \n q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_constraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@meta function ar_meta(artype, order, stype)\n AR() -> ARMeta(artype, order, stype)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_meta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"morder = 5\nmartype = Multivariate\nmc = ReactiveMP.ar_unit(martype, morder)\nmconstraints = ar_constraints()\nmmeta = ar_meta(martype, morder, ARsafe())\n\nmoptions = (limit_stack_depth = 100, )\n\nmmodel = lar_model(martype, length(observations), morder, mc, real_τ)\nmdata = (y = observations, )\nminitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))\nmreturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\n# First execution is slow due to Julia's initial compilation \n# Subsequent runs will be faster (benchmarks are below)\nmresult = infer(\n model = mmodel, \n data = mdata,\n constraints = mconstraints,\n meta = mmeta,\n options = moptions,\n initmarginals = minitmarginals,\n returnvars = mreturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@unpack x, γ, θ = mresult.posteriors","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Dict{Symbol, Vector} with 3 entries:\n :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)\n, Ga…\n :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…\n :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We will use different initial marginals depending on type of our AR process","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p1 = plot(first.(states), label=\"Hidden state\")\np1 = scatter!(p1, observations, label=\"Observations\")\np1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label=\"Inferred states\", legend = :bottomright)\n\np2 = plot(mean.(γ), ribbon = std.(γ), label = \"Inferred transition precision\", legend = :topright)\np2 = plot!([ real_γ ], seriestype = :hline, label = \"Real transition precision\")\n\np3 = plot(mresult.free_energy, label = \"Bethe Free Energy\")\n\nplot(p1, p2, p3, layout = @layout([ a; b c ]))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's also plot a subrange of our results:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"subrange = div(n,5):(div(n, 5) + div(n, 5))\n\nplot(subrange, first.(states)[subrange], label=\"Hidden state\")\nscatter!(subrange, observations[subrange], label=\"Observations\")\nplot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label=\"Inferred states\", legend = :bottomright)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"It is also interesting to see where our AR coefficients converge to:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"let\n pθ = plot()\n\n θms = mean.(θ)\n θvs = var.(θ)\n \n l = length(θms)\n\n edim(e) = (a) -> map(r -> r[e], a)\n\n for i in 1:length(first(θms))\n pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = \"Estimated θ[$i]\")\n end\n \n for i in 1:length(real_θ)\n pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = \"Real θ[$i]\")\n end\n \n plot(pθ, legend = :outertopright, size = (800, 300))\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"$(length(real_θ))-order AR inference Bethe Free Energy: \", last(mresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"5-order AR inference Bethe Free Energy: 1024.0775661298358","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can also run a 1-order AR inference on 5-order AR data:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"uorder = 1\nuartype = Univariate\nuc = ReactiveMP.ar_unit(uartype, uorder)\nuconstraints = ar_constraints()\numeta = ar_meta(uartype, uorder, ARsafe())\n\nuoptions = (limit_stack_depth = 100, )\n\numodel = lar_model(uartype, length(observations), uorder, uc, real_τ)\nudata = (y = observations, )\nuinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))\nureturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\nuresult = infer(\n model = umodel, \n data = udata,\n meta = umeta,\n constraints = uconstraints,\n initmarginals = uinitmarginals,\n returnvars = ureturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"1-order AR inference Bethe Free Energy: \", last(uresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1-order AR inference Bethe Free Energy: 1025.8792949319954","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"if uresult.free_energy[end] > mresult.free_energy[end]\n println(\"We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.\")\nelse\n error(\"AR-1 performs better than AR-5...\") \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can see that, according to final Bethe Free Energy value, in this exampl\ne 5-order AR process can describe data better than 1-order AR.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Autoregressive-Moving-Average-Model","page":"Autoregressive Models","title":"Autoregressive Moving Average Model","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\ne_t sim mathcalN(0 gamma^-1) quad\ntheta sim mathcalMN(mathbf0 mathbfI) quad\neta sim mathcalMN(mathbf0 mathbfI) \nmathbfh_0 sim mathcalMNleft(beginbmatrix\ne_-1 \ne_-2\nendbmatrix mathbfIright) \nmathbfh_t = mathbfSmathbfh_t-1 + mathbfc e_t-1 \nmathbfx_t = boldsymboltheta^topmathbfx_t-1 + boldsymboleta^topmathbfh_t + e_t \nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where shift matrix mathbfS is","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfS = beginpmatrix\n0 0 \n1 0 \nendpmatrix\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"and unit vector mathbfc: ","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfc=1 0\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"when MA order is 2","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this way, mathbfh_t containing errors e_t can be viewed as hidden state.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., boldsymboleta^topmathbfh_t, (2) induced by errors e_t that prevents analytical update of precision parameter gamma (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Load packages\nusing RxInfer, LinearAlgebra, CSV, DataFrames, Plots","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Define shift function\nfunction shift(dim)\n S = Matrix{Float64}(I, dim, dim)\n for i in dim:-1:2\n S[i,:] = S[i-1, :]\n end\n S[1, :] = zeros(dim)\n return S\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"shift (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)\n \n c = zeros(p); c[1] = 1.0; # AR\n b = zeros(q); b[1] = 1.0; # MA\n S = shift(q); # MA\n \n # initialize variables\n h = randomvar(n-1)\n e = randomvar(n)\n z = randomvar(n)\n \n x = datavar(Float64, n) where { allow_missing = true }\n \n # priors\n γ ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))\n η ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))\n θ ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))\n τ ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))\n \n # initial\n h_0 ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))\n z[1] ~ AR(h_0, η, τ)\n e[1] ~ Normal(mean = 0.0, precision = γ)\n\n x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]\n \n h_prev = h_0\n for t in 1:n-1\n \n e[t+1] ~ Normal(mean = 0.0, precision = γ)\n h[t] ~ S*h_prev + b*e[t]\n z[t+1] ~ AR(h[t], η, τ)\n x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]\n h_prev = h[t]\n end\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"x_df = CSV.read(\"../data/arma/aal_stock.csv\", DataFrame)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1259×7 DataFrame\n Row │ date open high low close volume Name\n │ Date Float64 Float64 Float64 Float64 Int64 String3\n──────┼───────────────────────────────────────────────────────────────────\n 1 │ 2013-02-08 15.07 15.12 14.63 14.75 8407500 AAL\n 2 │ 2013-02-11 14.89 15.01 14.26 14.46 8882000 AAL\n 3 │ 2013-02-12 14.45 14.51 14.1 14.27 8126000 AAL\n 4 │ 2013-02-13 14.3 14.94 14.25 14.66 10259500 AAL\n 5 │ 2013-02-14 14.94 14.96 13.16 13.99 31879900 AAL\n 6 │ 2013-02-15 13.93 14.61 13.93 14.5 15628000 AAL\n 7 │ 2013-02-19 14.33 14.56 14.08 14.26 11354400 AAL\n 8 │ 2013-02-20 14.17 14.26 13.15 13.33 14725200 AAL\n ⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮\n 1253 │ 2018-01-30 52.45 53.05 52.36 52.59 4741808 AAL\n 1254 │ 2018-01-31 53.08 54.71 53.0 54.32 5962937 AAL\n 1255 │ 2018-02-01 54.0 54.64 53.59 53.88 3623078 AAL\n 1256 │ 2018-02-02 53.49 53.99 52.03 52.1 5109361 AAL\n 1257 │ 2018-02-05 51.99 52.39 49.75 49.76 6878284 AAL\n 1258 │ 2018-02-06 49.32 51.5 48.79 51.18 6782480 AAL\n 1259 │ 2018-02-07 50.91 51.98 50.89 51.4 4845831 AAL\n 1244 rows omitted","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# we will use \"close\" column\nx_data = filter(!ismissing, x_df[:, 5]);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Plot data\nplot(x_data, xlabel=\"day\", ylabel=\"price\", label=false)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p_order = 10 # AR\nq_order = 4 # MA","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"4","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Training set\ntrain_size = 1000\nx_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]\nx_train = Float64.(x_data[p_order+1:end])[1:train_size];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Test set\nx_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]\nx_test = Float64.(x_data[p_order+1:end])[train_size+1:end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Inference","page":"Autoregressive Models","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Constraints are needed for performing VMP\narma_constraints = @constraints begin\n q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)\nend;","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# This cell defines prior knowledge for model parameters\nh_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nγ_prior = GammaShapeRate(1e4, 1.0)\nτ_prior = GammaShapeRate(1e2, 1.0)\nη_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nθ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Model's graph has structural loops, hence, it requires pre-initialisation\narma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);\narma_imessages = (h_0 = h_prior, h = h_prior);\narma_meta = ar_meta(Multivariate, q_order, ARsafe());","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"result = infer(\n model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), \n data = (x = x_train, ),\n initmarginals = arma_imarginals,\n initmessages = arma_imessages,\n constraints = arma_constraints,\n meta = arma_meta,\n iterations = 50,\n options = (limit_stack_depth = 400, ),\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = \"eₜ\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# extract posteriors\nh_posterior = result.posteriors[:h][end][end]\nγ_posterior = result.posteriors[:γ][end]\nτ_posterior = result.posteriors[:τ][end]\nη_posterior = result.posteriors[:η][end]\nθ_posterior = result.posteriors[:θ][end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Prediction","page":"Autoregressive Models","title":"Prediction","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Here we are going to use our inference results in order to predict the dataset itself","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The prediction function is aimed at approximating the predictive posterior distribution\n# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)\nfunction prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)\n h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))\n ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))\n c = zeros(p); c[1] = 1.0\n b = zeros(q); b[1] = 1.0\n ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)\n θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))\n ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)\n e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))\n ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out) \n @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out) \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"prediction (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"predictions = []\nfor x_prev in x_prev_test\n push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))\n # after every new prediction we can actually \"retrain\" the model to use the power of Bayesian approach\n # we will skip this part at this notebook\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(x_test, label=\"test data\", legend=:topleft)\nplot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label=\"predicted\", xlabel=\"day\", ylabel=\"price\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/#examples-how-to-train-your-hidden-markov-model","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"","category":"section"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate()\n;","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time t, let's call the estimate of the Roomba's position s_t.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call A.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"At time t, we will call our observations x_t and encode the mapping from the Roomba's position to the observations in a matrix we call B. B also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"beginaligned\n s_t sim mathcalCat(A s_t-1)\n x_t sim mathcalCat(B s_t)\nendaligned","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices A and B so we can use them to track the whereabouts of our little cleaning agent.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"To generate our observation data, we'll follow these steps:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.\nDetermine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.\nDetermine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.\nRepeat steps 2-3 for as many samples as we want.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"The following code implements this process and generates our observation data:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"\"\"\"\n rand_vec(rng, distribution::Categorical)\n\nThis function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.\n\"\"\"\nfunction rand_vec(rng, distribution::Categorical) \n k = ncategories(distribution)\n s = zeros(k)\n drawn_category = rand(rng, distribution)\n s[drawn_category] = 1.0\n return s\nend\n\nfunction generate_data(n_samples; seed = 42)\n \n rng = MersenneTwister(seed)\n \n # Transition probabilities \n state_transition_matrix = [0.9 0.0 0.1;\n 0.0 0.9 0.1; \n 0.05 0.05 0.9] \n # Observation noise\n observation_distribution_matrix = [0.9 0.05 0.05;\n 0.05 0.9 0.05;\n 0.05 0.05 0.9] \n # Initial state\n s_initial = [1.0, 0.0, 0.0] \n \n states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states\n observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations\n \n s_prev = s_initial\n \n for t = 1:n_samples\n s_probvec = state_transition_matrix * s_prev\n states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))\n obs_probvec = observation_distribution_matrix * states[t]\n observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))\n s_prev = states[t]\n end\n \n return observations, states\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Test data\nN = 100\nx_data, s_data = generate_data(N);\n\nscatter(argmax.(s_data), leg=false, xlabel=\"Time\",yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the A and B matrices we can use MatrixDirichlet priors. For the A-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on A with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on B. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Model specification\n@model function hidden_markov_model(n)\n \n A ~ MatrixDirichlet(ones(3,3))\n B ~ MatrixDirichlet([ 10.0 1.0 1.0; \n 1.0 10.0 1.0; \n 1.0 1.0 10.0 ])\n \n s_0 ~ Categorical(fill(1.0 / 3.0, 3))\n \n s = randomvar(n)\n x = datavar(Vector{Float64}, n)\n \n s_prev = s_0\n \n for t in 1:n\n s[t] ~ Transition(s_prev, A) \n x[t] ~ Transition(s[t], B)\n s_prev = s[t]\n end\n \nend\n\n# Constraints specification\n@constraints function hidden_markov_model_constraints()\n q(s_0, s, A, B) = q(s_0, s)q(A)q(B)\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"hidden_markov_model_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"imodel = hidden_markov_model(N)\nidata = (x = x_data,)\n\nimarginals = (\n A = vague(MatrixDirichlet, 3, 3), \n B = vague(MatrixDirichlet, 3, 3), \n s = vague(Categorical, 3)\n)\n\nireturnvars = (\n A = KeepLast(),\n B = KeepLast(),\n s = KeepLast()\n)\n\nresult = infer(\n model = imodel, \n data = idata,\n constraints = hidden_markov_model_constraints(),\n initmarginals = imarginals, \n returnvars = ireturnvars, \n iterations = 20, \n free_energy = true\n);","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over A) and about the uncertainty in the roombas observations (A good posterior over B). Let's see if it worked","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for A:\")\nmean(result.posteriors[:A])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for A:\n3×3 Matrix{Float64}:\n 0.871955 0.0290008 0.0572283\n 0.0349989 0.817591 0.135675\n 0.0930457 0.153408 0.807097","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for B:\")\nmean(result.posteriors[:B])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for B:\n3×3 Matrix{Float64}:\n 0.949636 0.0974741 0.0518997\n 0.0244903 0.833632 0.0277884\n 0.0258734 0.0688939 0.920312","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"p1 = scatter(argmax.(s_data), \n title=\"Inference results\", \n label = \"Real\", \n ms = 6, \n legend=:right,\n xlabel=\"Time\" ,\n yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]),\n size=(900,550)\n )\n\np1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),\n label = \"Inferred\",\n ms = 3\n )\n\np2 = plot(result.free_energy, \n label=\"Free energy\",\n xlabel=\"Iteration Number\"\n )\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#examples-rts-vs-bifm-smoothing","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"___Credits to Martin de Quincey___","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762\nH. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"We perform Kalman smoothing in the linear state space model, represented by:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n Z_k+1 = A Z_k + B U_k \n Y_k = C Z_k + W_k\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"with observations Y_k, latent states Z_k and inputs U_k. W_k is the observation noise. A in mathrmR^n times n, B in mathrmR^n times m and C in mathrmR^d times n are the transition matrices in the model. Here n, m and d denote the dimensionality of the latent, input and output dimension, respectively.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"The corresponding probabilistic model can be represented as ","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n p(y z u)\n = p(z_0) prod_k=1^N p(y_k mid z_k) p(z_kmid z_k-1 u_k-1) p(u_k-1) \n = mathcalN(z_0 mid mu_z_0 Sigma_z_0) left( prod_k=1^N mathcalN(y_k mid C z_k Sigma_W) delta(z_k - (Az_k-1 + Bu_k-1)) mathcalN(u_k-1 mid mu_i_k-1 Sigma_u_k-1) right)\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Import-packages","page":"RTS vs BIFM Smoothing","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Data-generation","page":"RTS vs BIFM Smoothing","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)\n \n # define noise levels\n input_noise = 500.0\n output_noise = 50.0\n\n # create random generator for reproducibility\n rng = MersenneTwister(seed)\n\n # generate matrices, input statistics and noise matrices\n A = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat)) # size (dim_lat x dim_lat)\n B = rand(dim_lat, dim_in) # size (dim_lat x dim_in)\n C = rand(dim_out, dim_lat) # size (dim_out x dim_lat)\n μu = rand(dim_in) .* collect(1:dim_in) # size (dim_in x 1)\n Σu = input_noise .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in)))) # size (dim_in x dim_in)\n Σy = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out)))) # size (dim_out x dim_out)\n Wu = inv(Σu)\n Wy = inv(Σy)\n \n # return parameters\n return A, B, C, μu, Σu, Σy, Wu, Wy\n\nend;","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)\n \n # create random data generator\n rng = StableRNG(seed)\n \n # preallocate space for variables\n z = Vector{Vector{Float64}}(undef, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n u = rand(rng, MvNormal(μu, Σu), nr_samples)'\n \n # set initial value of latent states\n z_prev = zeros(size(A,1))\n \n # generate data\n for i in 1:nr_samples\n\n # generate new latent state\n z[i] = A * z_prev + B * u[i,:]\n\n # generate new observation\n y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))\n \n # generate new observation\n z_prev .= z[i]\n \n end\n \n # return generated data\n return z, y, u\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# specify settings\nnr_samples = 200\ndim_out = 3\ndim_in = 3\ndim_lat = 25\n\n# generate parameters\nA, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);\n \n# generate data\ndata_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);\n\n# visualise data\np = Plots.plot(xlabel = \"sample\", ylabel = \"observations\")\n# plot each dimension independently\nfor i in 1:dim_out\n Plots.scatter!(p, getindex.(data_y, i), label = \"y_$i\", alpha = 0.5, ms = 2)\nend\np","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Model-specification","page":"RTS vs BIFM Smoothing","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n \n # fetch dimensionality\n dim_lat = size(A, 1)\n dim_out = size(C, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # hidden states (random variable)\n u = randomvar(nr_samples) # inputs (random variable)\n y = datavar(Vector{Float64}, nr_samples) # outputs (observed variables)\n \n # set initial hidden state\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n \n # update last/previous hidden state\n z_prev = z_prior\n\n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n \n # specify updated hidden state\n z[i] ~ A * z_prev + B * u[i]\n \n # specify observation\n y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n\n # fetch dimensionality\n dim_lat = size(A, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # latent states\n yt = randomvar(nr_samples) # latent observations\n y = datavar(Vector{Float64}, nr_samples) # actual observations\n u = randomvar(nr_samples) # inputs\n \n # set priors\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n z_tmp ~ BIFMHelper(z_prior) where { q = MeanField() }\n \n # update last/previous hidden state\n z_prev = z_tmp\n \n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n\n # specify observation\n yt[i] ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }\n y[i] ~ MvNormalMeanPrecision(yt[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \n # set final value\n z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Probabilistic-inference","page":"RTS vs BIFM Smoothing","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_RTS(data_y, A, B, C, μu, Wu, Wy)\n \n # In this task the inference is unstable and can diverge\n meta = @meta begin \n *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)\n end\n \n result = infer(\n model = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast()),\n meta = meta\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_RTS (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)\n result = infer(\n model = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast())\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_BIFM (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Experiments-for-200-observations","page":"RTS vs BIFM Smoothing","title":"Experiments for 200 observations","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)\nz_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\n\nmz_RTS = mean.(z_RTS)\nmz_BIFM = mean.(z_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:5\n Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\n\nrdata_u = collect(eachrow(data_u))\nmu_RTS = mean.(u_RTS)\nmu_BIFM = mean.(u_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:1\n Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Benchmark","page":"RTS vs BIFM Smoothing","title":"Benchmark","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation\n# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`\nrun_benchmark = false\n\nif run_benchmark\n trials_range = 30\n trials_n = 500\n trials_RTS = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n\n\n @showprogress for k = 1 : trials_range\n\n # generate parameters\n local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);\n \n # generate data|\n local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);\n\n # run inference\n trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n\n end\n\n m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9\n q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9\n m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9\n q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;\n\n p = Plots.plot(ylabel = \"duration [sec]\", xlabel = \"latent state dimension\", title = \"Benchmark\", yscale = :log)\n p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = \"blue\", label = \"mean (RTS)\")\n p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = \"orange\", label = \"mean (BIFM)\")\n Plots.savefig(p, \"../pics/rts_bifm_benchmark.png\")\n p\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"manuals/meta-specification/#user-guide-meta-specification","page":"Meta specification","title":"Meta Specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.","category":"page"},{"location":"manuals/meta-specification/#General-syntax","page":"Meta specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts either regular Julia function or a single begin ... end block:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function MyModelMeta(arg1, arg2)\n Node(y,x) -> MetaObject(arg1, arg2)\nend\n\nmy_meta = @meta begin \n Node(y,x) -> MetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order 5 can be specified as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function ARmodel_meta(num_order)\n AR() -> ARMeta(Univariate, num_order, ARsafe())\nend\n\nmy_meta = ARmodel_meta(5)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"num_order = 5\n\nmy_meta = @meta begin \n AR() -> ARMeta(Multivariate, num_order, ARsafe())\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Both syntax variations provide the same meta specification and there is no preference given to one over the other. ","category":"page"},{"location":"manuals/meta-specification/#Options-specification","page":"Meta specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta [ warn = false ] begin \n ...\nend\n\n@meta [ warn = false ] function MyModelMeta()\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"List of available options:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/meta specification","category":"page"},{"location":"manuals/meta-specification/#Meta-specification","page":"Meta specification","title":"Meta specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"First, let's start with an example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"You can have a list of as many meta specification entries as possible for different nodes:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))\n AR() -> ARMeta(Multivariate, 5, ARsafe())\n MyCustomNode() -> MyCustomMetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model(arguments...)\n ...\nend\n\nmy_meta = @meta begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); meta = my_meta)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"inferred_result = infer(\n model = my_model(arguments...),\n meta = my_meta,\n ...\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model()\n ...\n\n y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }\n\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.","category":"page"},{"location":"manuals/meta-specification/#Create-your-own-meta","page":"Meta specification","title":"Create your own meta","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for your custom node\nstruct MyCustomMeta\n arg1 \n arg2 \nend\n\n# apply the new meta structure to your node\n@meta function model_meta(arg1, arg2)\n MyCustomNode() -> MyCustomMeta(arg1,arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"or create different meta structures for a node, e.g. AR node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for the AR node\nstruct MyARMeta\n arg1\n arg2\nend\n\n# apply the new meta structure to the AR node\n@meta function model_meta(arg1, arg2)\n AR() -> MyARMeta(arg1, arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.","category":"page"},{"location":"manuals/meta-specification/#Example","page":"Meta specification","title":"Example","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"beginaligned\n x sim mathrmNormal(25 05)\n y sim mathrmNormal(2*x 20)\nendaligned","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"where y is observable data and x is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"using RxInfer\n\n#create data\ny_data = 4.0 \n\n#make model\n@model function gaussian_model()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\n#do inference\ninference_result = infer(\n model = gaussian_model(),\n data = (y = y_data,)\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean m clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#create your new meta structure for Normal node\nstruct MetaConstrainedMeanNormal{T}\n lower_limit :: T\n upper_limit :: T\nend\n\n#define rules with meta for the Normal node\n@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))\nend\n\n@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#make model\n@model function gaussian_model_with_meta()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\ncustom_meta = @meta begin\n NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)\nend\n\n#do inference\ninference_result = inference(\n model = gaussian_model(),\n data = (y = y_data,),\n meta = custom_meta\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution","page":"Overview","title":"Inference execution","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"Belief Propagation\nVariational Message Passing","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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.","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-static","page":"Overview","title":"Automatic inference specification on static datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-realtime","page":"Overview","title":"Automatic inference specification on real-time datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-manual-specification","page":"Overview","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#examples-chance-constrained-active-inference","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, \"Chance-constrained active inference\") and discussion with John Boik.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Plots, Distributions, StatsFuns, RxInfer","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Chance-Constraint-Node-Definition","page":"Chance-Constrained Active Inference","title":"Chance-Constraint Node Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not \"overflow\" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"struct ChanceConstraint end \n\n# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol\n@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Function to compute normalizing constant and central moments of a truncated Gaussian distribution\nfunction truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)\n V = clamp(V, tiny, huge)\n StdG = Distributions.Normal(m, sqrt(V))\n TrG = Distributions.Truncated(StdG, a, b)\n \n Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a) # safe mass for standard Gaussian\n \n if Z < tiny\n # Invalid region; return undefined mean and variance of truncated distribution\n Z = 0.0\n m_tr = 0.0\n V_tr = 0.0\n else\n m_tr = Distributions.mean(TrG)\n V_tr = Distributions.var(TrG)\n end\n \n return (Z, m_tr, V_tr)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@rule ChanceConstraint(:out, Marginalisation) (\n m_out::UnivariateNormalDistributionsFamily, # Require inbound message\n q_lo::PointMass, \n q_hi::PointMass, \n q_epsilon::PointMass, \n q_atol::PointMass) = begin \n\n # Extract parameters\n lo = mean(q_lo)\n hi = mean(q_hi)\n epsilon = mean(q_epsilon)\n atol = mean(q_atol)\n \n (m_bw, V_bw) = mean_var(m_out)\n (xi_bw, W_bw) = (m_bw, 1. /V_bw) # check division by zero\n (m_tilde, V_tilde) = (m_bw, V_bw)\n \n # Compute statistics (and normalizing constant) of q in safe region G\n # Phi_G is called the \"safe mass\" \n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)\n\n xi_fw = xi_bw\n W_fw = W_bw\n if epsilon <= 1.0 - Phi_G # If constraint is active\n # Initialize statistics of uncorrected belief\n m_tilde = m_bw\n V_tilde = V_bw\n for i = 1:100 # Iterate at most this many times\n (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G\n (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G\n\n # Compute moments of non-G region as a mixture of left and right truncations\n Phi_nG = Phi_lG + Phi_rG\n m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG\n V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2\n\n # Compute moments of corrected belief as a mixture of G and non-G regions\n m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG\n V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2\n # Re-compute statistics (and normalizing constant) of corrected belief\n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)\n if (1.0 - Phi_G) < (1.0 + atol)*epsilon\n break # Break the loop if the belief is sufficiently corrected\n end\n end\n \n # Convert moments of corrected belief to canonical form\n W_tilde = inv(V_tilde)\n xi_tilde = W_tilde * m_tilde\n\n # Compute canonical parameters of forward message\n xi_fw = xi_tilde - xi_bw\n W_fw = W_tilde - W_bw\n end\n\n return NormalWeightedMeanPrecision(xi_fw, W_fw)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Definition-of-the-Environment","page":"Chance-Constrained Active Inference","title":"Definition of the Environment","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile\n\nfunction initializeWorld()\n x_0 = 0.0 # Initial elevation\n \n x_t_last = x_0\n function execute(t::Int64, a_t::Float64)\n x_t = x_t_last + a_t + wind(t) # Update elevation\n \n x_t_last = x_t # Reset state\n \n return x_t\n end\n\n x_t = x_0 # Predefine outcome variable\n observe() = x_t # State is fully observed\n\n return (execute, observe)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Generative-Model-for-Regulator","page":"Chance-Constrained Active Inference","title":"Generative Model for Regulator","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@model function regulator_model(; T, lo, hi, epsilon, atol)\n # Fully observed state\n x_t = datavar(Float64)\n\n # Control prior statistics\n m_u = datavar(Float64, T)\n v_u = datavar(Float64, T) \n \n # Random variables\n u = randomvar(T) # Control\n x = randomvar(T) # Elevation\n \n # Loop over horizon\n x_k_last = x_t\n for k = 1:T\n u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior\n x[k] ~ x_k_last + u[k] # Transition model\n x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state\n pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency\n x_k_last = x[k]\n end\n \n return (u, x)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Reactive-Agent-Definition","page":"Chance-Constrained Active Inference","title":"Reactive Agent Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"function initializeAgent()\n # Set control prior statistics\n m_u = zeros(T)\n v_u = lambda^(-1)*ones(T)\n \n function compute(x_t::Float64)\n model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)\n data_t = (m_u = m_u, v_u = v_u, x_t = x_t)\n \n result = infer(\n model = model_t, \n data = data_t,\n iterations = n_its)\n\n # Extract policy from inference results\n pol = mode.(result.posteriors[:u][end])\n\n return pol\n end\n\n pol = zeros(T) # Predefine policy variable\n act() = pol[1]\n\n return (compute, act)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Action-Perception-Cycle","page":"Chance-Constrained Active Inference","title":"Action-Perception Cycle","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Simulation parameters\nN = 160 # Total simulation time\nT = 1 # Lookahead time horizon\nlambda = 1.0 # Control prior precision\nlo = 1.0 # Chance region lower bound\nhi = Inf # Chance region upper bound\nepsilon = 0.01 # Allowed chance violation\natol = 0.01 # Convergence tolerance for chance constraints\nn_its = 10; # Number of inference iterations","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(execute, observe) = initializeWorld() # Let there be a world\n(compute, act) = initializeAgent() # Let there be an agent\n\na = Vector{Float64}(undef, N) # Actions\nx = Vector{Float64}(undef, N) # States\nfor t = 1:N\n a[t] = act()\n execute(t, a[t])\n x[t] = observe()\n compute(x[t])\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Results","page":"Chance-Constrained Active Inference","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Results show that the agent does not allow the wind to push it all the way to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"p1 = plot(1:N, wind.(1:N), color=\"blue\", label=\"Wind\", ylabel=\"Velocity\", lw=2)\nplot!(p1, 1:N, a, color=\"red\", label=\"Control\", lw=2)\np2 = plot(1:N, x, color=\"black\", lw=2, label=\"Agent\", ylabel=\"Elevation\")\nplot(p1, p2, layout=(2,1))","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#examples-gamma-mixture-model","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Load-packages","page":"Gamma Mixture Model","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"using RxInfer, Random, StatsPlots","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# create custom structure for model parameters for simplicity\nstruct GammaMixtureModelParameters\n nmixtures # number of mixtures\n priors_as # tuple of priors for variable a\n priors_bs # tuple of priors for variable b\n prior_s # prior of variable s\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Model-specification","page":"Gamma Mixture Model","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)\n\n # fetch information from struct\n nmixtures = parameters.nmixtures\n priors_as = parameters.priors_as\n priors_bs = parameters.priors_bs\n prior_s = parameters.prior_s\n\n # set prior on global selection variable\n s ~ Dirichlet(probvec(prior_s))\n\n # allocate vectors of random variables\n as = randomvar(nmixtures)\n bs = randomvar(nmixtures)\n\n # set priors on variables of mixtures\n for i in 1:nmixtures\n as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))\n bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))\n end\n\n # introduce random variables for local selection variables and data\n z = randomvar(nobservations)\n y = datavar(Float64, nobservations)\n\n # convert vector to tuples for proper functioning of GammaMixture node\n tas = tuple(as...)\n tbs = tuple(bs...)\n\n # specify local selection variable and data generating process\n for i in 1:nobservations\n z[i] ~ Categorical(s)\n y[i] ~ GammaMixture(z[i], tas, tbs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"constraints = @constraints begin \n\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n\n q(as) = q(as[begin])..q(as[end])\n q(bs) = q(bs[begin])..q(bs[end])\n \n q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Constraints:\n marginals form:\n q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n q(as) = q(as[(begin)..(end)])\n q(bs) = q(bs[(begin)..(end)])\nOptions:\n warn = true","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify seed and number of data points\nrng = MersenneTwister(43)\nn_samples = 2500\n\n# specify parameters of mixture model that generates the data\n# Note that mixture components have exactly the same means\nmixtures = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]\nnmixtures = length(mixtures)\nmixing = rand(rng, nmixtures)\nmixing = mixing ./ sum(mixing)\nmixture = MixtureModel(mixtures, mixing)\n\n# generate data set\ndataset = rand(rng, mixture, n_samples);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify priors of probabilistic model\n# NOTE: As the means of the mixtures \"collide\", we specify informative prior for selector variable\nnmixtures = 2\ngpriors = GammaMixtureModelParameters(\n nmixtures, # number of mixtures\n [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ], # priors on variables a\n [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ], # priors on variables b\n Dirichlet(1e3*mixing) # prior on variable s\n)\n\ngmodel = gamma_mixture_model(length(dataset), gpriors)\ngdata = (y = dataset, )\nginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))\ngreturnvars = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())\n\ngoptions = (\n \n default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently\n)\n\ngresult = infer(\n model = gmodel, \n data = gdata,\n constraints = constraints,\n options = (limit_stack_depth = 100,),\n initmarginals = ginitmarginals,\n returnvars = greturnvars,\n free_energy = true,\n iterations = 250, \n showprogress = true\n);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# extract inferred parameters\n_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])\n_dists = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))\n_mixing = mean(gresult.posteriors[:s])\n\n# create model from inferred parameters\n_mixture = MixtureModel(_dists, _mixing);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# report on outcome of inference\nprintln(\"Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))\")\nprintln(\"Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))\")\nprintln(\"========\")\nprintln(\"Generated mixing: $(mixing)\")\nprintln(\"Inferred mixing: $(_mixing)\")","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Generated means: 0.3333333333333333 and 0.33333333333333337\nInferred means: 0.33822470398804994 and 0.33305534672666653\n========\nGenerated mixing: [0.18923488676601088, 0.8107651132339891]\nInferred mixing: [0.11395888467453213, 0.8860411153254679]","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# plot results\np1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np1 = plot!(mixture, label=false, title=\"Generated mixtures\", linewidth=3.0)\n\np2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np2 = plot!(_mixture, label=false, title=\"Inferred mixtures\", linewidth=3.0)\n\n# evaluate the convergence of the algorithm by monitoring the BFE\np3 = plot(gresult.free_energy, label=false, xlabel=\"iterations\", title=\"Bethe FE\")\n\nplot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#examples-gaussian-mixture","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Load-packages","page":"Gaussian Mixture","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Univariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Univariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Consider the data set of length N observed below.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_univariate_data(nr_samples; rng = MersenneTwister(123))\n\n # data generating parameters\n class = [1/3, 2/3]\n mean1, mean2 = -10, 10\n precision = 1.777\n\n # generate data\n z = rand(rng, Categorical(class), nr_samples)\n y = zeros(nr_samples)\n for k in 1:nr_samples\n y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_univariate = generate_univariate_data(100)\nhistogram(data_univariate, bins=50, label=\"data\", normed=true)\nxlims!(minimum(data_univariate), maximum(data_univariate))\nylims!(0, Inf)\nylabel!(\"relative occurrence [%]\")\nxlabel!(\"y\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m w z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(w_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmBeta(s mid alpha_s beta_s) \n p(m_k) = mathcalN(m_k mid mu_k sigma_k^2) p(w_k) = Gamma(w_k mid alpha_k beta_k) \n p(z_n mid s) = mathrmBer(z_n mid s) \n p(y_n mid m w z_n) = prod_k=1^K mathcalNleft(y_n mid m_k w_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions w = w_1 w_2 ldots w_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Here we implement the following model with uninformative values for the hyperparameters as","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function univariate_gaussian_mixture_model(nr_samples)\n \n s ~ Beta(1.0, 1.0)\n \n m1 ~ Normal(mean = -2.0, var = 1e3)\n w1 ~ Gamma(shape = 0.01, rate = 0.01)\n \n m2 ~ Normal(mean = 2.0, var = 1e3)\n w2 ~ Gamma(shape = 0.01, rate = 0.01)\n \n z = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n \n for n in 1:nr_samples\n z[n] ~ Bernoulli(s)\n y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m w mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m w mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(w_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmBeta(s mid hatalpha_s hatbeta_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatsigma^2_k) \n q(w_k) = Gamma (w_k mid hatalpha_k hatbeta_k) \n q(z_n) = mathrmBer(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"results_univariate = infer(\n model = univariate_gaussian_mixture_model(length(data_univariate)), \n constraints = MeanField(),\n data = (y = data_univariate,), \n initmarginals = (\n s = vague(Beta), \n m1 = NormalMeanVariance(-2.0, 1e3), \n m2 = NormalMeanVariance(2.0, 1e3), \n w1 = vague(GammaShapeRate), \n w2 = vague(GammaShapeRate)\n ), \n iterations = 10, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m2, m1, s, w2, w1, z)\n Free Energy: | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.\n277, 135.277, 135.277, 135.277, 135.277]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen as a function of the iterations","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L\"posterior $m_1$\")\nmp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L\"posterior $m_2$\")\nmp = plot!(mp, [ -10 ], seriestype = :hline, label = L\"true $m_1$\")\nmp = plot!(mp, [ 10 ], seriestype = :hline, label = L\"true $m_2$\")\n\nwp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L\"posterior $w_1$\", legend = :bottomright, ylim = (-1, 3))\nwp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L\"posterior $w_2$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_1$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_2$\")\n\nswp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L\"posterior $s$\")\nswp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L\"true $s$\")\n\nfep = plot(results_univariate.free_energy, label = \"Free Energy\", legend = :topright)\n\nplot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))\nxlabel!(\"iteration\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Multivariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Multivariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The above example can also be extended to the multivariate case. Consider the data set below","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))\n\n L = 50.0\n nr_mixtures = 6\n\n probvec = normalize!(ones(nr_mixtures), 1)\n\n switch = Categorical(probvec)\n\n gaussians = map(1:nr_mixtures) do index\n angle = 2π / nr_mixtures * (index - 1)\n basis_v = L * [ 1.0, 0.0 ]\n R = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]\n mean = R * basis_v \n covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))\n return MvNormal(mean, covariance)\n end\n\n z = rand(rng, switch, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n\n for n in 1:nr_samples\n y[n] = rand(rng, gaussians[z[n]])\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_multivariate = generate_multivariate_data(500)\n\nsdim(n) = (a) -> map(d -> d[n], a) # helper function\nscatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)\nxlabel!(L\"y_1\")\nylabel!(L\"y_2\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification-2","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m W z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(W_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmDir(s mid alpha_s) \n p(m_k) = mathcalN(m_k mid mu_k Sigma_k) p(W_k) = mathcalW(W_k mid V_k nu_k) \n p(z_n mid s) = mathrmCat(z_n mid s) \n p(y_n mid m W z_n) = prod_k=1^K mathcalNleft(y_n mid m_k W_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions W = W_1 W_2 ldots W_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)\n \n z = randomvar(nr_samples)\n m = randomvar(nr_mixtures)\n w = randomvar(nr_mixtures)\n y = datavar(Vector{Float64}, nr_samples)\n \n for k in 1:nr_mixtures \n m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])\n w[k] ~ Wishart(3, 1e2*diagm(ones(2)))\n end\n \n s ~ Dirichlet(ones(nr_mixtures))\n \n means = tuple(m...)\n precs = tuple(w...)\n \n for n in 1:nr_samples\n z[n] ~ Categorical(s) \n y[n] ~ NormalMixture(z[n], means, precs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference-2","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m W mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m W mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(W_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmDir(s mid hatalpha_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatSigma_k) \n q(w_k) = mathcalW(W_k mid hatV_k hatnu_k) \n q(z_n) = mathrmCat(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"rng = MersenneTwister(121)\nm = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]\nresults_multivariate = infer(\n model = multivariate_gaussian_mixture_model(\n 6, \n length(data_multivariate), \n m,\n [diagm(1e2 * ones(2)) for k in 1:6]\n ), \n data = (y = data_multivariate,), \n constraints = MeanField(),\n initmarginals = (\n s = vague(Dirichlet, 6), \n m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], \n w = Wishart(3, diagm(1e2 * ones(2)))\n ), \n iterations = 50, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m, w, s, z)\n Free Energy: | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49 … 3894.49, 3894.49, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results-2","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title=\"Data\", xlims=(-75, 75), ylims=(-75, 75))\np_result = plot(xlims = (-75, 75), ylims = (-75, 75), title=\"Inference result\", legend=false, colorbar = false)\nfor (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])\n gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))\n global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title=\"Inference result\", legend=false, levels = 7, colorbar = false)\nend\np_fe = plot(results_multivariate.free_energy, label = \"Free Energy\")\n\nplot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#examples-kalman-filtering-and-smoothing","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We then solve an identification problem which does not have an analytical solution.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Utimately, we show how RxInfer.jl can deal with missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Gaussian-Linear-Dynamical-System","page":"Kalman filtering and smoothing","title":"Gaussian Linear Dynamical System","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"LGSSM can be described with the following equations:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n p(x_ix_i - 1) = mathcalN(x_iA * x_i - 1 mathcalP)\n p(y_ix_i) = mathcalN(y_iB * x_i mathcalQ)\nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"where x_i are hidden states, y_i are noisy observations, A, B are state transition and observational matrices, mathcalP and mathcalQ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(rng, A, B, Q, P)\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(B * x[i], P))\n x_prev = x[i]\n end\n \n return x, y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Seed for reproducibility\nseed = 1234\n\nrng = MersenneTwister(1234)\n\n# We will model 2-dimensional observations with rotation matrix `A`\n# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`\n# are known and fixed for all time-steps\nθ = π / 35\nA = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\nB = diageye(2)\nQ = diageye(2)\nP = 25.0 .* diageye(2)\n\n# Number of observations\nn = 300;","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x, y = generate_data(rng, A, B, Q, P);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\npx = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To create a model we use GraphPPL package and @model macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rotate_ssm(n, x0, A, B, Q, P)\n \n # We create constvar references for better efficiency\n cA = constvar(A)\n cB = constvar(B)\n cQ = constvar(Q)\n cP = constvar(P)\n \n # `x` is a sequence of hidden states\n x = randomvar(n)\n # `y` is a sequence of \"clamped\" observations\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n x_prev = x_prior\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)\n y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)\n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference we also specify prior for out first hidden state:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. \n# infer(..., options = (limit_stack_depth = 500, ))`\nresult = infer(\n model = rotate_ssm(length(y), x0, A, B, Q, P), \n data = (y = y,),\n free_energy = true\n);\n\nxmarginals = result.posteriors[:x]\nlogevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\n\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :teal)\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :violet)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"logevidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"1-element Vector{Float64}:\n -1882.2434870099778","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We may be also interested in performance of our resulting Belief Propagation algorithm:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@benchmark infer(\n model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), \n data = (y = $y,)\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"BenchmarkTools.Trial: 142 samples with 1 evaluation.\n Range (min … max): 27.355 ms … 90.160 ms ┊ GC (min … max): 0.00% … 22.03\n%\n Time (median): 32.762 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 35.468 ms ± 9.416 ms ┊ GC (mean ± σ): 6.92% ± 10.68\n%\n\n ▃▆██▆█▄ ▁▁▁ \n ████████▅▁▅▅███▁▅▇▅▅▅▁▇▅▁▅▁▁▁▅▁▁▁▁▁▁▅▁▁▁▁▁▁▁▁▅▁▁▁▁▁▁▁▁▁▁▁▁▅ ▅\n 27.4 ms Histogram: log(frequency) by time 87.8 ms <\n\n Memory estimate: 9.73 MiB, allocs estimate: 226250.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#System-Identification-Problem","page":"Kalman filtering and smoothing","title":"System Identification Problem","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Distributions, StableRNGs, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)\n\n rng = StableRNG(seed)\n\n real_x = Vector{Float64}(undef, n)\n real_w = Vector{Float64}(undef, n)\n real_y = Vector{Float64}(undef, n)\n\n for i in 1:n\n real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))\n real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))\n real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))\n\n x_i_min = real_x[i]\n w_i_min = real_w[i]\n end\n \n return real_x, real_w, real_y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-1:-y-x-w","page":"Kalman filtering and smoothing","title":"Combination 1: y = x + w","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 250\nreal_x, real_w, real_y = generate_data(+, n);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, real_x, label = \"x\")\npl = plot!(pl, real_w, label = \"w\")\n\npr = plot(title = \"Combined y = x + w\")\npr = scatter!(pr, real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x = randomvar(n)\n w = randomvar(n)\n s = randomvar(n)\n y = datavar(Float64, n)\n \n x_i_min = x0\n w_i_min = w0\n \n for i in 1:n\n x[i] ~ Normal(mean = x_i_min, precision = τ_x)\n w[i] ~ Normal(mean = w_i_min, precision = τ_w)\n s[i] ~ f(x[i], w[i])\n y[i] ~ Normal(mean = s[i], precision = τ_y)\n \n x_i_min = x[i]\n w_i_min = w[i]\n end\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin \n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y\n)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The next step is to assign priors, initialise needed messages and marginals and call the inference function:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"m_x_0, τ_x_0 = -20.0, 1.0\nm_w_0, τ_w_0 = 20.0, 1.0\n\n# We set relatively strong priors for random walk noise components\n# and sort of vague prior for the noise of the observations\na_x, b_x = 0.01, 0.01var(real_x)\na_w, b_w = 0.01, 0.01var(real_w)\na_y, b_y = 1.0, 1.0\n\n# We set relatively strong priors for messages\nxinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))\nwinit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))\n\nimessages = (x = xinit, w = winit)\nimarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))\n\nresult = infer(\n model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),\n data = (y = real_y,), \n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = imessages, \n initmarginals = imarginals, \n iterations = 50\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's examine our inference results:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"τ_x_marginals = result.posteriors[:τ_x]\nτ_w_marginals = result.posteriors[:τ_w]\nτ_y_marginals = result.posteriors[:τ_y]\n\nsmarginals = result.posteriors[:s]\nxmarginals = result.posteriors[:x]\nwmarginals = result.posteriors[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-2:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Combination 2: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Smoothed version of `min` without zero-ed derivatives\nfunction smooth_min(x, y) \n if x < y\n return x + 1e-4 * y\n else\n return y + 1e-4 * x\n end\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"smooth_min (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_meta = @meta begin \n # In this example we are going to use a simple `Linearization` method\n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 200\nmin_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, min_real_x, label = \"x\")\npl = plot!(pl, min_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, min_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_m_x_0, min_τ_x_0 = -1.0, 1.0\nmin_m_w_0, min_τ_w_0 = 1.0, 1.0\n\nmin_a_x, min_b_x = 1.0, 1.0\nmin_a_w, min_b_w = 1.0, 1.0\nmin_a_y, min_b_y = 1.0, 1.0\n\nmin_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))\nmin_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))\n\nmin_result = infer(\n model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),\n data = (y = min_real_y,), \n meta = min_meta,\n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = min_imessages, \n initmarginals = min_imarginals, \n iterations = 100\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_τ_x_marginals = min_result.posteriors[:τ_x]\nmin_τ_w_marginals = min_result.posteriors[:τ_w]\nmin_τ_y_marginals = min_result.posteriors[:τ_y]\n\nmin_smarginals = min_result.posteriors[:s]\nmin_xmarginals = min_result.posteriors[:x]\nmin_wmarginals = min_result.posteriors[:w]\n\npx1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, min_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, min_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, min_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks). ","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Online-(filtering)-identification:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Online (filtering) identification: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rx_identification(f)\n \n # We are going to continuosly update our priors\n # based on new posteriors\n m_x_0 = datavar(Float64) \n τ_x_0 = datavar(Float64)\n m_w_0 = datavar(Float64) \n τ_w_0 = datavar(Float64)\n a_x = datavar(Float64) \n b_x = datavar(Float64)\n a_y = datavar(Float64) \n b_y = datavar(Float64)\n a_w = datavar(Float64) \n b_w = datavar(Float64)\n s = randomvar()\n y = datavar(Float64)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x ~ Normal(mean = x0, precision = τ_x)\n w ~ Normal(mean = w0, precision = τ_w)\n\n s ~ f(x, w)\n y ~ Normal(mean = s, precision = τ_y)\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We impose structured mean-field assumption for this model as well:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_constraints = @constraints begin \n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ\n_y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"autoupdates = @autoupdates begin \n m_x_0, τ_x_0 = mean_precision(q(x))\n m_w_0, τ_w_0 = mean_precision(q(w))\n a_x = shape(q(τ_x)) \n b_x = rate(q(τ_x))\n a_y = shape(q(τ_y))\n b_y = rate(q(τ_y))\n a_w = shape(q(τ_w)) \n b_w = rate(q(τ_w))\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_\nx = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_\ny)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_meta = @meta begin \n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 300\nrx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, rx_real_x, label = \"x\")\npl = plot!(pl, rx_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"engine = infer(\n model = rx_identification(smooth_min),\n constraints = rx_constraints,\n data = (y = rx_real_y,),\n autoupdates = autoupdates,\n meta = rx_meta,\n returnvars = (:x, :w, :τ_x, :τ_w, :τ_y, :s),\n keephistory = 1000,\n historyvars = KeepLast(),\n initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),\n iterations = 10,\n free_energy = true, \n free_energy_diagnostics = nothing,\n autostart = true,\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInferenceEngine:\n Posteriors stream | enabled for (w, s, τ_x, τ_w, τ_y, x)\n Free Energy stream | enabled\n Posteriors history | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)\n Free Energy history | available\n Enabled events | [ ]","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_smarginals = engine.history[:s]\nrx_xmarginals = engine.history[:x]\nrx_wmarginals = engine.history[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, rx_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = \"Estimated X\")\n\npx1 = plot!(px1, rx_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = \"Estimated W\")\n\npx2 = scatter!(px2, rx_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the \"disabled\" state, does not infer anything and simply increases its variance (which is expected for the random walk).","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Handling-Missing-Data","page":"Kalman filtering and smoothing","title":"Handling Missing Data","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let us assume that the following model generates the data","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n x_t sim mathcalNleft(x_t-1 10right) \n y_t sim mathcalNleft(x_t P right) \nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation haty_t in mathrmR we sometimes will catch missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function smoothing(n, x0)\n \n P ~ Gamma(shape = 0.001, scale = 0.001)\n x_prior ~ Normal(mean = mean(x0), var = var(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ Normal(mean = x_prev, precision = 1.0)\n y[i] ~ Normal(mean = x[i], precision = P)\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We need to manually extend the set of rules to support ::Missing values","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"P = 1.0\nn = 250\n\nreal_signal = map(e -> sin(0.05 * e), collect(1:n))\nnoisy_data = real_signal + rand(Normal(0.0, sqrt(P)), n);\nmissing_indices = 100:125\nmissing_data = similar(noisy_data, Union{Float64, Missing}, )\n\ncopyto!(missing_data, noisy_data)\n\nfor index in missing_indices\n missing_data[index] = missing\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0_prior = NormalMeanVariance(0.0, 1000.0)\n\nresult = infer(\n model = smoothing(n, x0_prior), \n data = (y = missing_data,), \n constraints = constraints,\n initmarginals = (P = Gamma(0.001, 0.001), ),\n returnvars = (x = KeepLast(),),\n iterations = 20\n);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"plot(real_signal, label = \"Noisy signal\", legend = :bottomright)\nscatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = \"Missing region\")\nplot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = \"Estimated hidden state\")","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#examples-conjugate-computational-variational-message-passing-(cvi)","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#An-example:-nonlinear-dynamical-system","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"An example: nonlinear dynamical system","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position z_t at time t. Instead they have access to the observed squared distance y_t between the object and some reference point s. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# data generating process\nnr_observations = 50\nreference_point = 53\nhidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)\nmeasurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot hidden location and reference frame\np1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label=\"hidden location\")\nhline!([reference_point], linewidth=3, label=\"reference point\")\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot measurements\np2 = scatter(1:nr_observations, measurements, linewidth=3, label=\"measurements\")\nxlabel!(\"time [sec]\"), ylabel!(\"squared distance [cm2]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"beginaligned\n p(tau) = Gamma(tau mid alpha_tau beta_tau)\n p(gamma) = Gamma(gamma mid alpha_gamma beta_gamma)\n p(z_t mid z_t - 1 tau) = mathcalN(z_t mid z_t - 1 + 1 tau^-1)\n p(y_t mid z_t gamma) = mathcalN(y_t mid (z_t - s)^2 gamma^-1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"where the researchers put priors on the process and measurement noise parameters, tau and gamma, respectively. They do this, because they do not know the accuracy of their devices.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"function compute_squared_distance(z)\n (z - reference_point)^2\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function measurement_model(nr_observations)\n\n # allocate random variables and observations\n z = randomvar(nr_observations)\n y = datavar(Float64, nr_observations)\n\n # set priors on precision parameters\n τ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n γ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n \n # specify estimate of initial location\n z[1] ~ Normal(mean = 0, precision = τ)\n y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)\n\n # loop over observations\n for t in 2:nr_observations\n\n # specify state transition model\n z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)\n\n # specify non-linear observation model\n y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)\n \n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)\n compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function model_meta(...)\n f() -> CVI(args...)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"See ?CVI for more information about the args....","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In the above example, we will assume the following posterior factorization:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function measurement_constraints()\n q(z, τ, γ) = q(z)q(τ)q(γ)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function posterior_constraints() begin\n q(z, γ) = q(z)q(γ) # CVI\n q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"results = infer(\n model = measurement_model(nr_observations),\n data = (y = measurements,),\n iterations = 5,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = measurement_constraints(),\n meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),\n initmessages = (z = NormalMeanVariance(0, 5),),\n initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),\n)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Inference results:\n Posteriors | available for (z)\n Free Energy: | Real[1241.91, 429.933, 376.869, 365.774, 362.879]","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot estimates for location\np1 = plot(collect(1:nr_observations), hidden_location, label = \"hidden location\", legend=:topleft, linewidth=3, color = :red)\nplot!(map(mean, results.posteriors[:z]), label = \"estimated location (±2σ)\", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot Bethe free energy\np2 = plot(results.free_energy, linewidth=3, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size = (1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Requirements","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Requirements","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"There are several main requirements for the CVI procedure to satisfy:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The out interface of the non-linearity must be independently factorized with respect to other variables in the model.\nThe messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function model(...)\n ...\n y ~ f(x1, x2, ..., xN)\n ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity\n ... \nend\n\n@constraints function constraints_meta() begin\n q(y, z1, ..., zn) = q(y)q(z1,...,zM)\n ...\nend;\n\n@meta function model_meta(...)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer))\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note that not all exponential family distributions are implemented.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Extensions","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Extensions","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Using-a-custom-optimizer","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Using a custom optimizer","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"CVI only supports Optimisers optimizers out of the box.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Below an explanation on how to extend to it to a custom optimizer.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Suppose we have CustomDescent structure which we want to use inside CVI for optimization.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"ReactiveMP.cvi_update! incapsulates the gradient step:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"opt is used to select your optimizer structure\nλ is the current value\n∇ is a gradient value computed inside CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"struct CustomDescent \n learning_rate::Float64\nend\n\n# Must return an optimizer and its initial state\nfunction ReactiveMP.cvi_setup(opt::CustomDescent, q)\n return (opt, nothing)\nend\n\n# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)\nfunction ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)\n opt, _ = opt_and_state\n λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))\n copyto!(new_λ, λ̂)\n return opt_and_state, new_λ\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's try to apply it to a model: beginaligned p(x) = mathcalN(0 1)\n p(y_imid x) = mathcalN(y_i mid x^2 1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's generate some synthetic data for the model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# generate data\ny = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)\nhistogram(y)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Again we can create the corresponding model as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# specify non-linearity\nf(x) = x ^ 2\n\n# specify model\n@model function normal_square_model(nr_observations)\n\n # allocate observations\n y = datavar(Float64, nr_observations)\n\n # describe prior on latent state\n x ~ NormalMeanPrecision(0, 100)\n\n # transform latent state\n mean ~ f(x)\n\n # observation model\n y .~ NormalMeanVariance(mean, 1)\n\nend\n\n# specify meta\n@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"normal_square_meta (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"res = infer(\n model = normal_square_model(1000),\n data = (y = y,),\n iterations = 10,\n free_energy = true,\n initmessages = (x = NormalMeanVariance(0, 100),),\n meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))\n)\n\nmean(res.posteriors[:x][end])","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"-18.998075156688632","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working! ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note: x^2 can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"page"},{"location":"library/functional-forms/#lib-forms","page":"Built-in functional form constraints","title":"Built-in Functional Forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.","category":"page"},{"location":"library/functional-forms/#lib-forms-custom-constraints","page":"Built-in functional form constraints","title":"Custom functional forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.","category":"page"},{"location":"library/functional-forms/#lib-forms-unspecified-constraint","page":"Built-in functional form constraints","title":"UnspecifiedFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: Nothing # This is the default setting\nend","category":"page"},{"location":"library/functional-forms/#lib-forms-point-mass-constraint","page":"Built-in functional form constraints","title":"PointMassFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. ","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.PointMassFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.PointMassFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.PointMassFormConstraint","text":"PointMassFormConstraint\n\nOne of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.\n\nKeyword arguments\n\noptimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer\nstarting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point\nboundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries\n\nCustom optimizer callback interface\n\n# This is an example of the `custom_optimizer` interface\nfunction custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # should return argmin of the -logpdf(distribution)\nend\n\nCustom starting point callback interface\n\n# This is an example of the `custom_starting_point` interface\nfunction custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # built-in optimizer expects an array, even for a univariate distribution\n return [ 0.0 ] \nend\n\nCustom boundaries callback interface\n\n# This is an example of the `custom_boundaries` interface\nfunction custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # returns a tuple of `lower` and `upper` boundaries\n return (-Inf, Inf)\nend\n\nTraits\n\nis_point_mass_form_constraint = true\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = PointMass (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-sample-list-constraint","page":"Built-in functional form constraints","title":"SampleListFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000)\n # or \n q(y) :: SampleList(1000, LeftProposal())\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.SampleListFormConstraint\nRxInfer.AutoProposal\nRxInfer.LeftProposal\nRxInfer.RightProposal","category":"page"},{"location":"library/functional-forms/#RxInfer.SampleListFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.SampleListFormConstraint","text":"SampleListFormConstraint(rng, strategy, method)\n\nOne of the form constraint objects. Approximates DistProduct with a SampleList object. \n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = SampleList (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.AutoProposal","page":"Built-in functional form constraints","title":"RxInfer.AutoProposal","text":"Tries to determine the proposal distribution in the SampleList approximation automatically.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.LeftProposal","page":"Built-in functional form constraints","title":"RxInfer.LeftProposal","text":"Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.RightProposal","page":"Built-in functional form constraints","title":"RxInfer.RightProposal","text":"Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-fixed-marginal-constraint","page":"Built-in functional form constraints","title":"FixedMarginalFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints function block_updates(x_posterior = nothing) \n # `nothing` returns the computed posterior marginal\n q(x) :: Marginal(x_posterior)\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.FixedMarginalFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.FixedMarginalFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.FixedMarginalFormConstraint","text":"FixedMarginalFormConstraint\n\nOne of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.\n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = Marginal (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-composite-constraint","page":"Built-in functional form constraints","title":"CompositeFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass()\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/#examples-hierarchical-gaussian-filter","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"","category":"section"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Simple HGF model can be defined as:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n x^(j)_k sim mathcalN(x^(j)_k - 1 f_k(x^(j - 1)_k)) \n y_k sim mathcalN(x^(j)_k tau_k)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"where j is an index of layer in hierarchy, k is a time step and f_k is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with f_k = exp(kappa x + omega) variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n z_k sim mathcalN(z_k - 1 mathcaltau_z) \n x_k sim mathcalN(x_k - 1 exp(kappa z_k + omega)) \n y_k sim mathcalN(x_k mathcaltau_y)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"For simplicity we will consider tau_z, tau_y, kappa and omega known and fixed, but there are no principled limitations to make them random variables too.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"using RxInfer, BenchmarkTools, Random, Plots","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function generate_data(rng, k, w, zv, yv)\n z_prev = 0.0\n x_prev = 0.0\n\n z = Vector{Float64}(undef, n)\n v = Vector{Float64}(undef, n)\n x = Vector{Float64}(undef, n)\n y = Vector{Float64}(undef, n)\n\n for i in 1:n\n z[i] = rand(rng, Normal(z_prev, sqrt(zv)))\n v[i] = exp(k * z[i] + w)\n x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))\n y[i] = rand(rng, Normal(x[i], sqrt(yv)))\n\n z_prev = z[i]\n x_prev = x[i]\n end \n \n return z, x, y\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Seed for reproducibility\nseed = 42\n\nrng = MersenneTwister(seed)\n\n# Parameters of HGF process\nreal_k = 1.0\nreal_w = 0.0\nz_variance = abs2(0.2)\ny_variance = abs2(0.1)\n\n# Number of observations\nn = 300\n\nz, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n scatter!(px, 1:n, y, label = \"y_i\", color = :red, ms = 2, alpha = 0.2)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To create a model we use the @model macro:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# We create a single-time step of corresponding state-space process to\n# perform online learning (filtering)\n@model function hgf(real_k, real_w, z_variance, y_variance)\n \n # Priors from previous time step for `z`\n zt_min_mean = datavar(Float64)\n zt_min_var = datavar(Float64)\n \n # Priors from previous time step for `x`\n xt_min_mean = datavar(Float64)\n xt_min_var = datavar(Float64)\n\n zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)\n xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)\n\n # Higher layer is modelled as a random walk \n zt ~ NormalMeanVariance(zt_min, z_variance)\n \n # Lower layer is modelled with `GCV` node\n gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)\n \n # Noisy observations \n y = datavar(Float64)\n y ~ NormalMeanVariance(xt, y_variance)\n \n return gcvnode\nend\n\n@constraints function hgfconstraints() \n q(xt, zt, xt_min) = q(xt, xt_min)q(zt)\nend\n\n@meta function hgfmeta()\n # Lets use 31 approximation points in the Gauss Hermite cubature approximation method\n GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) \nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"hgfmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function run_inference(data, real_k, real_w, z_variance, y_variance)\n\n autoupdates = @autoupdates begin\n zt_min_mean, zt_min_var = mean_var(q(zt))\n xt_min_mean, xt_min_var = mean_var(q(xt))\n end\n\n return infer(\n model = hgf(real_k, real_w, z_variance, y_variance),\n constraints = hgfconstraints(),\n meta = hgfmeta(),\n data = (y = data, ),\n autoupdates = autoupdates,\n keephistory = length(data),\n historyvars = (\n xt = KeepLast(),\n zt = KeepLast()\n ),\n initmarginals = (\n zt = NormalMeanVariance(0.0, 5.0),\n xt = NormalMeanVariance(0.0, 5.0),\n ), \n iterations = 5,\n free_energy = true,\n autostart = true,\n callbacks = (\n after_model_creation = (model, returnval) -> begin \n gcvnode = returnval\n setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))\n end,\n )\n )\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"run_inference (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"result = run_inference(y, real_k, real_w, z_variance, y_variance);\n\nmz = result.history[:zt];\nmx = result.history[:xt];","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = \"estimated z_i\", color = :teal)\n \n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = \"estimated x_i\", color = :violet)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"plot(result.free_energy_history, label = \"Bethe Free Energy\")","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see BetheFreeEnergy converges nicely to a stable point.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"At final, lets check the overall performance of our resulting Variational Message Passing algorithm:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"BenchmarkTools.Trial: 37 samples with 1 evaluation.\n Range (min … max): 116.366 ms … 196.439 ms ┊ GC (min … max): 0.00% … 0.0\n0%\n Time (median): 134.625 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 137.513 ms ± 14.948 ms ┊ GC (mean ± σ): 1.41% ± 2.7\n1%\n\n ▁ █▁▆▁ \n ▄▁▄▁▁▄▁▁▇▇█▄▇████▄▁▁▁▄▄▁▄▁▁▁▁▁▁▁▄▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▄▁▁▁▁▁▁▁▄ ▁\n 116 ms Histogram: frequency by time 196 ms <\n\n Memory estimate: 18.78 MiB, allocs estimate: 456888.","category":"page"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = RxInfer","category":"page"},{"location":"#RxInfer","page":"Home","title":"RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"Julia package for automatic Bayesian inference on a factor graph with reactive message passing.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.","category":"page"},{"location":"#Package-Features","page":"Home","title":"Package Features","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"User friendly syntax for specification of probabilistic models.\nAutomatic generation of message passing algorithms including\nBelief propagation\nVariational message passing\nExpectation maximization\nSupport for hybrid models combining discrete and continuous latent variables.\nSupport for hybrid distinct message passing inference algorithm under a unified paradigm.\nFactorisation and functional form constraints specification.\nEvaluation of Bethe free energy as a model performance measure.\nSchedule-free reactive message passing API.\nHigh performance.\nScalability for large models with millions of parameters and observations.\nInference procedure is differentiable.\nEasy to extend with custom nodes and message update rules.","category":"page"},{"location":"#Why-RxInfer","page":"Home","title":"Why RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a \"variational Free Energy\" cost function. For large models, manual derivation of these gradients might not be feasible, while automated \"black-box\" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.","category":"page"},{"location":"","page":"Home","title":"Home","text":"RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different \"what-if\" scenarios and enables very efficient inference in specific cases.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.","category":"page"},{"location":"#How-to-get-started?","page":"Home","title":"How to get started?","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"manuals/background.md\",\n \"manuals/comparison.md\",\n \"manuals/getting-started.md\",\n \"manuals/model-specification.md\",\n \"manuals/constraints-specification.md\",\n \"manuals/meta-specification.md\",\n \"manuals/inference-execution.md\",\n \"manuals/custom-node.md\",\n \"manuals/debugging.md\",\n \"manuals/delta-node.md\",\n \"examples/overview.md\",\n \"library/exported-methods.md\",\n \"library/functional-forms.md\",\n \"contributing/overview.md\",\n \"contributing/new-example.md\"\n]\nDepth = 2","category":"page"},{"location":"#References","page":"Home","title":"References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RxInfer: A Julia package for reactive real-time Bayesian inference - a reference paper for the RxInfer.jl framwork.\nVariational Message Passing and Local Constraint Manipulation in Factor Graphs - describes theoretical aspects of the underlying Bayesian inference method.\nReactive Message Passing for Scalable Bayesian Inference - describes implementation aspects of the Bayesian inference engine and performs benchmarks and accuracy comparison on various models.\nA Julia package for reactive variational Bayesian inference - a reference paper for the ReactiveMP.jl package, the underlying inference engine.\nThe Factor Graph Approach to Model-Based Signal Processing - an introduction to message passing and FFGs.","category":"page"},{"location":"#Ecosystem","page":"Home","title":"Ecosystem","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ReactiveMP.jl - core package for efficient and scalable for reactive message passing \nGraphPPL.jl - package for model and constraints specification\nRocket.jl - reactive programming tools","category":"page"},{"location":"#Index","page":"Home","title":"Index","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"manuals/inference/infer/#user-guide-inference","page":"Static vs Streamline inference","title":"Automatic Inference Specification","text":"","category":"section"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors. ","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"For details on manual inference specification, see the Manual Inference section.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"infer\nInferenceResult\nRxInfer.start\nRxInfer.stop\n@autoupdates\nRxInferenceEngine\nRxInferenceEvent","category":"page"},{"location":"manuals/inference/infer/#RxInfer.infer","page":"Static vs Streamline inference","title":"RxInfer.infer","text":"infer(\n model; \n data = nothing,\n datastream = nothing,\n autoupdates = nothing,\n initmarginals = nothing,\n initmessages = nothing,\n constraints = nothing,\n meta = nothing,\n options = nothing,\n returnvars = nothing, \n predictvars = nothing, \n historyvars = nothing,\n keephistory = nothing,\n iterations = nothing,\n free_energy = false,\n free_energy_diagnostics = BetheFreeEnergyDefaultChecks,\n showprogress = false,\n callbacks = nothing,\n addons = nothing,\n postprocess = DefaultPostprocess(),\n warn = true,\n events = nothing,\n uselock = false,\n autostart = true,\n catch_exception = false\n)\n\nThis function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.\n\nArguments\n\nFor more information about some of the arguments, please check below. \n\nmodel: specifies a model generator, required\ndata: NamedTuple or Dict with data, required (or datastream or predictvars)\ndatastream: A stream of NamedTuple with data, required (or data)\nautoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates\ninitmarginals = nothing: NamedTuple or Dict with initial marginals, optional\ninitmessages = nothing: NamedTuple or Dict with initial messages, optional\nconstraints = nothing: constraints specification object, optional, see @constraints\nmeta = nothing: meta specification object, optional, may be required for some models, see @meta\noptions = nothing: model creation options, optional, see ModelInferenceOptions\nreturnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information\npredictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)\nhistoryvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)\nkeephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)\niterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information\nfree_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl\nfree_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.\nshowprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)\ncatch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)\ncallbacks = nothing: inference cycle callbacks, optional, see below for more info\naddons = nothing: inject and send extra computation information along messages, see below for more info\npostprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info\nevents = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)\nuselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)\nautostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)\nwarn = true: enables/disables warnings\n\nNote on NamedTuples\n\nWhen passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.\n\nThe model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:\n\n@model function coin_toss(some_argument, some_keyword_argument = 3)\n ...\nend\n\nresult = infer(\n model = coin_toss(some_argument; some_keyword_argument = 3)\n)\n\nNote: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.\n\ndata\n\nEither data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.\n\nNote: The behavior of the data keyword argument depends on the inference setting (batch or streamline).\n\nThe data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.\n\nstreamline setting\n\nAll entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.\n\ndatastream\n\nThe datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.\n\nNote: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.\n\nFor specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as\n\ninfer(...\n initmarginals = (\n # initialize the marginal distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.\n\n- ### `initmessages`\n\nFor specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as\n\njulia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )\n\noptions\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\nreturnvars\n\nreturnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.\n\nBatch inference:\n\nAccepts a NamedTuple or Dict of return variable specifications.\nTwo specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).\nWhen iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).\nUse iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.\n\nExample:\n\nresult = infer(\n ...,\n returnvars = (\n x = KeepLast(),\n τ = KeepEach()\n )\n)\n\nShortcut for setting the same option for all variables:\n\nresult = infer(\n ...,\n returnvars = KeepLast() # or KeepEach()\n)\n\nStreamline inference:\n\nFor each symbol in returnvars, infer creates an observable stream of posterior updates.\nAgents can subscribe to these updates using the Rocket.jl package.\n\nExample:\n\nengine = infer(\n ...,\n autoupdates = my_autoupdates,\n returnvars = (:x, :τ),\n autostart = false\n)\n\npredictvars\n\npredictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.\n\nSimilar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n predictvars = (\n o = KeepLast(),\n τ = KeepEach()\n )\n)\n\nNote: The predictvars argument is exclusive for batch setting.\n\nhistoryvars\n\nhistoryvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.\n\nhistoryvars accepts a NamedTuple or Dict or return var specification. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = (\n x = KeepLast(),\n τ = KeepEach()\n ),\n keephistory = 10\n)\n\nIt is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.\n\nExample:\n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = KeepLast(),\n keephistory = 10\n)\n\nkeep_history\n\nSpecifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.\n\niterations\n\nSpecifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration. \n\nfree_energy\n\nStreamline inference:\n\nSpecifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.\n\nWhen free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.\nengine.free_energy_history: Averaged BFE history over VMP iterations.\nengine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.\nengine.free_energy_raw_history: Raw BFE history.\n\nBatch inference:\n\nSpecifies if the infer function should return Bethe Free Energy (BFE) values.\n\nOptionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.\nfree_energy_diagnostics\n\nThis settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.\n\ncatch_exception\n\nThe catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.\n\ncallbacks\n\nThe inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.\n\nresult = infer(\n ...,\n callbacks = (\n on_marginal_update = (model, name, update) -> println(\"$(name) has been updated: $(update)\"),\n after_inference = (args...) -> println(\"Inference has been completed\")\n )\n)\n\nThe callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:\n\non_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)\nbefore_model_creation: args: ()\nafter_model_creation: args: (model::FactorGraphModel, returnval)\nbefore_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nbefore_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nafter_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\nafter_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\n\nbefore_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.\n\naddons\n\nThe addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.\n\npostprocess\n\nThe postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.InferenceResult","page":"Static vs Streamline inference","title":"RxInfer.InferenceResult","text":"InferenceResult\n\nThis structure is used as a return value from the infer function. \n\nPublic Fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.\nfree_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\nerror: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.start","page":"Static vs Streamline inference","title":"RxInfer.start","text":"start(engine::RxInferenceEngine)\n\nStarts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.stop\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.stop","page":"Static vs Streamline inference","title":"RxInfer.stop","text":"stop(engine::RxInferenceEngine)\n\nStops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.start\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.@autoupdates","page":"Static vs Streamline inference","title":"RxInfer.@autoupdates","text":"@autoupdates\n\nCreates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification. \n\nEach line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.\n\nFor example:\n\n@autoupdates begin \n x = f(q(z))\nend\n\nThis structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically. \n\nAs an example consider the following model and auto-update specification:\n\n@model function kalman_filter()\n x_current_mean = datavar(Float64)\n x_current_var = datavar(Float64)\n\n x_current ~ Normal(mean = x_current_mean, var = x_current_var)\n\n x_next ~ Normal(mean = x_current, var = 1.0)\n\n y = datavar(Float64)\n y ~ Normal(mean = x_next, var = 1.0)\nend\n\nThis model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:\n\nautoupdates = @autoupdates begin\n x_current_mean, x_current_var = mean_cov(q(x_next))\nend\n\nThis structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.\n\nSee also: infer\n\n\n\n\n\n","category":"macro"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEngine","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEngine","text":"RxInferenceEngine\n\nThe return value of the rxinference function. \n\nPublic fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.\nfree_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.\nhistory: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.\nfree_energy_history: (optional) Free energy history, average over variational iterations \nfree_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)\nfree_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)\nevents: (optional) A stream of events send by the inference engine. See the events argument for the infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\n\nUse the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.\n\nSee also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEvent","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEvent","text":"RxInferenceEvent{T, D}\n\nThe RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.\n\nThe events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:\n\nusing Rocket\n\nstruct MyEventListener <: Rocket.Actor{RxInferenceEvent}\n # ... extra fields\nend\n\nfunction Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })\n model, iteration = event\n println(\"Iteration $(iteration) has been finished.\")\nend\n\nfunction Rocket.on_error!(listener::MyEventListener, err)\n # ...\nend\n\nfunction Rocket.on_complete!(listener::MyEventListener)\n # ...\nend\n\n\nand later on:\n\nengine = infer(events = Val((:after_iteration, )), ...)\n\nsubscription = subscribe!(engine.events, MyEventListener(...))\n\nSee also: infer, RxInferenceEngine\n\n\n\n\n\n","category":"type"},{"location":"examples/advanced_examples/overview/#examples-advanced_examples-overview","page":"Overview","title":"Advanced examples","text":"","category":"section"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Advanced examples contain more complex inference problems.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.\nAdvanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.\nAssessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.\nChance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.\nConjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.\nGlobal Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.\nSolve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.\nInfinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.\nNonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors","category":"page"},{"location":"manuals/constraints-specification/#user-guide-constraints-specification","page":"Constraints specification","title":"Constraints Specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"using RxInfer","category":"page"},{"location":"manuals/constraints-specification/#General-syntax","page":"Constraints specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"\n# `functional` style\n@constraints function create_my_constraints(arg1, arg2)\n ...\nend\n\n# `block` style\nmyconstraints = @constraints begin \n ...\nend\n","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In the first case it returns a function that return constraints upon calling, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(mean_field)\n q(x) :: PointMass\n\n if mean_field\n q(x, y) = q(x)q(y)\n end\nend\n\nmyconstraints = make_constraints(true)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"and in the second case it evaluates automatically and returns constraints object directly.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints begin \n q(x) :: PointMass\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/#Options-specification","page":"Constraints specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints [ warn = false ] begin \n ...\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"List of available options:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/constraints specification","category":"page"},{"location":"manuals/constraints-specification/#Marginal-and-messages-form-constraints","page":"Constraints specification","title":"Marginal and messages form constraints","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"The following constraint:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"mathrmapproximate q(x) = fracoverrightarrowmu(x)overleftarrowmu(x)int overrightarrowmu(x)overleftarrowmu(x) mathrmdxmathrmasPointMass","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\n μ(x) :: SampleList(1000)\n # it is possible to assign different form constraints on the same variable \n # both for the marginal and for the messages \nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro understands \"stacked\" form constraints. For example the following form constraint","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\nNot all combinations of \"stacked\" form constraints are compatible between each other.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.","category":"page"},{"location":"manuals/constraints-specification/#Factorisation-constraints-on-posterior-distribution-q()","page":"Constraints specification","title":"Factorisation constraints on posterior distribution q()","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"For example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) = q(x[begin])..q(x[end])\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables x_i.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\n@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"It is possible to write more complex factorisation constraints, for example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(k)\n q(x) = q(x[begin:k])q(x[k+1:end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end]. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model function my_model(arguments...)\n ...\nend\n\nconstraints = @constraints begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); constraints = constraints)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument. ","category":"page"},{"location":"contributing/overview/#contributing-overview","page":"Overview","title":"Contributing","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.","category":"page"},{"location":"contributing/overview/#Reporting-bugs","page":"Overview","title":"Reporting bugs","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.","category":"page"},{"location":"contributing/overview/#Nightly-Julia-status","page":"Overview","title":"Nightly Julia status","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"(Image: PkgEval)","category":"page"},{"location":"contributing/overview/#Suggesting-features","page":"Overview","title":"Suggesting features","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome new feature proposals. However, before submitting a feature request, consider a few things:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.\nIf you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.","category":"page"},{"location":"contributing/overview/#Contributing-code","page":"Overview","title":"Contributing code","text":"","category":"section"},{"location":"contributing/overview/#Installing-RxInfer","page":"Overview","title":"Installing RxInfer","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] dev git@github.com:your_username/RxInfer.jl.git","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nIt is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.","category":"page"},{"location":"contributing/overview/#Core-dependencies","page":"Overview","title":"Core dependencies","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.","category":"page"},{"location":"contributing/overview/#Committing-code","page":"Overview","title":"Committing code","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well. ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.","category":"page"},{"location":"contributing/overview/#Style-conventions","page":"Overview","title":"Style conventions","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Use 4 spaces for indentation\nType names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..\nFunction names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..\nVariable names and function arguments use snake_case\nThe name of a method that modifies its argument(s) must end in !","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nRxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.","category":"page"},{"location":"contributing/overview/#Unit-tests","page":"Overview","title":"Unit tests","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The tests can be evaluated by running following command in the Julia REPL:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] test RxInfer","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"In addition tests can be evaluated by running following command in the RxInfer root directory:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make test","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make devtest to use local dev-ed versions of the core packages.","category":"page"},{"location":"contributing/overview/#Makefile","page":"Overview","title":"Makefile","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl uses Makefile for most common operations:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make help: Shows help snippet\nmake test: Run tests, supports extra arguments\nmake test test_args=\"distributions:normal_mean_variance\" would run tests only from distributions/test_normal_mean_variance.jl\nmake test test_args=\"distributions:normal_mean_variance models:lgssm\" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl\nmake test dev=true would run tests while using dev-ed versions of core packages\nmake devtest: Alias for the make test dev=true ...\nmake docs: Compile documentation\nmake devdocs: Same as make docs, but uses dev-ed versions of core packages\nmake examples: Run all examples and put them in the docs/ folder if successfull \nmake devexamples: Same as make examples, but uses dev-ed versions of core packages\nmake lint: Check codestyle\nmake format: Check and fix codestyle ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nCore packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.","category":"page"},{"location":"contributing/new-release/#contributing-new-release","page":"Publishing a new release","title":"Publishing a new release","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.","category":"page"},{"location":"contributing/new-release/#Start-the-release-process","page":"Publishing a new release","title":"Start the release process","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"In order to start the release process a person with the associated permissions should: ","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Open a commit page on GitHub\nWrite the @JuliaRegistrator register comment for the commit:","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"(Image: Release comment)","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#examples-solve-gp-regression-by-sde","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"In this notebook, we solve a GP regression problem by using \"Stochastic Differential Equation\" (SDE). This method is well described in the dissertation \"Stochastic differential equation methods for spatio-temporal Gaussian process regression.\" by Arno Solin and \"Sequential Inference for Latent Temporal Gaussian Process Models\" by Jouni Hartikainen. The idea of the method is as follows.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Suppose a function f(x) follows a zero-mean Gaussian Process beginaligned f(x) sim mathcalGP(0 k(xx)) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"When the dimensionality of x is 1, we can consider f(x) as a stochastic process over time, i.e. f(t). For a certain classses of covariance functions, f(t) is a solution to an m-th order linear stochastic differential equation (SDE) beginaligned a_0 f(t) + a_1 fracd f(t)dt + dots + a_m fracd^m f(t)dt^m = w(t) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where w(t) is a zero-mean white noise process with spectral density Q_c. If we define a vector-valued function mathbff(t) = (f(t) ddt f(t)dots d^m-1dt^m-1f(t)), then we can rewrite the above SDE under the companion form","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracd mathbff(t)dt = mathbfF mathbff(t) + mathbfL w(t) quad (1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfF and mathbfL are defined based on the choice of covariance functions. From (1), we have the following state-space model: beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) quad(2a) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) quad(2b) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfA_k = exp(mathbfFDelta t_k), with Delta t_k = t_k+1 - t_k, is called the discrete-time state transition matrix, and mathbfQ_k the process noise covariance matrix. For the computation of mathbfQ_k, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state f_0 sim mathcalN(mathbf0 mathbfP_0). For stationary covariance function, the SDE has a stationary state f_infty sim mathcalN(mathbf0 mathbfP_infty), where mathbfP_infty is the solution to beginaligned fracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0 quad (mathrmLyapunov equation) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"With this stationary condition, the process noise covariance mathbfQ_k is computed as follows beginaligned mathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"For one-dimensional problem the SDE representation of the GP is defined by the matrices mathbfF mathbfL mathbfQ_c mathbfP_0 and mathbfH. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"using RxInfer, Random, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Create-state-space-model-for-GP-regression","page":"Solve GP regression by SDE","title":"Create state space model for GP regression","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Here we create a state-space model beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) \nendaligned where y_k is the noisy observation of the function f at time t_k, and sigma^2_noise is the noise variance and assumed to be known.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"@model function gp_regression(n, P∞, A, Q, H, σ²_noise)\n f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)\n f = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n \n f_prev = f_0\n\n for i=1:n\n f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])\n y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)\n f_prev = f[i]\n end\n return f, y\nend","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Generate-data","page":"Solve GP regression by SDE","title":"Generate data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Random.seed!(10)\nn = 100\nσ²_noise = 0.04;\nt = collect(range(-2, 2, length=n)); #timeline\nf_true = sinc.(t); # true process\nf_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process\n\npos = sort(randperm(75)[1:2:75]); \nt_obser = t[pos]; # time where we observe data\n\ny_data = Array{Union{Float64,Missing}}(missing, n)\nfor i in pos \n y_data[i] = f_noisy[i]\nend\n\nθ = [1., 1.]; # store [l, σ²]\nΔt = [t[1]]; # time difference\nappend!(Δt, t[2:end] - t[1:end-1]);","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Let's-visualize-our-data","page":"Solve GP regression by SDE","title":"Let's visualize our data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"plot(t, f_true, label=\"True process f(t)\")\nscatter!(t_obser, y_data[pos], label = \"Noisy observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-3/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-3/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"The Matern is a stationary covariance function and defined as follows beginaligned k(tau) = sigma^2 frac2^1-nuGamma(nu) left(fracsqrt2nutaul right)^nu K_nuleft(fracsqrt2nutaul right) endaligned where beginaligned sigma^2 textthe magnitude scale hyperparameter\nl textthe characteristic length-scale\nnu textthe smoothness hyperparameter\nK_nu() textthe modified Bessel function of the second kind endaligned When we say the Matern-3/2, we mean nu=32. The matrices for the state space model are computed as follows beginaligned mathbfF = beginpmatrix 0 1\n-lambda^2 -2lambda endpmatrix quad quad mathbfL = beginpmatrix 0 1 endpmatrix quad quad mathbfP_infty = beginpmatrix sigma^2 0 0 lambda^2sigma^2 endpmatrix quad quad mathbfH = beginpmatrix 1 0 endpmatrix quad quad Q_c = 4lambda^3sigma^2 endaligned where lambda = fracsqrt3l From these matrices we can define mathbfA_k and mathbfQ_k.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(3)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 1.];\nH = [1., 0.];\nF = [0. 1.; -λ^2 -2λ]\nP∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_32 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-5/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-5/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfF = beginpmatrix\n0 1 0\n0 0 1 \n-lambda^3 -3lambda^2 -3lambda\nendpmatrix quad quad mathbfL = beginpmatrix\n0 0 1\nendpmatrix quad quad mathbfH = beginpmatrix\n1 0 0\nendpmatrix quad quad Q_c = frac163 sigma^2 lambda^5 \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where lambda = sqrt5 l. To find mathbfP_infty, we solve the Lyapunov equation","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"of which the solution is","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nvec(mathbfP_infty) = (mathbfI otimes mathbfF + mathbfFotimesmathbfI)^-1 vec(-mathbfLQ_cmathbfL^T)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where vec() is the vectorization operator and otimes denotes the Kronecker product. Now we can find mathbfA_k and mathbfQ_k ","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfA_k = exp(mathbfFDelta t_k) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(5)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 0., 1.];\nH = [1., 0., 0.];\nF = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]\nQc = 16/3 * θ[2] * λ^5;\n\nI = diageye(3) ; \nvec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); \nP∞ = reshape(vec_P,3,3);\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_52 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Result","page":"Solve GP regression by SDE","title":"Result","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"slicedim(dim) = (a) -> map(e -> e[dim], a)\n\nplot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M32\", title = \"Matern-3/2\", legend =false, lw = 2)\nplot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M52\",legend = :bottomleft, title = \"GPRegression by SSM\", lw = 2)\nplot!(t, f_true,label=\"true process\", lw = 2)\nscatter!(t_obser, f_noisy[pos], label=\"Observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"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. ","category":"page"},{"location":"contributing/new-documentation/#guide-docs-contributing","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.\nIdentify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.\nFork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.\nMake Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.\nSubmit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.\nReview and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.\nMerging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.","category":"page"},{"location":"contributing/new-documentation/#Use-[LiveServer.jl](https://github.com/tlienart/LiveServer.jl)","page":"Contributing to the documentation","title":"Use LiveServer.jl","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"To use LiveServer.jl, simply follow these steps[1]","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"[1]: Make sure to install the LiveServer and Documenter in your current working environment.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Make sure to import the required packages ","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> using LiveServer, Documenter","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"After importing the required packages, you can start the live server with the following command:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> servedocs()","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#examples-bayesian-linear-regression-tutorial","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The first part uses a regular Bayesian Linear Regression on a simple application of fuel consumption for a car with synthetic data.\nThe second part is an adaptation of a tutorial from NumPyro and uses Hierarchical Bayesian linear regression on the OSIC pulmonary fibrosis progression dataset from Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-1.-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 1. Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-known-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He records the speed and fuel consumption for the urban road which is the xdata and ydata.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b)\n Free Energy: | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184\n.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821\n, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a\\mid y)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0,Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b)\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b\\mid y)\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"a = results.posteriors[:a]\nb = results.posteriors[:b]\n\nprintln(\"Real a: \", 0.5, \" | Estimated a: \", mean_var(a), \" | Error: \", abs(mean(a) - 0.5))\nprintln(\"Real b: \", 25.0, \" | Estimated b: \", mean_var(b), \" | Error: \", abs(mean(b) - 25.0))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err\nor: 0.001490188462705988\nReal b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error\n: 0.18735789804394898","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-unknown-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with unknown noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. beginaligned p(y_n mid a b s) = mathcalN(y_n mid ax_n + b s)\np(s) = mathcalIG(smidalpha theta)\np(a) = mathcalN(a mid m_a v_a) \np(b) = mathcalN(b mid m_b v_b) endaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_unknown_noise(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n s ~ InverseGamma(1.0, 1.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = s)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)\n\nscatter(x_data_un, y_data_un, title = \"Dateset with unknown noise (mountain road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_unknown_noise = infer(\n model = linear_regression_unknown_noise(length(x_data_un)), \n data = (y = y_data_un, x = x_data_un), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast(), s = KeepLast()), \n iterations = 20,\n constraints = MeanField(),\n initmarginals = (s = vague(InverseGamma), ),\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, s)\n Free Energy: | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125\n.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56\n, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"plot(results_unknown_noise.free_energy, title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Below he visualizes the obtained posterior distributions for parameters:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(a)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(b)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25.0 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(b)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25.0 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L\"Prior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(s)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 200 ], label=L\"True $s$\", c = 3)\npsb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L\"Posterior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(s)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 200 ], label=L\"True $s$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$s$\", ylabel=L\"$p(s)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He sees that in the presence of more noise the inference result is more uncertain about the actual values for a and b parameters.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John samples a and b and plot many possible regression lines on the same plot:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"as = rand(results_unknown_noise.posteriors[:a], 100)\nbs = rand(results_unknown_noise.posteriors[:b], 100)\np = scatter(x_data_un, y_data_un, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)\nend\n\nplot(p, size = (900, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"From this plot John can see that many lines do fit the data well and there is no definite \"best\" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Multivariate-linear-regression","page":"Bayesian Linear Regression Tutorial","title":"Multivariate linear regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_multivariate(dim, nr_samples)\n a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))\n b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))\n W ~ InverseWishart(dim + 2, 100 * diageye(dim))\n\n # Here is a small trick to make the example work\n # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`\n x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n z = randomvar(nr_samples)\n\n z .~ x .* a .+ b\n y .~ MvNormal(mean = z, covariance = W)\n\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"After received all the measurement records, he plots the measurements and performance index:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dim_mv = 6\nnr_samples_mv = 50\nrng_mv = StableRNG(42)\na_mv = randn(rng_mv, dim_mv)\nb_mv = 10 * randn(rng_mv, dim_mv)\nv_mv = 100 * rand(rng_mv, dim_mv)\n\nx_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft)\n\nplt = palette(:tab10)\n\ndata_set_label = [\"\"]\n\nfor k in 1:dim_mv\n global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\nxlabel!(L\"$x$\")\nylabel!(L\"$y$\")\np","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Before this data can be used to perform inference, John needs to change its format slightly.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)\ny_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_mv = infer(\n model = linear_regression_multivariate(dim_mv, nr_samples_mv),\n data = (y = y_data_mv_processed, x = x_data_mv_processed),\n initmarginals = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),\n initmessages = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),\n returnvars = (a = KeepLast(), b = KeepLast(), W = KeepLast()),\n free_energy = true,\n iterations = 50,\n constraints = MeanField()\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, W)\n Free Energy: | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7\n22, 712.341, 700.865, 690.782, 682.505 … 664.434, 664.434, 664.434, 664.4\n34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft, xlabel=L\"$x$\", ylabel=L\"$y$\")\n\n# how many lines to plot\nr = 50\n\ni_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))\ni_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))\n\nplt = palette(:tab10)\n\nfor k in 1:dim_mv\n x_mv_k = x_data_mv[k]\n y_mv_k = y_data_mv[k]\n\n for i in 1:r\n global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])\n end\n\n global p = scatter!(p, x_mv_k, y_mv_k, label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\n\n# truncate the init step\nf = plot(results_mv.free_energy[2:end], title =\"Bethe free energy convergence\", label = nothing, xlabel = \"Iteration\", ylabel = \"Bethe free energy [nats]\") \n\nplot(p, f, size = (1000, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_a_mv = results_mv.posteriors[:a]\n\nps_a = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $a_{%$k}$\", xlabel=L\"$a_{%$k}$\", ylabel=L\"$p(a_{%$k})$\", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])\n\n local m_a_mv_k = mean(i_a_mv)[k]\n local v_a_mv_k = std(i_a_mv)[k, k]\n \n _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(a_{%$k})$\", c=2,)\n _p = vline!(_p, [ a_mv[k] ], label=L\"True $a_{%$k}$\", c = 3)\n \n push!(ps_a, _p)\nend\n\nplot(ps_a...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_b_mv = results_mv.posteriors[:b]\n\nps_b = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $b_{%$k}$\", xlabel=L\"$b_{%$k}$\", ylabel=L\"$p(b_{%$k})$\", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])\n local m_b_mv_k = mean(i_b_mv)[k]\n local v_b_mv_k = std(i_b_mv)[k, k]\n\n _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(b_{%$k})$\", c=2,)\n _p = vline!(_p, [ b_mv[k] ], label=L\"Real $b_{%$k}$\", c = 3)\n \n push!(ps_b, _p)\nend\n\nplot(ps_b...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L\"True $s_d$\")\nscatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L\"$\\mathrm{E}[s_d] \\pm \\sigma$\")\nplot!(; xlabel=L\"Dimension $d$\", ylabel=\"Variance\", title=\"Estimated variance of the noise\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-2.-Hierarchical-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 2. Hierarchical Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# https://www.machinelearningplus.com/linear-regression-in-julia/\n# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Understanding-the-Task","page":"Bayesian Linear Regression Tutorial","title":"Understanding the Task","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's explore the data and delve deeper into the problem involved.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dataset = CSV.read(\"../data/hbr/osic_pulmonary_fibrosis.csv\", DataFrame);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"describe(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"7×7 DataFrame\n Row │ variable mean min median max \n ⋯\n │ Symbol Union… Any Union… Any \n ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ Patient ID00007637202177411956430 ID004266\n372 ⋯\n 2 │ Weeks 31.8618 -5 28.0 133\n 3 │ FVC 2690.48 827 2641.0 6399\n 4 │ Percent 77.6727 28.8776 75.6769 153.145\n 5 │ Age 67.1885 49 68.0 88 \n ⋯\n 6 │ Sex Female Male\n 7 │ SmokingStatus Currently smokes Never sm\noke\n 3 columns om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"first(dataset, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5×7 DataFrame\n Row │ Patient Weeks FVC Percent Age Sex Sm\noki ⋯\n │ String31 Int64 Int64 Float64 Int64 String7 St\nrin ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ ID00007637202177411956430 -4 2315 58.2536 79 Male Ex\n-sm ⋯\n 2 │ ID00007637202177411956430 5 2214 55.7121 79 Male Ex\n-sm\n 3 │ ID00007637202177411956430 7 2061 51.8621 79 Male Ex\n-sm\n 4 │ ID00007637202177411956430 9 2144 53.9507 79 Male Ex\n-sm\n 5 │ ID00007637202177411956430 11 2069 52.0634 79 Male Ex\n-sm ⋯\n 1 column om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart(dataset, patient_id; line_kws = true)\n info = patientinfo(dataset, patient_id)\n x = info[!, \"Weeks\"]\n y = info[!, \"FVC\"]\n\n p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)\n p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = \"Weeks\", ylabel = \"FVC\")\n \n if line_kws\n # Use the `GLM.jl` package to estimate linear regression\n linearFormulae = @formula(FVC ~ Weeks)\n linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))\n linearPredicted = predict(linearRegressor)\n p = plot!(p, x, linearPredicted, color = :red, lw = 3)\n end\n\n return p\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart(dataset, \"ID00007637202177411956430\")\np2 = patientchart(dataset, \"ID00009637202177434476278\")\np3 = patientchart(dataset, \"ID00010637202177584971671\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modelling:-Bayesian-Hierarchical-Linear-Regression-with-Partial-Pooling","page":"Bayesian Linear Regression Tutorial","title":"Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the \"pooled model.\" On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the \"unpooled model,\" where each patient has completely separate regression lines.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In this analysis, we will adopt a middle ground approach known as \"Partial pooling.\" Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Mathematically, the model is described by the following equations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n mu_alpha sim mathcalN(mathrmmean = 00 mathrmvariance = 2500000) \n sigma_alpha sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mu_beta sim mathcalN(mathrmmean = 00 mathrmvariance = 90) \n sigma_beta sim mathcalGamma(mathrmshape = 175 mathrmscale = 136) \n alpha_i sim mathcalN(mathrmmean = mu_alpha mathrmprecision = sigma_alpha) \n beta sim mathcalN(mathrmmean = mu_beta mathrmprecision = sigma_beta) \n sigma sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mathrmFVC_ij sim mathcalN(mathrmmean = alpha_i + t beta_i mathrmprecision = sigma)\n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Implementing this model in RxInfer is pretty straightforward:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled(patient_codes, weeks)\n μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β ~ Normal(mean = 0.0, var = 9.0) # Prior for the mean of β (slope)\n σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)\n σ_β ~ Gamma(shape = 1.75, scale = 1.36) # Prior for the precision of β (slope)\n\n n_codes = length(patient_codes) # Total number of data points\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution\n β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the standard deviation of the error term\n \n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes) # Observed FVC measurements\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@constraints function partially_pooled_constraints()\n # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent\n q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)\n # Assume that `μ_α`, `σ_α`, `α` are jointly independent\n q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)\n # Assume that `μ_β`, `σ_β`, `β` are jointly independent\n q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)\n # Assume that `FVC_est`, `σ` are jointly independent\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inference-in-the-model","page":"Bayesian Linear Regression Tutorial","title":"Inference in the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patient_ids = dataset[!, \"Patient\"] # get the column of all patients\npatient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));\npatient_code_column = map(patient -> patient_code_encoder[patient], patient_ids)\n\ndataset[!, :PatientCode] = patient_code_column\n\nfirst(patient_code_encoder, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5-element Vector{Pair{InlineStrings.String31, Int64}}:\n \"ID00197637202246865691526\" => 85\n \"ID00388637202301028491611\" => 160\n \"ID00341637202287410878488\" => 142\n \"ID00020637202178344345685\" => 9\n \"ID00305637202281772703145\" => 127","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_inference(dataset)\n\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n\n results = infer(\n model = partially_pooled(patient_codes, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n σ = vague(Gamma),\n σ_α = vague(Gamma),\n σ_β = vague(Gamma),\n ),\n returnvars = KeepLast(),\n iterations = 100\n )\n \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference_results = partially_pooled_inference(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Checking-the-model","page":"Bayesian Linear Regression Tutorial","title":"Checking the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspecting-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspecting the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)\n local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Looks like our model learned personalized alphas and betas for each patient!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Visualizing-FVC-decline-curves-for-some-patients","page":"Bayesian Linear Regression Tutorial","title":"Visualizing FVC decline curves for some patients","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)\n info = patientinfo(dataset, patient_id)\n patient_code_id = encoder[patient_id]\n\n patient_α = results.posteriors[:α][patient_code_id]\n patient_β = results.posteriors[:β][patient_code_id]\n\n estimated_σ = inv(mean(results.posteriors[:σ]))\n \n predict_weeks = range(-12, 134)\n\n predicted = map(predict_weeks) do week\n pm = mean(patient_α) + mean(patient_β) * week\n pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ\n return pm, sqrt(pv)\n end\n \n p = patientchart(dataset, patient_id; kwargs...)\n \n return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart_bayesian (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\")\np2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\")\np3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The results match our expectations perfectly! Let's highlight the observations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.\nThe model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.\nAdditionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Computing-the-modified-Laplace-Log-Likelihood-and-RMSE","page":"Bayesian Linear Regression Tutorial","title":"Computing the modified Laplace Log Likelihood and RMSE","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n sigma_mathrmclipped = max(sigma 70) \n delta = min(vert mathrmFVC_mathrmtrue - mathrmFVC_mathrmpredvert 1000) \n mathrmmetric = -fracsqrt2deltasigma_mathrmclipped - mathrmln(sqrt2sigma_mathrmclipped) \n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function FVC_predict(results)\n return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s\n return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"FVC_predict (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function compute_rmse(results, dataset)\n FVC_predicted = FVC_predict(results)\n return mean((dataset[!, \"FVC\"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)\nend\n\nfunction compute_laplace_log_likelihood(results, dataset)\n FVC_predicted = FVC_predict(results)\n sigma_c = std.(FVC_predicted)\n sigma_c[sigma_c .< 70] .= 70\n delta = abs.(mean.(FVC_predicted) .- dataset[!, \"FVC\"])\n delta[delta .> 1000] .= 1000\n return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"compute_laplace_log_likelihood (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.0313266260767\nLaplace Log Likelihood: -6.15689374755478","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Add-layer-to-model-hierarchy:-Smoking-Status","page":"Bayesian Linear Regression Tutorial","title":"Add layer to model hierarchy: Smoking Status","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We can enhance the model by incorporating the column \"SmokingStatus\" as a pooling level, where model parameters will be partially pooled within the groups \"Never smoked,\" \"Ex-smoker,\" and \"Currently smokes.\" To achieve this, we need to:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Encode the \"SmokingStatus\" column. Map the patient encoding to the corresponding \"SmokingStatus\" encodings. Refine and retrain the model with the additional hierarchical structure.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"combine(groupby(dataset, \"SmokingStatus\"), nrow)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"3×2 DataFrame\n Row │ SmokingStatus nrow\n │ String31 Int64\n─────┼─────────────────────────\n 1 │ Ex-smoker 1038\n 2 │ Never smoked 429\n 3 │ Currently smokes 82","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, \"SmokingStatus\"]))))\nsmoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id\n smoking_status = first(unique(patientinfo(dataset, patient_id)[!, \"SmokingStatus\"]))\n return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]\nend)\n\nsmoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)\n μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)\n σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n σ_β_global ~ Gamma(shape = 1.75, scale = 1.36) # Corresponds to half-normal with scale 3.0\n\n n_codes = length(patient_codes) # Total number of data points\n n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern\n μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern\n \n for i in 1:n_smoking_statuses\n μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)\n μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)\n end\n \n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)\n β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n\n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes)\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\n \nend\n\n@constraints function partially_pooled_with_smooking_constraints()\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)\n q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)\n q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)\n q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smooking_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n \n return infer(\n model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_with_smooking_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n σ = Gamma(1.75, 45.54),\n σ_α_global = Gamma(1.75, 45.54),\n σ_β_global = Gamma(1.75, 1.36),\n ),\n returnvars = KeepLast(),\n iterations = 100,\n )\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspect-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspect the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)\n local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)\n local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])\n local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α_global)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β_global)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n local p5 = plot(title = \"q(μ_α_smoking_status)...\", legend = false)\n local p6 = plot(title = \"q(μ_β_smoking_status)...\", legend = false)\n \n foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) \n foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)\n \n plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Interpret-smoking-status-model-parameters","page":"Bayesian Linear Regression Tutorial","title":"Interpret smoking status model parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Dict{InlineStrings.String31, Int64} with 3 entries:\n \"Currently smokes\" => 3\n \"Ex-smoker\" => 1\n \"Never smoked\" => 2","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]\n\nprintln(\"Trend for\")\nforeach(pairs(smoking_id_mapping)) do (key, id)\n println(\" $key: $(mean(posteriors_μ_β_smoking_status[id]))\")\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Trend for\n Currently smokes: 1.8157457671008241\n Ex-smoker: -4.56516461765951\n Never smoked: -4.446729680170274","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Let's look at these curves for individual patients to help interpret these model results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Never smoked\np1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\") \n# Ex-smoker\np2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\") \n# Currently smokes\np3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\") \n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Review-patients-that-currently-smoke","page":"Bayesian Linear Regression Tutorial","title":"Review patients that currently smoke","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"When plotting each patient with the smoking status \"Currently smokes,\" we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Depending on the purpose of the model, we can proceed in different ways:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.\nHowever, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the \"Currently smokes\" group's parameters closer to the global parameters, or even consider merging the group with \"Ex-smokers.\" Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"let \n local plots = []\n\n for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==(\"Currently smokes\"), dataset)[!, \"Patient\"]))\n push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))\n end\n\n plot(plots..., size = (1200, 1200))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modified-Laplace-Log-Likelihood-and-RMSE-for-model-with-Smoking-Status-Level","page":"Bayesian Linear Regression Tutorial","title":"Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We calculate the metrics for the updated model and compare to the original model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.7845980866563\nLaplace Log Likelihood: -6.165346437287973","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#References","page":"Bayesian Linear Regression Tutorial","title":"References","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#examples-probit-model-(ep)","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable x_t with the discrete variable y_t. The model is defined as:","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"beginaligned\n u = 01 \n x_0 sim mathcalN(0 100) \n x_t sim mathcalN(x_t-1+ u 001) \n y_t sim mathrmBer(Phi(x_t))\nendaligned","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Import-packages","page":"Probit Model (EP)","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"using RxInfer, StableRNGs, Random, Plots\nusing StatsFuns: normcdf","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Data-generation","page":"Probit Model (EP)","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n \n # hyper parameters\n u = 0.1\n\n # allocate space for data\n data_x = zeros(nr_samples + 1)\n data_y = zeros(nr_samples)\n \n # initialize data\n data_x[1] = -2\n \n # generate data\n for k = 2:nr_samples + 1\n \n # calculate new x\n data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)\n \n # calculate y\n data_y[k-1] = normcdf(data_x[k]) > rand(rng)\n \n end\n \n # return data\n return data_x, data_y\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"n = 40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"data_x, data_y = generate_data(n);","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"p = plot(xlabel = \"t\", ylabel = \"x, y\")\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\")","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Model-specification","page":"Probit Model (EP)","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"@model function probit_model(nr_samples::Int64)\n \n # allocate space for variables\n x = randomvar(nr_samples + 1)\n y = datavar(Float64, nr_samples)\n \n # specify uninformative prior\n x[1] ~ Normal(mean = 0.0, precision = 0.01)\n \n # create model \n for k = 2:nr_samples + 1\n x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)\n y[k - 1] ~ Probit(x[k]) where {\n # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge\n # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations\n pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) \n }\n end\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Inference","page":"Probit Model (EP)","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"result = infer(\n model = probit_model(length(data_y)), \n data = (y = data_y, ), \n iterations = 5, \n returnvars = (x = KeepLast(),),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"Inference results:\n Posteriors | available for (x)\n Free Energy: | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Results","page":"Probit Model (EP)","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"mx = result.posteriors[:x]\n\np = plot(xlabel = \"t\", ylabel = \"x, y\", legend = :bottomright)\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\", lw = 2)\np = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label=\"x (inferred mean)\")\n\nf = plot(xlabel = \"t\", ylabel = \"BFE\")\nf = plot!(result.free_energy, label = \"Bethe Free Energy\")\n\nplot(p, f, size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#examples-advanced-tutorial","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This tutorial is also available in the documentation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#General-model-specification-syntax","page":"Advanced Tutorial","title":"General model specification syntax","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We use the @model macro from the RxInfer.jl package to create a probabilistic model p(s y) and we also specify extra constraints on the variational family of distributions mathcalQ, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `@model` macro accepts a regular Julia function\n@model function test_model1(s_mean, s_precision)\n \n # We use the `randomvar` function to create \n # a random variable in our model\n s = randomvar()\n \n # the `tilde` operator creates a functional dependency\n # between variables in our model and can be read as \n # `sampled from` or `is modeled by`\n s ~ Normal(mean = s_mean, precision = s_precision)\n \n # We use the `datavar` function to create \n # observed data variables in our models\n # We also need to specify the type of our data \n # In this example it is `Float64`\n y = datavar(Float64)\n \n y ~ Normal(mean = s, precision = 1.0)\n \n # It is possible to return something from the model specification (including variables and nodes)\n return \"Hello world\"\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"modelgenerator = test_model1(0.0, 1.0)\n\nmodel, returnval = create_model(modelgenerator)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(FactorGraphModel(), \"Hello world\")","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(): returns an array of factor nodes in a corresponding factor graph\ngetrandom(): returns an array of random variables in the model\ngetdata(): returns an array of data inputs in the model\ngetconstant(): returns an array of constant values in the model","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(model)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"FactorNodesCollection(nodes: 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getrandom(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :s","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getdata(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :y","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getconstant(model) .|> getconst","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 1.0","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model2(n)\n \n if n <= 1\n error(\"`n` argument must be greater than one.\")\n end\n \n # `randomvar(n)` creates a dense sequence of \n # random variables\n s = randomvar(n)\n \n # `datavar(Float64, n)` creates a dense sequence of \n # observed data variables of type `Float64`\n y = datavar(Float64, n)\n \n s[1] ~ Normal(mean = 0.0, precision = 0.1)\n y[1] ~ Normal(mean = s[1], precision = 1.0)\n \n for i in 2:n\n s[i] ~ Normal(mean = s[i - 1], precision = 1.0)\n y[i] ~ Normal(mean = s[i], precision = 1.0)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, _ = create_model(test_model2(10));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of factor nodes in generated Factor Graph\ngetnodes(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"20","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of random variables\ngetrandom(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of data inputs\ngetdata(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of constant values\ngetconstant(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"21","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use complex expressions inside the functional dependency expressions","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# s = randomvar() here is optional\n# `~` creates random variables automatically\ns ~ NormalMeanPrecision(0.0, 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example model which will throw an error:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function error_model1()\n s = 1.0\n s ~ NormalMeanPrecision(0.0, 1.0)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Creates constant reference in a model with a prespecified value\nc = constvar(0.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)\n \n s = randomvar(n)\n \n y = datavar(Vector{Float64}, n)\n \n # Here we create constant references\n # for constant matrices in our model \n # to make inference more memory efficient\n cA = constvar(A)\n cP = constvar(P)\n cQ = constvar(Q)\n \n s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)\n y[1] ~ MvNormal(mean = s[1], covariance = cQ)\n \n for i in 2:n\n s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)\n y[i] ~ MvNormal(mean = s[i], covariance = cQ)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n\n # In this example `ynode` refers to the corresponding \n # `GaussianMeanVariance` node created in the factor graph\n ynode, y ~ GaussianMeanVariance(0.0, 1.0)\n \n return ynode, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Probabilistic-inference-in-RxInfer.jl","page":"Advanced Tutorial","title":"Probabilistic inference in RxInfer.jl","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Observables","page":"Advanced Tutorial","title":"Observables","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Observables are lazy push-based collections and they deliver their values over time.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Timer that emits a new value every second and has an initial one second delay \nobservable = timer(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerObservable(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"actor = (value) -> println(value)\nsubscription1 = subscribe!(observable, actor)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We always need to unsubscribe from some observables\nunsubscribe!(subscription1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We can modify our observables\nmodified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Int64, MapProxy(Int64))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscription2 = subscribe!(modified, (value) -> println(value))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(subscription2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n \n # We assume that the outcome of each coin flip \n # is modeled by a Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during the inference step\n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can call the inference function to run inference in such model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"p = 0.75 # Bias of a coin\n\ndataset = float.(rand(Bernoulli(p), 500));\n\nresult = infer(\n model = coin_toss_model(length(dataset)),\n data = (y = dataset, )\n)\n\nprintln(\"Inferred bias: \", mean_var(result.posteriors[:θ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inferred bias: (0.7347740667976425, 0.0003821198775672473)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can see that the inferred bias is quite close to the actual value we used in the dataset generation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getmarginal(x): for a single random variable x\ngetmarginals(xs): for a dense sequence of random variables sx","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = create_model(coin_toss_model(length(dataset)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# As soon as we have a new value for the marginal posterior over the `θ` variable\n# we simply print the first two statistics of it\nθ_subscription = subscribe!(getmarginal(θ), (marginal) -> println(\"New update: mean(θ) = \", mean(marginal), \", std(θ) = \", std(marginal)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To pass data to our model we use update! function","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"New update: mean(θ) = 0.7347740667976425, std(θ) = 0.019547886780090767","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It is necessary to always unsubscribe from running observables\nunsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them\n# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing\nupdate!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `keep` actor simply keeps all incoming updates in an internal storage, ordered\nθvalues = keep(Marginal)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"KeepActor{Marginal}(Marginal[])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `getmarginal` always emits last cached value as its first value\nsubscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=374.0, β=135.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"2-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=374.0, β=135.0))\n Marginal(Beta{Float64}(α=374.0, β=135.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `buffer` actor keeps very last incoming update in an internal storage and can also store \n# an array of updates for a sequence of random variables\nθbuffer = buffer(Marginal, 1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=374.0, β=135.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=374.0, β=135.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Reactive-Online-Inference","page":"Advanced Tutorial","title":"Reactive Online Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function online_coin_toss_model()\n \n # We create datavars for the prior \n # over `θ` variable\n θ_a = datavar(Float64)\n θ_b = datavar(Float64)\n \n θ ~ Beta(θ_a, θ_b)\n \n y = datavar(Float64)\n y ~ Bernoulli(θ)\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"autoupdates = @autoupdates begin \n θ_a, θ_b = params(q(θ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(θ_a,θ_b = params(q(θ)),)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"rxresult = infer(\n model = online_coin_toss_model(),\n data = (y = dataset, ),\n autoupdates = autoupdates,\n historyvars = (θ = KeepLast(), ),\n keephistory = length(dataset),\n initmarginals = (\n θ = vague(Beta),\n ),\n autostart = true\n);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"animation = @animate for i in 1:length(dataset)\n plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = \"Online coin bias inference\", label = \"Inferred bias\", legend = :bottomright)\n hline!([ p ], label = \"Real bias\", size = (600, 200))\nend\n\ngif(animation, \"../pics/online-coin-bias-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Variational-inference","page":"Advanced Tutorial","title":"Variational inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions q in mathcalQ. Often this involves assuming some factorization over q. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_a for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"There are several options to specify the mean-field factorisation constraint. ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use local structured factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-constraints-macro","page":"Advanced Tutorial","title":"RxInfer.jl constraints macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints6 = @constraints begin\n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: where blocks have higher priority over constraints specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Inference","page":"Advanced Tutorial","title":"Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To run inference in this model we again need to create a synthetic dataset:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#inference-function","page":"Advanced Tutorial","title":"inference function","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Use ?inference to quickly check the documentation for the inference function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"result = infer(\n model = test_model6(length(dataset)),\n data = (y = dataset, ),\n constraints = constraints6, \n initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),\n returnvars = (μ = KeepLast(), τ = KeepLast()),\n iterations = 10,\n free_energy = true,\n showprogress = true\n)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inference results:\n Posteriors | available for (μ, τ)\n Free Energy: | Real[14763.3, 3275.49, 644.502, 601.009, 601.009, 601.\n009, 601.009, 601.009, 601.009, 601.009]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(result.posteriors[:μ]), \", std = \", std(result.posteriors[:μ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -2.9919174008110594, std = 0.013849961458913337","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(result.posteriors[:τ]), \", std = \", std(result.posteriors[:τ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 5.213171798397569, std = 0.2329073393900073","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Manual-inference","page":"Advanced Tutorial","title":"Manual inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-2.997906986213373e-9, w=\n0.010000001002000566))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.46754573443492, w=9.1\n90565291792494))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9965.403984486915, w=333\n0.7787123998623))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15588.61696393659, w=521\n0.243095807691))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.400556480787, w=52\n13.178863918331))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409327454854, w=52\n13.181795468951))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336208271, w=52\n13.181798394724))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336217037, w=52\n13.18179839753))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336217064, w=52\n13.181798397531))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15597.409336217064, w=52\n13.181798397531))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(GammaShapeRate{Float64}(a=501.0, b=5.0000000000457144e14))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=54571.80294201576))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=150.4157277972677))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.1569263385032))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10277608069556))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272203871091))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198477709))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198472312))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198472299))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=96.10272198472299))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(last(μ_values)), \", std = \", std(last(μ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -2.9919174008110594, std = 0.013849961458913337","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(last(τ_values)), \", std = \", std(last(τ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 5.213171798397569, std = 0.2329073393900073","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Form-constraints","page":"Advanced Tutorial","title":"Form constraints","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints7 = @constraints begin \n q(μ) :: PointMass\n \n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_i for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar()\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, PointMass(1.0))\n\nμ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(PointMass{Float64}(-2.99191740653874))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(GammaShapeRate{Float64}(a=501.0, b=96.00681126848353))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { \n prod_constraint = ProdGeneric(),\n form_constraint = SampleListFormConstraint() \n}","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: @constraints macro specifies required prod_constraint automatically.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Free-Energy","page":"Advanced Tutorial","title":"Free Energy","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_observable = score(model, Float64, BetheFreeEnergy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Float64, ErrorIfProxy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_subscription = subscribe!(bfe_observable, (fe) -> println(\"Current BFE value: \", fe));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Reset the model with vague marginals\nsetmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Current BFE value: 613.4987949414008\nCurrent BFE value: 601.0091294023605\nCurrent BFE value: 601.0091291534445\nCurrent BFE value: 601.0091291534441\nCurrent BFE value: 601.0091291534454\nCurrent BFE value: 601.0091291534436\nCurrent BFE value: 601.0091291534454\nCurrent BFE value: 601.0091291534436\nCurrent BFE value: 601.0091291534454\nCurrent BFE value: 601.0091291534436","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It always necessary to unsubscribe and release computer resources\nunsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Meta-data-specification","page":"Advanced Tutorial","title":"Meta data specification","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of \n# the autoregressive process and its order. In addition it specifies that the message computation rules should\n# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations\n# by cost of possible numerical instabilities during an inference procedure\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }\n...\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` \n# method with `21` sigma points for approximation of non-lineariety between hierarchy layers\nxt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-@meta-macro","page":"Advanced Tutorial","title":"RxInfer.jl @meta macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@meta begin \n AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Meta specification:\n AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Creating-custom-nodes-and-message-computation-rules","page":"Advanced Tutorial","title":"Creating custom nodes and message computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-nodes","page":"Advanced Tutorial","title":"Custom nodes","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification\n@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]\n\n# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error\nstruct NormalMeanVariance end \n\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# It is also possible to use function objects as a node functional form\nfunction dot end\n\n# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them \n# out = dot(x, a)\n@node typeof(dot) Deterministic [ out, x, a ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"After that it is possible to use the newly created node during model specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n ...\n y ~ dot(x, a)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-messages-computation-rules","page":"Advanced Tutorial","title":"Custom messages computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu_z = mu_x + mu_y\nV_z = V_x + V_y\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To specify this in RxInfer.jl we use the @node and @rule macros:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@node typeof(+) Deterministic [ z, x, y ]\n\n@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin\n x_mean, x_var = mean_var(m_x)\n y_mean, y_var = mean_var(m_y)\n return NormalMeanVariance(x_mean + y_mean, x_var + y_var)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(z) = int q(z x y) mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu(z) = int f(x y z)mu(x)mu(y)mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nnu(z) = exp int log f(x y z)q(x)q(y)mathrmdxmathrmdy \nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @rule macro supports both cases with special prefixes during rule specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"m_ prefix corresponds to the incoming message on a specific edge\nq_ prefix corresponds to the posterior marginal of a specific edge","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Sum-Product rule with m_ messages used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin \n m_out_mean, m_out_cov = mean_cov(m_out)\n return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Variational rule with Mean-Field assumption with q_ posteriors used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin \n return NormalMeanPrecision(mean(q_out), mean(q_τ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin\n m, V = mean_cov(q_out_μ)\n θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))\n α = convert(typeof(θ), 1.5)\n return Gamma(α, θ)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference backend expects arguments in `@rule` macro to be in the same order\n@node NormalMeanPrecision Stochastic [ out, μ, τ ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Any rule always has access to the meta information with hidden the meta::Any variable:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin \n ...\n println(meta)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to dispatch on a specific type of a meta object:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"or","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Customizing-messages-computational-pipeline","page":"Advanced Tutorial","title":"Customizing messages computational pipeline","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Logs all outbound messages\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }\n# Initialise messages to be vague\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }\n# In principle, it is possible to approximate outbound messages with Laplace Approximation\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let us return to the coin toss model, but this time we want to print flowing messages:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model_log(n)\n\n y = datavar(Float64, n)\n\n θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage(\"θ\") }\n\n for i in 1:n\n y[i] ~ Bernoulli(θ) where { pipeline = LoggerPipelineStage(\"y[$i]\") }\n end\n \n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"θ_subscription = subscribe!(getmarginal(θ), (value) -> println(\"New posterior marginal for θ: \", value));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[θ][Beta][out]: VariationalMessage()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"coinflips = float.(rand(Bernoulli(0.5), 5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, coinflips)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[y[1]][Bernoulli][p]: VariationalMessage()\n[y[2]][Bernoulli][p]: VariationalMessage()\n[y[3]][Bernoulli][p]: VariationalMessage()\n[y[4]][Bernoulli][p]: VariationalMessage()\n[y[5]][Bernoulli][p]: VariationalMessage()\nNew posterior marginal for θ: Marginal(Beta{Float64}(α=5.0, β=9.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference is lazy and does not send messages if no one is listening for them\nupdate!(y, coinflips)","category":"page"},{"location":"manuals/custom-node/#create-node","page":"Defining a custom node and rules","title":"Creating your own custom nodes","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To create a custom node in RxInfer, 4 steps are required:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Create your custom node in RxInfer using the @node macro.\nDefine the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.\nSpecify computations for marginal distributions of the relevant variables with the @marginalrule macro.\nImplement the computation of the Free Energy in a node with the @average_energy macro.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!","category":"page"},{"location":"manuals/custom-node/#Problem-statement","page":"Defining a custom node and rules","title":"Problem statement","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin K=20 times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment x_kin01 using the Bernoulli distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_k mid pi) = mathrmBer(x_k mid pi) = pi^x_k (1-pi)^1-x_k","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"where pi in01 denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of pi which she models using the Beta distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(pi) = mathrmBeta(pi mid 4 8)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With this prior belief, the total probabilistic model that she has for this experiment is given by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_1K pi) = p(pi) prod_k=1^K p(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of pi, p(pi mid x_1K), denoting how pi is distributed after we have seen the data.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-1:-Creating-the-custom-node","page":"Defining a custom node and rules","title":"Step 1: Creating the custom node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nIn this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"First things first, let's import RxInfer:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using RxInfer","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The name of the node. (::Type)\nWhether the node is Deterministic or Stochastic.\nThe interfaces of the node and any potential aliases. (::Vector)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"# struct for Bernoulli distribution with success probability π\nstruct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution\n π :: T\n new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError(\"π must be between 0 and 1\"))\t\nend\n\n# for simplicity, let's also specify the mean of the distribution\nDistributions.mean(d::MyBernoulli) = d.π\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nYou can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of pi, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Concluding, we can create the MyBernoulli factor node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@node MyBernoulli Stochastic [out, (π, aliases = [p])]","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Cool! Step 1 is done, we have created a custom node.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-2:-Defining-rules-for-our-node","page":"Defining a custom node and rules","title":"Step 2: Defining rules for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as p(pimid x_1K), we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.","category":"page"},{"location":"manuals/custom-node/#Sum-product-message-passing-update-rules","page":"Defining a custom node and rules","title":"Sum-product message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In sum-product message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecmu(x) propto int mathrmBer(xmid pi) vecmu(pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(pi) propto sum_x in 01 mathrmBer(xmid pi) overleftarrowmu(x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain pi = fracalphaalpha + beta, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for \"the incoming message on interface π\". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(π) propto mathrmBeta(1 + x 2 - x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which gives us the following update rule:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin\n p = mean(m_out)\n Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/#Variational-message-passing-update-rules","page":"Defining a custom node and rules","title":"Variational message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecnu(x) propto exp int q(pi) ln mathrmBer(xmid pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrownu(pi) propto exp sum_x in 01 q(x) ln mathrmBer(xmid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"#rules towards out\n@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))\n\n@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin\n rho_1 = mean(log, q_π) # E[ln(x)]\n rho_2 = mean(mirrorlog, q_π) # E[log(1-x)]\n m = max(rho_1, rho_2)\n tmp = exp(rho_1 - m)\n p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))\n return Bernoulli(p)\nend\n\n#rules towards π\n@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin\n p = mean(q_out)\n return Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"node: Node\nTypically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-3:-Defining-joint-marginals-for-our-node","page":"Defining a custom node and rules","title":"Step 3: Defining joint marginals for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Fqf = - sum_ainmathcalV mathrmHq_a(s_a) - sum_ainmathcalVmathrmE_q_a(s_a)ln f_a(s_a) + sum_iinmathcalEmathrmHq_i(s_i)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here we call q_a(s_a) the joint marginals around a node and -mathrmE_q_a(s_a)ln f_a(s_a) we term the average energy.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to be able to compute the Bethe free energy, we need to first describe how to compute q_a(s_a), defined in our case as ","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"q(x_k pi) = vecmu(pi) overleftarrowmu(x_k) mathrmBer(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin\n r = mean(m_out)\n p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)\n return (out = m_out, p = p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as q(x_k pi) = q(x_k)q(pi). These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing q(pi) we need to compute the product vecmu(pi)overleftarrowmu(pi). We already know how overleftarrowmu(pi) looks like from the previous step, so we can just use the prod function.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-4:-Defining-the-average-energy-for-our-node","page":"Defining a custom node and rules","title":"Step 4: Defining the average energy for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as -mathrmE_q(x_k pi)ln p(x_k mid pi), however, because we know that we observe x_k and therefore q(x_k pi) factorizes, we can instead compute beginaligned -mathrmE_q(x_k)q(pi)ln p(x_k mid pi) = -mathrmE_q(x_k)q(pi) ln (pi^x_k (1-pi)^1 - x_k) \n= -mathrmE_q(x_k)q(pi) x_k ln(pi) + (1-x_k) ln(1-pi) \n= -mathrmE_q(x_k)x_k mathrmE_q(pi) ln(pi) - (1-mathrmE_q(x_k)x_k) mathrmE_q(pi)ln(1-pi) endaligned","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to mathrmE_q(x)1-logx.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....","category":"page"},{"location":"manuals/custom-node/#Using-our-node-in-a-model","page":"Defining a custom node and rules","title":"Using our node in a model","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Random\n\nrng = MersenneTwister(42)\nn = 500\nπ_real = 0.75\ndistribution = Bernoulli(π_real)\n\ndataset = float.(rand(rng, distribution, n))\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model_mybernoulli(n)\n\n # `datavar` creates data 'inputs' in our model\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n π ~ Beta(4.0, 8.0)\n\n # We assume that outcome of each coin flip is governed by the MyBernoulli distribution\n for i in 1:n\n y[i] ~ MyBernoulli(π)\n end\n\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Finally, we can run inference with this model and the generated dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"result_mybernoulli = infer(\n model = coin_model_mybernoulli(length(dataset)), \n data = (y = dataset, ),\n)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label=\"p(π|x)\", c=3)\nvline!([π_real], label=\"Real π\")","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model(n)\n \n y = datavar(Float64, n)\n p ~ Beta(4.0, 8.0)\n\n for i in 1:n\n y[i] ~ Bernoulli(p)\n end\n\nend\n\nresult_bernoulli = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, ),\n)\n\nif !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])\n error(\"Results are not identical\")\nelse \n println(\"Results are identical 🎉🎉🎉\")\nend\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#examples-simple-nonlinear-node","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using RxInfer, Random, StableRNGs","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here is an example of creating custom node with nonlinear function approximation with samplelist.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Custom-node-creation","page":"Simple Nonlinear Node","title":"Custom node creation","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"struct NonlinearNode end # Dummy structure just to make Julia happy\n\nstruct NonlinearMeta{R, F}\n rng :: R\n fn :: F # Nonlinear function, we assume 1 float input - 1 float output\n nsamples :: Int # Number of samples used in approximation\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@node NonlinearNode Deterministic [ out, in ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"We need to define two Sum-product message computation rules for our new custom node","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Rule for outbound message on out edge given inbound message on in edge\nRule for outbound message on in edge given inbound message on out edge\nBoth rules accept optional meta object","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `out` edge given inbound message on `in` edge\n@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin \n samples = rand(meta.rng, m_in, meta.nsamples)\n return SampleList(map(meta.fn, samples))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `in` edge given inbound message on `out` edge\n@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin \n return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Model-specification","page":"Simple Nonlinear Node","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"After we have defined our custom node with custom rules we may proceed with a model specification:","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"beginaligned\np(theta) = mathcalN(thetamu_theta sigma_theta)\np(m) = mathcalN(thetamu_m sigma_m)\np(w) = f(theta)\np(y_im w) = mathcalN(y_im w)\nendaligned","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable theta through a non-linear transformation f to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of theta. ","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@model function nonlinear_estimation(n)\n \n θ ~ Normal(mean = 0.0, variance = 100.0)\n m ~ Normal(mean = 0.0, variance = 1.0)\n \n w ~ NonlinearNode(θ)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = m, precision = w)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@constraints function nconstsraints(nsamples)\n q(θ) :: SampleList(nsamples, LeftProposal())\n q(w) :: SampleList(nsamples, RightProposal())\n \n q(θ, w, m) = q(θ)q(m)q(w)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nconstsraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@meta function nmeta(fn, nsamples)\n NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here we generate some data","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn(x) = abs(exp(x) * sin(x))","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"seed = 123\nrng = StableRNG(seed)\n\nniters = 15 # Number of VMP iterations\nnsamples = 5_000 # Number of samples in approximation\n\nn = 500 # Number of IID samples\nμ = -10.0\nθ = -1.0\nw = nonlinear_fn(θ)\n\ndata = rand(rng, NormalMeanPrecision(μ, w), n);","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"result = infer(\n model = nonlinear_estimation(n),\n meta = nmeta(nonlinear_fn, nsamples),\n constraints = nconstsraints(nsamples),\n data = (y = data, ), \n initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),\n returnvars = (θ = KeepLast(), ),\n iterations = niters, \n showprogress = true\n)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"θposterior = result.posteriors[:θ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"SampleList(Univariate, 5000)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using Plots, StatsPlots\n\nestimated = Normal(mean_std(θposterior)...)\n\nplot(estimated, title=\"Posterior for θ\", label = \"Estimated\", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))\nvline!([ θ ], label = \"Real value of θ\")","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"page"},{"location":"library/exported-methods/#lib-using-methods","page":"Exported methods","title":"Using methods from RxInfer","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"A nice explanation about how modules/packages work in Julia can be found in the official documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean as mean_from_rxinfer\nimport Distributions: mean as mean_from_distributions\n\nmean_from_rxinfer === mean_from_distributions","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"# It is easier to let Julia resolve names automatically\n# Julia will not overwrite `mean` that is coming from both packages\nusing RxInfer, Distributions ","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`","category":"page"},{"location":"library/exported-methods/#lib-list-methods","page":"Exported methods","title":"List of available methods","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"note: Note\nSome exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer #hide\nforeach(println, names(RxInfer))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/#examples-nonlinear-sensor-fusion","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"section"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers\nusing DataFrames, DelimitedFiles, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"To illustrate these noisy measurements, the engineers decided to plot them:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# fetch measurements\nbeacon_locations = readdlm(\"../data/sensor_fusion/beacons.txt\")\ndistances = readdlm(\"../data/sensor_fusion/distances.txt\")\nposition = readdlm(\"../data/sensor_fusion/position.txt\")\nnr_observations = size(distances, 1);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual location of WALL-E\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\")\n\n# plot noisy distance measurements\np2 = plot(distances, legend=:topleft, linewidth=3, label=[\"distance to beacon 1\" \"distance to beacon 2\" \"distance to beacon 3\"])\nxlabel!(\"time [sec]\"), ylabel!(\"distance [m]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time t, denoted by z_t, follows a 2-dimensional normal random walk:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(z_t mid z_t - 1) = mathcalN(z_t mid z_t-1mathrmI_2)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"where mathrmI_2 denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements y_t as a noisy set of the distances between WALL-E and the beacons, specified by s_i:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(y_t mid z_t) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixmathrmI_3 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# function to compute distance to beacons\nfunction compute_distances(z) \n distance1 = norm(z - beacon_locations[1,:])\n distance2 = norm(z - beacon_locations[2,:])\n distance3 = norm(z - beacon_locations[3,:])\n distances = [distance1, distance2, distance3]\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model(nr_observations)\n \n # specify precision matrices\n W = diageye(2)\n R = diageye(3)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], W)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":" compute_distances(z) -> CVI(..., Val(false), ...)","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)\n compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"NOTE: You can try out different meta for approximating the nonlinearity, e.g.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_linear_meta()\n compute_distances(z) -> Linearization()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_unscented_meta()\n compute_distances(z) -> Unscented()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_fast = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_accuracy = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1000, 100, StableRNG(42)),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"After running this fast inference procedure, the engineers plot the results and evaluate the performance:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_fast.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Fast (1 sample, 3 iterations)\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot beacon and actual and estimated location of WALL-E (accurate inference)\np2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_accuracy.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Accurate (1000 samples, 100 iterations)\"); p2.series_list[end][:label] = \"estimated location ±2σ\"\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, Q and R respectively. They did this by adding Wishart priors to those matrices:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(Q) = mathcalW(Q mid 3 mathrmI_2) \n p(R) = mathcalW(R mid 4 mathrmI_3) \n p(z_t mid z_t - 1 Q) = mathcalN(z_t mid z_t-1 Q^-1)\n p(y_t mid z_t R) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixR^-1 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model_wishart(nr_observations)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # set priors on precision matrices\n Q ~ Wishart(3, diageye(2))\n R ~ Wishart(4, diageye(3))\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], Q)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"meta = @meta begin \n compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"constraints = @constraints begin\n q(z, Q, R) = q(z)q(Q)q(R)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_wishart = infer(\n model = random_walk_model_wishart(nr_observations),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = constraints,\n meta = meta,\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),\n initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"They plot the new estimates and the performance over time, and luckily WALL-E is found!","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_wishart.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot bethe free energy performance\np2 = plot(results_wishart.free_energy, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"page"},{"location":"examples/problem_specific/overview/#examples-problem_specific-overview","page":"Overview","title":"Problem specific","text":"","category":"section"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Autoregressive Models: An example of Bayesian treatment of latent AR and ARMA models. Reference: Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.\nGamma Mixture Model: This example implements one of the Gamma mixture experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/ .\nGaussian Mixture: This example implements variational Bayesian inference in univariate and multivariate Gaussian mixture models with mean-field assumption.\nHierarchical Gaussian Filter: An example of online inference procedure for Hierarchical Gaussian Filter with univariate noisy observations using Variational Message Passing algorithm. Reference: Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter.\nInvertible neural networks: a tutorial: An example of variational Bayesian Inference with invertible neural networks. Reference: Bart van Erp, Hybrid Inference with Invertible Neural Networks in Factor Graphs.\nProbit Model (EP): In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model.\nRTS vs BIFM Smoothing: This example performs BIFM Kalman smoother on a factor graph using message passing and compares it with the RTS implementation.\nSimple Nonlinear Node: In this example we create a non-conjugate model and use a nonlinear link function between variables. We show how to extend the functionality of RxInfer and to create a custom factor node with arbitrary message passing update rules.\nUniversal Mixtures: Universal mixture modeling.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/#examples-coin-toss-model-(beta-bernoulli)","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"section"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"In this example, we are going to perform an exact inference for a coin toss model that can be represented as:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"beginaligned\np(theta) = mathrmBeta(thetaa b)\np(y_itheta) = mathrmBer(y_itheta)\nendaligned","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"where y_i in 0 1 is a binary observation induced by Bernoulli likelihood while theta is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of theta.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using RxInfer, Random","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"rng = MersenneTwister(42)\nn = 500\nθ_real = 0.75\ndistribution = Bernoulli(θ_real)\n\ndataset = float.(rand(rng, Bernoulli(θ_real), n));","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n θ ~ Beta(4.0, 8.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n\n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, )\n)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Beta{Float64}(α=365.0, β=147.0)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\nplot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\nvline!([θ_real], label=\"Real θ\")","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#examples-invertible-neural-networks:-a-tutorial","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Table of contents","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Introduction\nModel specification\nModel compilation\nProbabilistic inference\nParameter estimation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Introduction","page":"Invertible neural networks: a tutorial","title":"Introduction","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Load-required-packages","page":"Invertible neural networks: a tutorial","title":"Load required packages","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Before we can start, we need to import some packages:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using RxInfer\nusing Random\nusing StableRNGs\n\nusing ReactiveMP # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality\nusing LinearAlgebra # only used for some matrix specifics\nusing Plots # only used for visualisation\nusing Distributions # only used for sampling from multivariate distributions\nusing Optim # only used for parameter optimisation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-specification","page":"Invertible neural networks: a tutorial","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Alternatively, the input_dim can also be passed as an InputLayer layer as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the above AdditiveCouplingLayer layers the input bfx = x_1 x_2 ldots x_N is partitioned into chunks of unit length. These partitions are additively coupled to an output bfy = y_1 y_2 ldots y_N as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n y_1 = x_1 \n y_2 = x_2 + f_1(x_1) \n vdots \n y_N = x_N + f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Importantly, this structure can easily be converted as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n x_1 = y_1 \n x_2 = y_2 - f_1(x_1) \n vdots \n x_N = y_N - f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"f_n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow(); permute=false),\n PermutationLayer(PermutationMatrix(2)),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-compilation","page":"Invertible neural networks: a tutorial","title":"Model compilation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the current models, the layers are setup to work with the passed input dimension. This means that the function f_n is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P\nlanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa\nyerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou\nplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar\nFlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad\nditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive\nMP.PlanarFlowEmpty{1}(),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel - specifies that we are dealing with a flow model.\n3 - Number of layers.\nTuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.\nTuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions f_n.\nPermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(1.2018526210096325, -0.13275455\n874928943, -0.8599072121890323),), 1), PermutationLayer{Int64}(2, [0 1; 1 0\n]), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFl\now{Float64, Float64}(-1.1996171058581517, 0.8453788042976358, 2.35925874964\n65023),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361\n28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323\n52386),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Probabilistic-inference","page":"Invertible neural networks: a tutorial","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)\n\n rng = StableRNG(seed)\n \n # specify latent sampling distribution\n dist = MvNormal([1.5, 0.5], I)\n\n # sample from the latent distribution\n x = rand(rng, dist, nr_samples)\n\n # transform data\n y = zeros(Float64, size(x))\n for k = 1:nr_samples\n y[:,k] .= ReactiveMP.forward(model, x[:,k])\n end\n\n # return data\n return y, x\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# generate data\ny, x = generate_data(1000, compiled_model)\n\n# plot generated data\np1 = scatter(x[1,:], x[2,:], alpha=0.3, title=\"Original data\", size=(800,400))\np2 = scatter(y[1,:], y[2,:], alpha=0.3, title=\"Transformed data\", size=(800,400))\nplot(p1, p2, legend = false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The probabilistic model for doing inference can be described as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network(nr_samples::Int64)\n \n # initialize variables\n z_μ = randomvar()\n z_Λ = randomvar()\n x = randomvar(nr_samples)\n y_lat = randomvar(nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n\n # specify prior\n z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))\n z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)\n\n # specify transformed latent value\n y_lat[k] ~ Flow(x[k])\n\n # specify observations\n y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))\n\n end\n\n # return variables\n return z_μ, z_Λ, x, y_lat, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here the model is passed inside a meta data object of the flow node. Inference then resorts to","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"observations = [y[:,k] for k=1:size(y,2)]\n\nfmodel = invertible_neural_network(length(observations))\ndata = (y = observations, )\ninitmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))\nreturnvars = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())\n\nconstraints = @constraints begin\n q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)\nend\n\n@meta function fmeta(model)\n compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))\n Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). \n # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))\nend\n\n# First execution is slow due to Julia's initial compilation \nresult = infer(\n model = fmodel, \n data = data,\n constraints = constraints,\n meta = fmeta(model),\n initmarginals = initmarginals,\n returnvars = returnvars,\n free_energy = true,\n iterations = 10, \n showprogress = false\n)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Inference results:\n Posteriors | available for (z_μ, z_Λ, y_lat, x)\n Free Energy: | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357\n0.6, 23570.6, 23570.6, 23570.6, 23570.6]","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fe_flow = result.free_energy\nzμ_flow = result.posteriors[:z_μ]\nzΛ_flow = result.posteriors[:z_Λ]\nx_flow = result.posteriors[:x]\ny_flow = result.posteriors[:y_lat];","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"As we can see, the variational free energy decreases inside of our model.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"plot(1:10, fe_flow/size(y,2), xlabel=\"iteration\", ylabel=\"normalized variational free energy [nats/sample]\", legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"If we plot a random noisy observation and its approximated transformed uncertainty we obtain:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# pick a random observation\nid = rand(StableRNG(321), 1:size(y,2))\nrand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))\nwarped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');\n\np1 = scatter(x[1,:], x[2,:], alpha=0.1, title=\"Latent distribution\", size=(1200,500), label=\"generated data\")\ncontour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)\nscatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color=\"red\", markershape=:x, markersize=5, label=\"inferred mean\")\ncontour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, colorbar=false)\nscatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color=\"red\", label=\"transformed noisy observation\")\np2 = scatter(y[1,:], y[2,:], alpha=0.1, label=\"generated data\")\nscatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color=\"red\", marker=:x, label=\"inferred mean\")\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, label=\"random noisy observation\", colorba=false)\nscatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color=\"red\", label=\"random noisy observation\")\nplot(p1, p2, legend = true)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Parameter-estimation","page":"Invertible neural networks: a tutorial","title":"Parameter estimation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n\n # sample weights\n w = rand(rng, nr_samples, 2)\n\n # sample appraisal\n y = zeros(Float64, nr_samples)\n for k = 1:nr_samples\n y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)\n end\n\n # return data\n return y, w\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"data_y, data_x = generate_data(50);\nscatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel=\"w1\", ylabel=\"w2\", colorbar=false, legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We will then specify a possible model as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# specify flow model\nmodel = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The corresponding probabilistic model for the binary classification task can be created as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network_classifier(nr_samples::Int64)\n \n # initialize variables\n x_lat = randomvar(nr_samples)\n y_lat1 = randomvar(nr_samples)\n y_lat2 = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n x = datavar(Vector{Float64}, nr_samples)\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))\n\n # specify transformed latent value\n y_lat1[k] ~ Flow(x_lat[k])\n y_lat2[k] ~ dot(y_lat1[k], [1, 1])\n\n # specify observations\n y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }\n\n end\n\n # return variables\n return x_lat, x, y_lat1, y_lat2, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fcmodel = invertible_neural_network_classifier(length(data_y))\ndata = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )\n\n@meta function fmeta(model, params)\n compiled_model = compile(model, params)\n Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)\nend","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fmeta (generic function with 2 methods)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function f(params)\n Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure\n result = infer(\n model = fcmodel, \n data = data,\n meta = fmeta(model, params),\n free_energy = true,\n free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure\n iterations = 10, \n showprogress = false\n );\n \n result.free_energy[end]\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"uses finitediff and is slower/less accurate.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"or","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# create gradient function\ng = (x) -> ForwardDiff.gradient(f, x);\n\n# specify initial params\nparams = randn(nr_params(model))\n\n# create custom optimizer (here Adam)\noptimizer = Adam(params; λ=1e-1)\n\n# allocate space for gradient\n∇ = zeros(nr_params(model))\n\n# perform optimization\nfor it = 1:10000\n\n # backward pass\n ∇ .= ForwardDiff.gradient(f, optimizer.x)\n\n # gradient update\n ReactiveMP.update!(optimizer, ∇)\n\nend\n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Iter Function value Gradient norm \n 0 5.888958e+02 8.943663e+02\n * time: 5.984306335449219e-5\n 100 1.059826e+01 4.120090e+00\n * time: 11.85617995262146\n * Status: success\n\n * Candidate solution\n Final objective value: 1.010332e+01\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.21e-03 ≰ 0.0e+00\n |x - x'|/|x'| = 5.80e-04 ≰ 0.0e+00\n |f(x) - f(x')| = 6.28e-03 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03\n |g(x)| = 2.07e+00 ≰ 1.0e-08\n\n * Work counters\n Seconds run: 14 (vs limit Inf)\n Iterations: 113\n f(x) calls: 301\n ∇f(x) calls: 301","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"optimization results are then given as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"params = Optim.minimizer(res)\ninferred_model = compile(model, params)\ntrans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'\ntrans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])\ntrans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title=\"original data\")\np2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title=\"|> warp\")\np3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title=\"|> dot\")\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using StatsFuns: normcdf\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title=\"original labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title=\"predicted labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title=\"Classification map\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"contributing/new-example/#contributing-new-example","page":"Contributing to the examples","title":"Contributing to the examples","text":"","category":"section"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/\"subcategory\" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"After preparing the new example it is necessary to modify the examples/.meta.jl file.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"Make sure that the very first cell of the notebook contains ONLY # in it and has the markdown cell type. This is important for generating links in our documentation.\nThe path option must be set to a local path in a category sub-folder.\nThe text in the description option will be used on the Examples page in the documentation.\nSet category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).\nPlease do no use Overview as a name for the new example, the title Overview is reserved.\nUse the following template for equations, note that $$ and both \\begin and \\end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"$$\\begin{aligned}\n <latex equations here>\n\\end{aligned}$$","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.\nNotebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"variable = 0\nfor i in 1:10\n global variable = variable + i\nend","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.\nAll plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nPlease avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nUse make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.","category":"page"},{"location":"library/model-specification/#lib-model-specification","page":"Model specification","title":"Model specification in RxInfer","text":"","category":"section"},{"location":"library/model-specification/","page":"Model specification","title":"Model specification","text":"RxInfer.@model\nRxInfer.ModelGenerator\nRxInfer.create_model\nRxInfer.ModelInferenceOptions","category":"page"},{"location":"library/model-specification/#RxInfer.@model","page":"Model specification","title":"RxInfer.@model","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model description\nend\n\n@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.\n\nSupported alias in the model specification\n\na || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).\na && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\na -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\n¬a and !a: alias for NOT(a) node (Unicode \\neg, operator precedence ||, &&, -> and ! is the same as in Julia).\na + b + c: alias for (a + b) + c\na * b * c: alias for (a * b) * c\nNormal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.\nNormal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.\nMvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nGamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.\nGamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.\n\n\n\n\n\n","category":"macro"},{"location":"library/model-specification/#RxInfer.ModelGenerator","page":"Model specification","title":"RxInfer.ModelGenerator","text":"ModelGenerator\n\nModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"library/model-specification/#RxInfer.create_model","page":"Model specification","title":"RxInfer.create_model","text":"create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)\n\nCreates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.\n\nReturns a tuple of 2 values:\n\nan instance of FactorGraphModel\nreturn value from the @model macro function definition\n\n\n\n\n\n","category":"function"},{"location":"library/model-specification/#RxInfer.ModelInferenceOptions","page":"Model specification","title":"RxInfer.ModelInferenceOptions","text":"ModelInferenceOptions(; kwargs...)\n\nCreates model inference options object. The list of available options is present below.\n\nOptions\n\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\nwarn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.\n\nAdvanced options\n\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/getting-started/#user-guide-getting-started","page":"Getting started","title":"Getting started","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.","category":"page"},{"location":"manuals/getting-started/#Installation","page":"Getting started","title":"Installation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Install RxInfer through the Julia package manager:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"] add RxInfer","category":"page"},{"location":"manuals/getting-started/#Importing-RxInfer","page":"Getting started","title":"Importing RxInfer","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"To add RxInfer package (and all associated packages) into a running Julia session simply run:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more about about using in the Using methods from RxInfer section of the documentation.","category":"page"},{"location":"manuals/getting-started/#Example:-Inferring-the-bias-of-a-coin","page":"Getting started","title":"Example: Inferring the bias of a coin","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The RxInfer approach to solving inference problems consists of three phases:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.\nInference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.\nInference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.","category":"page"},{"location":"manuals/getting-started/#Coin-flip-simulation","page":"Getting started","title":"Coin flip simulation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"First let's setup our environment by importing all needed packages:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Next, let's define our dataset:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"rng = MersenneTwister(42)\nn = 10\np = 0.75\ndistribution = Bernoulli(p)\n\ndataset = float.(rand(rng, Bernoulli(p), n))","category":"page"},{"location":"manuals/getting-started/#getting-started-model-specification","page":"Getting started","title":"Model specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In 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.","category":"page"},{"location":"manuals/getting-started/#Likelihood","page":"Getting started","title":"Likelihood","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"y_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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 01.","category":"page"},{"location":"manuals/getting-started/#Prior","page":"Getting started","title":"Prior","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"theta sim Beta(a b)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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. ","category":"page"},{"location":"manuals/getting-started/#Joint-probability","page":"Getting started","title":"Joint probability","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The joint probability is given by the multiplication of the likelihood and the prior, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"P(y_1N θ) = P(θ) prod_i=1^N P(y_i θ)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Now let's see how to specify this model using GraphPPL's package syntax.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"\n# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n \n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during inference step\n return y, θ\nend\n","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create \"clamped\" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG. ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-specification","page":"Getting started","title":"Inference specification","text":"","category":"section"},{"location":"manuals/getting-started/#Automatic-inference-specification","page":"Getting started","title":"Automatic inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Once 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 inference function that supports static datasets.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"result = infer(\n model = coin_model(length(dataset)),\n data = (y = dataset, )\n)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more information about the inference function in the Static Inference documentation section.","category":"page"},{"location":"manuals/getting-started/#Manual-inference-specification","page":"Getting started","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Return variables of interests from model specification\nSubscribe on variables of interests posterior marginal updates\nPass data to the model\nUnsubscribe ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here is an example of inference procedure:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"function custom_inference(data)\n n = length(data)\n\n # `coin_model` function from `@model` macro returns a reference to the model generator object\n # we need to use the `create_model` function to get actual model object\n model, (y, θ) = create_model(coin_model(n))\n \n # Reference for future posterior marginal \n mθ = nothing\n\n # `getmarginal` function returns an observable of future posterior marginal updates\n # We use `Rocket.jl` API to subscribe on this observable\n # As soon as posterior marginal update is available we just save it in `mθ`\n subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)\n \n # `update!` function passes data to our data inputs\n update!(y, data)\n \n # It is always a good practice to unsubscribe and to \n # free computer resources held by the subscription\n unsubscribe!(subscription)\n \n # Here we return our resulting posterior marginal\n return mθ\nend","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-execution","page":"Getting started","title":"Inference execution","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = custom_inference(dataset)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title=\"Prior\", fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\np2 = plot(rθ, (x) -> pdf(θestimated, x), title=\"Posterior\", fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"dataset_100 = float.(rand(rng, Bernoulli(p), 100))\ndataset_1000 = float.(rand(rng, Bernoulli(p), 1000))\ndataset_10000 = float.(rand(rng, Bernoulli(p), 10000))\nnothing # hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated_100 = custom_inference(dataset_100)\nθestimated_1000 = custom_inference(dataset_1000)\nθestimated_10000 = custom_inference(dataset_10000)\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"p3 = plot(title = \"Posterior\", legend = :topleft)\n\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_100)\", c = 4)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_1000)\", c = 5)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_10000)\", c = 6)\n\nplot(p1, p3, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated_10000))\nprintln(\"std: \", std(θestimated_10000))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/#Where-to-go-next?","page":"Getting started","title":"Where to go next?","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.","category":"page"},{"location":"manuals/debugging/#user-guide-debugging","page":"Debugging","title":"Debugging","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want. ","category":"page"},{"location":"manuals/debugging/#Requesting-a-trace-of-messages","page":"Debugging","title":"Requesting a trace of messages","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a \"Memory Addon\". Below is an example explaining how you can extract this history and use it to fix a bug.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Consider the coin toss example from earlier in the documentation. We model the binary outcome x (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the theta parameter, with a known shape 𝑎 and rate 𝑏 parameter.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"x_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"theta sim mathrmBeta(a b)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"where x_i in 0 1 are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"using RxInfer, Random, Plots\n\nn = 4\nθ_real = 0.3\ndataset = convert.(Int64, rand(Bernoulli(θ_real), n))\n\n@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, huge)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);\n","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The model will run without errors. But when we plot the posterior distribution for theta, something's wrong. The posterior seems to be a flat distribution:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"\nrθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n addons = (AddonMemory(),)\n)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now we have access to the messages that led to the marginal posterior:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"underbraceoverrightarrowmu_θ(θ)_substack textoutgoing textmessage = sum_x_1ldotsx_n underbraceoverrightarrowmu_X_1(x_1)cdots overrightarrowmu_X_n(x_n)_substacktextincoming textmessages cdot underbracef(θx_1ldotsx_n)_substacktextnode textfunction","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Graph)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of theta we used in the code block above. So why does the posterior have this rate parameter?","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, 100)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"rθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now the posterior is visible in the plot.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#examples-active-inference-mountain-car","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#The-environmental-process-of-the-mountain","page":"Active Inference Mountain car","title":"The environmental process of the mountain","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Firstly, we specify the environmental process according to Ueltzhoeffer (2017) \"Deep active inference\". This process shows how the environment evolves after interacting with the agent.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Particularly, let's denote z_t = (phi_t dotphi_t) as the environmental state depending on the position phi_t and velocity dotphi_t of the car; a_t as the action of the environment on the car. Then the evolution of the state is described as follows ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndotphi_t = dotphi_t-1 + F_g(phi_t-1) + F_f(dotphi_t-1) + F_a(a_t)\nphi_t = phi_t-1 + dotphi_t \nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where F_g(phi_t-1) is the gravitational force of the hill landscape that depends on the car's position","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_g(phi) = begincases\n -005(2phi + 1) mathrmif phi 0 \n -005 left(1 + 5phi^2)^-frac12 + phi^2 (1 + 5phi^2)^-frac32 + frac116phi^4 right mathrmotherwise\nendcases","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_f(dotphi)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"is the friction on the car defined through the car's velocity F_f(dotphi) = -01 dotphi and F_a(a) is the engine force F_a(a) = 004 tanh(a) Since the car is on low battery, we use the tanh(cdot) function to limit the engine force to the interval [-0.04, 0.04].","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the create_physics function defines forces F_g F_f F_a; and the create_world function defines the environmental process of the mountain.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import HypergeometricFunctions: _₂F₁\n\nfunction create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)\n # Engine force as function of action\n Fa = (a::Real) -> engine_force_limit * tanh(a) \n\n # Friction force as function of velocity\n Ff = (y_dot::Real) -> -friction_coefficient * y_dot \n \n # Gravitational force (horizontal component) as function of position\n Fg = (y::Real) -> begin\n if y < 0\n 0.05*(-2*y - 1)\n else\n 0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)\n end\n end\n \n # The height of the landscape as a function of the horizontal coordinate\n height = (x::Float64) -> begin\n if x < 0\n h = x^2 + x\n else\n h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80\n end\n return 0.05*h\n end\n\n return (Fa, Ff, Fg,height)\nend;\n\nfunction create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)\n\n y_t_min = initial_position\n y_dot_t_min = initial_velocity\n \n y_t = y_t_min\n y_dot_t = y_dot_t_min\n \n execute = (a_t::Float64) -> begin\n # Compute next state\n y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)\n y_t = y_t_min + y_dot_t\n \n # Reset state for next step\n y_t_min = y_t\n y_dot_t_min = y_dot_t\n end\n \n observe = () -> begin \n return [y_t, y_dot_t]\n end\n \n return (execute, observe)\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_world (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Let's visualize the mountain landscape and the situation of the car. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"engine_force_limit = 0.04\nfriction_coefficient = 0.1\n\nFa, Ff, Fg, height = create_physics(\n engine_force_limit = engine_force_limit,\n friction_coefficient = friction_coefficient\n);\ninitial_position = -0.5\ninitial_velocity = 0.0\n\nx_target = [0.5, 0.0] \n\nvalley_x = range(-2, 2, length=400)\nvalley_y = [ height(xs) for xs in valley_x ]\nplot(valley_x, valley_y, title = \"Mountain valley\", label = \"Landscape\", color = \"black\")\nscatter!([ initial_position ], [ height(initial_position) ], label=\"initial car position\") \nscatter!([x_target[1]], [height(x_target[1])], label=\"camping site\")","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Naive-approach","page":"Active Inference Mountain car","title":"Naive approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"N_naive = 100 # Total simulation time\npi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only\n\n# Let there be a world\n(execute_naive, observe_naive) = create_world(; \n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n);\n\ny_naive = Vector{Vector{Float64}}(undef, N_naive)\nfor t = 1:N_naive\n execute_naive(pi_naive[t]) # Execute environmental process\n y_naive[t] = observe_naive() # Observe external states\nend\n\nanimation_naive = @animate for i in 1:N_naive\n plot(valley_x, valley_y, title = \"Naive policy\", label = \"Landscape\", color = \"black\", size = (800, 400))\n scatter!([y_naive[i][1]], [height(y_naive[i][1])], label=\"car\")\n scatter!([x_target[1]], [height(x_target[1])], label=\"goal\") \nend\n\n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_naive, \"../pics/ai-mountain-car-naive.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Active-inference-approach","page":"Active Inference Mountain car","title":"Active inference approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned\np_t(xsu) propto p(s_t-1) prod_k=t^t+T p(x_k mid s_k) p(s_k mid s_k-1u_k) p(u_k) p(x_k) nonumber\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where the factors are defined as","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k) = mathcalN(x_k mid x_goalV_goal) quad (mathrmtarget)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_k mid s_k-1u_k) = mathcalN(s_k mid tildeg(s_k-1)+h(u_k)gamma^-1) quad (mathrmstate transition)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k mid s_k) = mathcalN(x_k mid s_ktheta) quad (mathrmobservation)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(u_k) = mathcalN(u_k mid m_uV_u) quad (mathrmcontrol)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_t-1) = mathcalN(s_t-1 mid m_t-1V_t-1) quad (mathrmprevious state)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"x\ndenotes observations of the agent after interacting with the environment; \ns_t = (s_tdots_t)\nis the state of the car embodying its position and velocity; \nu_t\ndenotes the control state of the agent; \nh(cdot)\nis the tanh(cdot) function modeling engine control; \ntildeg(cdot)\nexecutes a linear approximation of equations (1) and (2): ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndots_t = dots_t-1 + F_g(s_t-1) + F_f(dots_t-1)\ns_t = s_t-1 + dots_t\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)\n \n # Transition function modeling transition due to gravity and friction\n g = (s_t_min::AbstractVector) -> begin \n s_t = similar(s_t_min) # Next state\n s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity\n s_t[1] = s_t_min[1] + s_t[2] # Update position\n return s_t\n end\n \n # Function for modeling engine control\n h = (u::AbstractVector) -> [0.0, Fa(u[1])] \n \n # Inverse engine force, from change in state to corresponding engine force\n h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] \n \n # Internal model perameters\n Gamma = 1e4*diageye(2) # Transition precision\n Theta = 1e-4*diageye(2) # Observation variance\n \n m_s_t_min = datavar(Vector{Float64})\n V_s_t_min = datavar(Matrix{Float64})\n\n s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)\n s_k_min = s_t_min\n \n m_u = datavar(Vector{Float64}, T)\n V_u = datavar(Matrix{Float64}, T)\n \n m_x = datavar(Vector{Float64}, T)\n V_x = datavar(Matrix{Float64}, T)\n \n u = randomvar(T)\n s = randomvar(T)\n x = randomvar(T)\n \n u_h_k = randomvar(T)\n s_g_k = randomvar(T)\n u_s_sum = randomvar(T)\n \n for k in 1:T\n u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])\n u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }\n s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }\n u_s_sum[k] ~ s_g_k[k] + u_h_k[k]\n s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)\n x[k] ~ MvNormal(mean = s[k], cov = Theta)\n x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal\n s_k_min = s[k]\n end\n \n return (s, )\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time t and gets T observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next T time step. \nInfer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state s_t and control u_t, i.e. p(s_tmid x_t) and p(u_tmid x_t).\nSlide: After updating its internal belief, the agent moves to the next time step and uses the inferred action u_t in the previous time step to interact with the environment. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next T positions based on the current action. These two function implement the Act-Execute-Observe phase.\nThe compute function infers the policy (which is a set of actions for the next T time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.\nThe slide function implements the Slide phase, which moves the agent internal model to the next time step.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"# We are going to use some private functionality from ReactiveMP, \n# in the future we should expose a proper API for this\nimport RxInfer.ReactiveMP: getrecent, messageout\n\nfunction create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)\n Epsilon = fill(huge, 1, 1) # Control prior variance\n m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors\n V_u = Matrix{Float64}[ Epsilon for k=1:T ]\n\n Sigma = 1e-4*diageye(2) # Goal prior variance\n m_x = [zeros(2) for k=1:T]\n V_x = [huge*diageye(2) for k=1:T]\n V_x[end] = Sigma # Set prior to reach goal at t=T\n\n # Set initial brain state prior\n m_s_t_min = [initial_position, initial_velocity] \n V_s_t_min = tiny * diageye(2)\n \n # Set current inference results\n result = nothing\n\n # The `infer` function is the heart of the agent\n # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing\n compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin\n m_u[1] = [ upsilon_t ] # Register action with the generative model\n V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action\n\n m_x[1] = y_hat_t # Register observation with the generative model\n V_x[1] = tiny*diageye(2) # Clamp goal prior to observation\n\n data = Dict(:m_u => m_u, \n :V_u => V_u, \n :m_x => m_x, \n :V_x => V_x,\n :m_s_t_min => m_s_t_min,\n :V_s_t_min => V_s_t_min)\n \n model = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) \n result = infer(model = model, data = data)\n end\n \n # The `act` function returns the inferred best possible action\n act = () -> begin\n if result !== nothing\n return mode(result.posteriors[:u][2])[1]\n else\n return 0.0 # Without inference result we return some 'random' action\n end\n end\n \n # The `future` function returns the inferred future states\n future = () -> begin \n if result !== nothing \n return getindex.(mode.(result.posteriors[:s]), 1)\n else\n return zeros(T)\n end\n end\n\n # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step\n # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`\n slide = () -> begin\n (s, ) = result.returnval\n \n slide_msg_idx = 3 # This index is model dependend\n (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))\n\n m_u = circshift(m_u, -1)\n m_u[end] = [0.0]\n V_u = circshift(V_u, -1)\n V_u[end] = Epsilon\n\n m_x = circshift(m_x, -1)\n m_x[end] = x_target\n V_x = circshift(V_x, -1)\n V_x[end] = Sigma\n end\n\n return (compute, act, slide, future) \nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_agent (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now it's time to see if we can help our friends arrive at the camping site by midnight?","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(execute_ai, observe_ai) = create_world(\n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n) # Let there be a world\n\nT_ai = 50\n\n(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent\n T = T_ai, \n Fa = Fa,\n Fg = Fg, \n Ff = Ff, \n engine_force_limit = engine_force_limit,\n x_target = x_target,\n initial_position = initial_position,\n initial_velocity = initial_velocity\n) \n\nN_ai = 100\n\n# Step through experimental protocol\nagent_a = Vector{Float64}(undef, N_ai) # Actions\nagent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future\nagent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations\n\nfor t=1:N_ai\n agent_a[t] = act_ai() # Invoke an action from the agent\n agent_f[t] = future_ai() # Fetch the predicted future states\n execute_ai(agent_a[t]) # The action influences hidden external states\n agent_x[t] = observe_ai() # Observe the current environmental outcome (update p)\n compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)\n slide_ai() # Prepare for next iteration\nend\n\nanimation_ai = @animate for i in 1:N_ai\n # pls - plot landscape\n pls = plot(valley_x, valley_y, title = \"Active inference results\", label = \"Landscape\", color = \"black\")\n pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label=\"car\")\n pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label=\"goal\") \n pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = \"Predicted future\", alpha = map(i -> 0.5 / i, 1:T_ai))\n \n # pef - plot engine force\n pef = plot(Fa.(agent_a[1:i]), title = \"Engine force (agents actions)\", xlim = (0, N_ai), ylim = (-0.05, 0.05))\n \n plot(pls, pef, size = (800, 400))\nend\n \n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_ai, \"../pics/ai-mountain-car-ai.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Voila! The car now is able to reach the camping site with a smart strategy.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now our friends can enjoy their trip at the camping site!. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Reference","page":"Active Inference Mountain car","title":"Reference","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We refer reader to the Thijs van de Laar (2019) \"Simulating active inference processes by message passing\" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) \"Deep active inference\".","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-free-energy","page":"Bethe Free Energy","title":"Bethe Free Energy implementation in RxInfer","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-factorized-model","page":"Bethe Free Energy","title":"Factorized model","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, y = (y_1 dots y_j dots y_m) and variables that can not be observed directly, also known as latent variables, x = (x_1 dots x_i dots x_n) We then define a model that factorizes over consituent smaller factors (functions), as f(yx) = prod_a f_a(y_ax_a)","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-vfe","page":"Bethe Free Energy","title":"Variational Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, Fq(haty) = mathbbE_q(x)leftlog fracq(x)f(y=haty x) right A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-variational-inference","page":"Bethe Free Energy","title":"Variational inference","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The goal of variational inference is to find a variational distibution that minimizes the VFE, q^*(x) = argmin_qinmathcalQ Fq(haty) This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-approximation","page":"Bethe Free Energy","title":"Bethe approximation","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, q(x) triangleq fracprod_a q_a(x_a)prod_i q_i(x_i)^d_i - 1 The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-bfe","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as F_Bq(haty) = sum_a U_aq_a(haty_a) - sum_a Hq_a + sum_i (d_i - 1) Hq_i The first term of the BFE specifies an average energy, U_aq_a(haty_a) = -mathbbE_q_a(x_a)leftlog f_a(y_a=haty_a x_a)right which internalizes the factors of the model. The last two terms specify entropies.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-further-reading","page":"Bethe Free Energy","title":"Further reading","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Pearl (1986) on the original foundations of Bayesian networks and belief propagation;\nYedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;\nDauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);\nSenoz et al. (2021) on constraint manipulation and message passing on FFGs.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"RxInfer.AbstractScoreObjective\nRxInfer.BetheFreeEnergy\nRxInfer.apply_diagnostic_check\nRxInfer.BetheFreeEnergyCheckNaNs\nRxInfer.BetheFreeEnergyCheckInfs","category":"page"},{"location":"library/bethe-free-energy/#RxInfer.AbstractScoreObjective","page":"Bethe Free Energy","title":"RxInfer.AbstractScoreObjective","text":"AbstractScoreObjective\n\nAbstract type for functional objectives that can be used in the score function. \n\nnote: Note\n\n\nscore is defined in the ReactiveMP package.\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergy","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergy","text":"BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)\n\nCreates Bethe Free Energy values stream when passed to the score function. \n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.apply_diagnostic_check","page":"Bethe Free Energy","title":"RxInfer.apply_diagnostic_check","text":"apply_diagnostic_check(check, context, stream)\n\nThis function applies a check to the stream. Accepts optional context object for custom error messages.\n\n\n\n\n\n","category":"function"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckNaNs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckNaNs","text":"BetheFreeEnergyCheckNaNs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return NaNs. Throws an error if finds NaN. \n\nSee also: BetheFreeEnergyCheckInfs\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckInfs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckInfs","text":"BetheFreeEnergyCheckInfs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return Infs. Throws an error if finds Inf. \n\nSee also: BetheFreeEnergyCheckNaNs\n\n\n\n\n\n","category":"type"},{"location":"manuals/background/#intro-background-variational-inference","page":"Background: variational inference","title":"Background: variational inference","text":"","category":"section"}] +} diff --git a/v2.16.1/siteinfo.js b/v2.16.1/siteinfo.js new file mode 100644 index 000000000..d25e42056 --- /dev/null +++ b/v2.16.1/siteinfo.js @@ -0,0 +1 @@ +var DOCUMENTER_CURRENT_VERSION = "v2.16.1"; diff --git a/v2.16.2/.documenter-siteinfo.json b/v2.16.2/.documenter-siteinfo.json new file mode 100644 index 000000000..f8baef8e1 --- /dev/null +++ b/v2.16.2/.documenter-siteinfo.json @@ -0,0 +1 @@ +{"documenter":{"julia_version":"1.10.1","generation_timestamp":"2024-02-22T13:41:00","documenter_version":"1.2.1"}} \ No newline at end of file diff --git a/v2.16.2/assets/biglogo-blacktheme.svg b/v2.16.2/assets/biglogo-blacktheme.svg new file mode 100644 index 000000000..101ebb89d --- /dev/null +++ b/v2.16.2/assets/biglogo-blacktheme.svg @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Generator: Adobe Illustrator 27.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) --> +<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" + viewBox="0 0 642.5 213.6" style="enable-background:new 0 0 642.5 213.6;" xml:space="preserve"> +<style type="text/css"> + .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFFFFF;stroke-miterlimit:10;} + .st1{fill:#389826;} + .st2{fill:#9558B2;} + .st3{fill:#FFFFFF;stroke:#FFFFFF;stroke-miterlimit:10;} + .st4{fill:#CB3C33;} + .st5{fill-rule:evenodd;clip-rule:evenodd;fill:#333333;stroke:#FFE9E9;stroke-miterlimit:10;} + .st6{fill-rule:evenodd;clip-rule:evenodd;fill:#4063D8;stroke:#FFFFFF;stroke-miterlimit:10;} +</style> +<g id="Слой_2"> + <g id="Layer_1_00000116955105323099935610000000039006590443086520_"> + <path class="st0" d="M66.6,114.5h63c6.7-0.3,12-5.8,12-12.5c0-14.1,0.3-27.6,0.3-41.5c0-6.3,5.1-11.4,11.3-11.4h40.1 + c6.3,0,11.4,5.1,11.4,11.4v40.1c0,6.3-5.1,11.4-11.4,11.4h-35.1c-6.2,0.9-10.8,6.2-10.8,12.4v70.9c0,9.8-8,17.8-17.9,17.8H66.6 + c-9.8,0-17.8-8-17.8-17.8V130c0-6.8-5.5-12.2-12.3-12.2H9.2c-4.8,0-8.7-3.9-8.7-8.7V78.2c0-4.8,3.9-8.7,8.7-8.7h28.7 + c6,0,10.8-4.8,10.8-10.8V13c0-6.9,5.6-12.5,12.5-12.5h44c6.9,0,12.5,5.6,12.5,12.5v44c0,6.9-5.6,12.5-12.5,12.5H59.6 + c-6,0-10.8,4.8-10.8,10.8v22c0,6.7,5.5,12.2,12.2,12.2H66.6z"/> + <rect x="62" y="13.8" class="st1" width="42.3" height="42.3"/> + <rect x="155.2" y="62.4" class="st2" width="36.2" height="36.2"/> + <rect x="13.7" y="82.8" class="st3" width="21.7" height="21.7"/> + <rect x="62" y="127.7" class="st4" width="72" height="72"/> + <path class="st5" d="M213.7,130.1c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.1-9.6,10.4-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.1,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C223.6,131.6,219,130.1,213.7,130.1z"/> + <polygon class="st0" points="281.9,165.8 306.4,130.8 294,130.8 276.2,156.7 260.4,130.8 232.2,130.8 259.8,175.5 234.7,211.6 + 247.2,211.6 265.4,184.8 281.9,211.6 310,211.6 "/> + <polygon class="st0" points="342.1,211.6 342.1,130 315.8,134.3 315.8,211.6 "/> + <path class="st6" d="M329.3,124.6c3.7,0.1,7.2-1.3,9.8-3.9c2.6-2.7,4-6.3,3.9-10.1c0.1-3.7-1.3-7.3-3.9-9.9s-6.1-4.1-9.8-4 + c-3.9-0.1-7.6,1.3-10.4,4c-2.7,2.6-4.2,6.2-4.1,9.9c-0.1,3.8,1.4,7.5,4.1,10.1C321.7,123.3,325.6,124.8,329.3,124.6z"/> + <path class="st0" d="M405.2,129.3c-5.7-0.1-11.3,1.4-16.3,4.1c-4.8,2.5-8.8,6.3-11.7,10.9V130l-26.3,4.3v77.3h26.3v-55.4 + c3.6-8.1,10.4-13.3,17.6-13.3c6.6,0,11.5,5.2,11.5,12.5v56.2h26.3v-55.7c0.2-7.2-2.6-14.1-7.8-19 + C419.6,131.9,413.1,129.4,405.2,129.3z"/> + <path class="st0" d="M479.3,93.6c-9.7,0-17.8,2.8-24.3,8.3s-9.8,12.5-9.8,20.7v8.2h-9.4v8.7h9.4v72.1h26.3v-72.1h16.4v-8.7h-16.4 + v-10.3c-0.2-4.3,1.3-8.5,4.1-11.8c2.7-3.1,6.6-4.9,10.6-5c-1.4,1.9-2.1,4.2-2.1,6.6c0,2.9,1.2,5.7,3.4,7.7 + c2.2,2.1,5.1,3.3,8.1,3.2c2.8,0.1,5.6-1.1,7.6-3.1s3.2-4.8,3.1-7.7c0-4.7-2.6-8.7-7.7-11.9S487,93.6,479.3,93.6z"/> + <path class="st0" d="M527.9,129.4v8.6l0,0V129.4L527.9,129.4z"/> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M527.3,129.3c-11.7,0.2-21.6,4.2-29.7,12c-8.3,7.9-12.6,17.9-12.6,29.8c-0.2,11.4,4.6,22.4,13.2,29.9 + c7.9,7.3,17.9,11.3,29.8,12v-0.1c1.2,0.1,2.5,0.1,3.7,0.1c9.9,0,18.4-2.1,25.4-6.4s10.5-9.5,10.5-15.7c0.1-3-1.1-6-3.2-8.2 + c-2-2.2-4.9-3.3-7.9-3.3c-3.2-0.1-6.2,1.1-8.5,3.3c-2.3,2.1-3.6,5.1-3.6,8.2c-0.1,3.9,1.9,7.6,5.4,9.5c-3.3,1.5-6.9,2.3-10.5,2.2 + c-3.9,0.1-7.8-0.6-11.4-2l0,0c-9.9-3.9-15.2-13.8-16-29.5h55.9c0-12-3.8-22-11.4-29.9c-7.6-8-17.2-11.9-28.8-11.9L527.3,129.3 + M527.9,138c8.5,0.1,14.2,9.1,15.1,24.4h-15.7l0,0h-15.1c0.6-7.3,2.4-13.2,5.3-17.7C520.3,140.5,523.8,138.2,527.9,138L527.9,138" + /> + <path class="st0" d="M527.9,138L527.9,138L527.9,138L527.9,138z"/> + <path class="st0" d="M623.6,129.4c-10.1,0-18.8,5.9-23.3,15.6v-15l-26.3,4.3v77.3h26.3v-54.1c3.2-9.6,10.3-16,19.2-16.4 + c-1,1.7-1.5,3.7-1.4,5.7c0,6.8,5.2,11.7,12.3,11.7c3.1,0.1,6.1-1.1,8.3-3.4c2.2-2.2,3.4-5.2,3.3-8.4c0.2-4.7-1.7-9.3-5.1-12.6 + C633.4,130.9,629,129.4,623.6,129.4z"/> + </g> +</g> +<g id="Layer_2_00000036966862148631286250000015780344526604021166_"> +</g> +</svg> diff --git a/v2.16.2/assets/biglogo.svg b/v2.16.2/assets/biglogo.svg new file mode 100644 index 000000000..b9f3d9f8e --- /dev/null +++ b/v2.16.2/assets/biglogo.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 641.51 212.57"><defs><style>.cls-1{fill:#333;}.cls-1,.cls-6{fill-rule:evenodd;}.cls-2{fill:#389826;}.cls-3{fill:#9558b2;}.cls-4{fill:#fff;}.cls-5{fill:#cb3c33;}.cls-6{fill:#4063d8;}</style></defs><title>1 \ No newline at end of file diff --git a/v2.16.2/assets/documenter.js b/v2.16.2/assets/documenter.js new file mode 100644 index 000000000..f5311607b --- /dev/null +++ b/v2.16.2/assets/documenter.js @@ -0,0 +1,889 @@ +// Generated by Documenter.jl +requirejs.config({ + paths: { + 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', + 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', + 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', + 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', + 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', + 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', + 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', + 'katex': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min', + 'highlight': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min', + 'highlight-julia-repl': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia-repl.min', + }, + shim: { + "highlight-julia": { + "deps": [ + "highlight" + ] + }, + "katex-auto-render": { + "deps": [ + "katex" + ] + }, + "headroom-jquery": { + "deps": [ + "jquery", + "headroom" + ] + }, + "highlight-julia-repl": { + "deps": [ + "highlight" + ] + } +} +}); +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'katex', 'katex-auto-render'], function($, katex, renderMathInElement) { +$(document).ready(function() { + renderMathInElement( + document.body, + { + "delimiters": [ + { + "left": "$", + "right": "$", + "display": false + }, + { + "left": "$$", + "right": "$$", + "display": true + }, + { + "left": "\\[", + "right": "\\]", + "display": true + } + ] +} + + ); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'highlight', 'highlight-julia', 'highlight-julia-repl'], function($) { +$(document).ready(function() { + hljs.highlightAll(); +}) + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let timer = 0; +var isExpanded = true; + +$(document).on("click", ".docstring header", function () { + let articleToggleTitle = "Expand docstring"; + + debounce(() => { + if ($(this).siblings("section").is(":visible")) { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + } else { + $(this) + .find(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + articleToggleTitle = "Collapse docstring"; + } + + $(this) + .find(".docstring-article-toggle-button") + .prop("title", articleToggleTitle); + $(this).siblings("section").slideToggle(); + }); +}); + +$(document).on("click", ".docs-article-toggle-button", function () { + let articleToggleTitle = "Expand docstring"; + let navArticleToggleTitle = "Expand all docstrings"; + + debounce(() => { + if (isExpanded) { + $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + + isExpanded = false; + + $(".docstring section").slideUp(); + } else { + $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); + $(".docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); + + isExpanded = true; + articleToggleTitle = "Collapse docstring"; + navArticleToggleTitle = "Collapse all docstrings"; + + $(".docstring section").slideDown(); + } + + $(this).prop("title", navArticleToggleTitle); + $(".docstring-article-toggle-button").prop("title", articleToggleTitle); + }); +}); + +function debounce(callback, timeout = 300) { + if (Date.now() - timer > timeout) { + callback(); + } + + clearTimeout(timer); + + timer = Date.now(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require([], function() { +function addCopyButtonCallbacks() { + for (const el of document.getElementsByTagName("pre")) { + const button = document.createElement("button"); + button.classList.add("copy-button", "fa-solid", "fa-copy"); + button.setAttribute("aria-label", "Copy this code block"); + button.setAttribute("title", "Copy"); + + el.appendChild(button); + + const success = function () { + button.classList.add("success", "fa-check"); + button.classList.remove("fa-copy"); + }; + + const failure = function () { + button.classList.add("error", "fa-xmark"); + button.classList.remove("fa-copy"); + }; + + button.addEventListener("click", function () { + copyToClipboard(el.innerText).then(success, failure); + + setTimeout(function () { + button.classList.add("fa-copy"); + button.classList.remove("success", "fa-check", "fa-xmark"); + }, 5000); + }); + } +} + +function copyToClipboard(text) { + // clipboard API is only available in secure contexts + if (window.navigator && window.navigator.clipboard) { + return window.navigator.clipboard.writeText(text); + } else { + return new Promise(function (resolve, reject) { + try { + const el = document.createElement("textarea"); + el.textContent = text; + el.style.position = "fixed"; + el.style.opacity = 0; + document.body.appendChild(el); + el.select(); + document.execCommand("copy"); + + resolve(); + } catch (err) { + reject(err); + } finally { + document.body.removeChild(el); + } + }); + } +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addCopyButtonCallbacks); +} else { + addCopyButtonCallbacks(); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'headroom', 'headroom-jquery'], function($, Headroom) { + +// Manages the top navigation bar (hides it when the user starts scrolling down on the +// mobile). +window.Headroom = Headroom; // work around buggy module loading? +$(document).ready(function () { + $("#documenter .docs-navbar").headroom({ + tolerance: { up: 10, down: 10 }, + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery', 'minisearch'], function($, minisearch) { + +// In general, most search related things will have "search" as a prefix. +// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +let results = []; +let timer = undefined; + +let data = documenterSearchIndex["docs"].map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; +}); + +// list below is the lunr 2.1.3 list minus the intersect with names(Base) +// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) +// ideally we'd just filter the original list but it's not available as a variable +const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", +]); + +let index = new minisearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification + tokenize: (string) => string.split(/[\s\-\.]+/), + // options which will be applied during the search + searchOptions: { + boost: { title: 100 }, + fuzzy: 2, + processTerm: (term) => { + let word = stopWords.has(term) ? null : term; + if (word) { + word = word + .replace(/^[^a-zA-Z0-9@!]+/, "") + .replace(/[^a-zA-Z0-9@!]+$/, ""); + } + + return word ?? null; + }, + tokenize: (string) => string.split(/[\s\-\.]+/), + }, +}); + +index.addAll(data); + +let filters = [...new Set(data.map((x) => x.category))]; +var modal_filters = make_modal_body_filters(filters); +var filter_results = []; + +$(document).on("keyup", ".documenter-search-input", function (event) { + // Adding a debounce to prevent disruptions from super-speed typing! + debounce(() => update_search(filter_results), 300); +}); + +$(document).on("click", ".search-filter", function () { + if ($(this).hasClass("search-filter-selected")) { + $(this).removeClass("search-filter-selected"); + } else { + $(this).addClass("search-filter-selected"); + } + + // Adding a debounce to prevent disruptions from crazy clicking! + debounce(() => get_filters(), 300); +}); + +/** + * A debounce function, takes a function and an optional timeout in milliseconds + * + * @function callback + * @param {number} timeout + */ +function debounce(callback, timeout = 300) { + clearTimeout(timer); + timer = setTimeout(callback, timeout); +} + +/** + * Make/Update the search component + * + * @param {string[]} selected_filters + */ +function update_search(selected_filters = []) { + let initial_search_body = ` +
Type something to get started!
+ `; + + let querystring = $(".documenter-search-input").val(); + + if (querystring.trim()) { + results = index.search(querystring, { + filter: (result) => { + // Filtering results + if (selected_filters.length === 0) { + return result.score >= 1; + } else { + return ( + result.score >= 1 && selected_filters.includes(result.category) + ); + } + }, + }); + + let search_result_container = ``; + let search_divider = `
`; + + if (results.length) { + let links = []; + let count = 0; + let search_results = ""; + + results.forEach(function (result) { + if (result.location) { + // Checking for duplication of results for the same page + if (!links.includes(result.location)) { + search_results += make_search_result(result, querystring); + count++; + } + + links.push(result.location); + } + }); + + let result_count = `
${count} result(s)
`; + + search_result_container = ` +
+ ${modal_filters} + ${search_divider} + ${result_count} +
+ ${search_results} +
+
+ `; + } else { + search_result_container = ` +
+ ${modal_filters} + ${search_divider} +
0 result(s)
+
+
No result found!
+ `; + } + + if ($(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").removeClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(search_result_container); + } else { + filter_results = []; + modal_filters = make_modal_body_filters(filters, filter_results); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".search-modal-card-body").html(initial_search_body); + } +} + +/** + * Make the modal filter html + * + * @param {string[]} filters + * @param {string[]} selected_filters + * @returns string + */ +function make_modal_body_filters(filters, selected_filters = []) { + let str = ``; + + filters.forEach((val) => { + if (selected_filters.includes(val)) { + str += `${val}`; + } else { + str += `${val}`; + } + }); + + let filter_html = ` +
+ Filters: + ${str} +
+ `; + + return filter_html; +} + +/** + * Make the result component given a minisearch result data object and the value of the search input as queryString. + * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ +function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } + + let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${result.title}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; +} + +/** + * Get selected filters, remake the filter html and lastly update the search modal + */ +function get_filters() { + let ele = $(".search-filters .search-filter-selected").get(); + filter_results = ele.map((x) => $(x).text().toLowerCase()); + modal_filters = make_modal_body_filters(filters, filter_results); + update_search(filter_results); +} + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Modal settings dialog +$(document).ready(function () { + var settings = $("#documenter-settings"); + $("#documenter-settings-button").click(function () { + settings.toggleClass("is-active"); + }); + // Close the dialog if X is clicked + $("#documenter-settings button.delete").click(function () { + settings.removeClass("is-active"); + }); + // Close dialog if ESC is pressed + $(document).keyup(function (e) { + if (e.keyCode == 27) settings.removeClass("is-active"); + }); +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +let search_modal_header = ` +
+
+

+ + + + +

+
+
+ +
+
+`; + +let initial_search_body = ` +
Type something to get started!
+`; + +let search_modal_footer = ` +
+ + Ctrl + + / to search + + esc to close +
+`; + +$(document.body).append( + ` + + ` +); + +document.querySelector(".docs-search-query").addEventListener("click", () => { + openModal(); +}); + +document.querySelector(".close-search-modal").addEventListener("click", () => { + closeModal(); +}); + +$(document).on("click", ".search-result-link", function () { + closeModal(); +}); + +document.addEventListener("keydown", (event) => { + if ((event.ctrlKey || event.metaKey) && event.key === "/") { + openModal(); + } else if (event.key === "Escape") { + closeModal(); + } + + return false; +}); + +// Functions to open and close a modal +function openModal() { + let searchModal = document.querySelector("#search-modal"); + + searchModal.classList.add("is-active"); + document.querySelector(".documenter-search-input").focus(); +} + +function closeModal() { + let searchModal = document.querySelector("#search-modal"); + let initial_search_body = ` +
Type something to get started!
+ `; + + searchModal.classList.remove("is-active"); + document.querySelector(".documenter-search-input").blur(); + + if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { + $(".search-modal-card-body").addClass("is-justify-content-center"); + } + + $(".documenter-search-input").val(""); + $(".search-modal-card-body").html(initial_search_body); +} + +document + .querySelector("#search-modal .modal-background") + .addEventListener("click", () => { + closeModal(); + }); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Manages the showing and hiding of the sidebar. +$(document).ready(function () { + var sidebar = $("#documenter > .docs-sidebar"); + var sidebar_button = $("#documenter-sidebar-button"); + sidebar_button.click(function (ev) { + ev.preventDefault(); + sidebar.toggleClass("visible"); + if (sidebar.hasClass("visible")) { + // Makes sure that the current menu item is visible in the sidebar. + $("#documenter .docs-menu a.is-active").focus(); + } + }); + $("#documenter > .docs-main").bind("click", function (ev) { + if ($(ev.target).is(sidebar_button)) { + return; + } + if (sidebar.hasClass("visible")) { + sidebar.removeClass("visible"); + } + }); +}); + +// Resizes the package name / sitename in the sidebar if it is too wide. +// Inspired by: https://github.com/davatron5000/FitText.js +$(document).ready(function () { + e = $("#documenter .docs-autofit"); + function resize() { + var L = parseInt(e.css("max-width"), 10); + var L0 = e.width(); + if (L0 > L) { + var h0 = parseInt(e.css("font-size"), 10); + e.css("font-size", (L * h0) / L0); + // TODO: make sure it survives resizes? + } + } + // call once and then register events + resize(); + $(window).resize(resize); + $(window).on("orientationchange", resize); +}); + +// Scroll the navigation bar to the currently selected menu item +$(document).ready(function () { + var sidebar = $("#documenter .docs-menu").get(0); + var active = $("#documenter .docs-menu .is-active").get(0); + if (typeof active !== "undefined") { + sidebar.scrollTop = active.offsetTop - sidebar.offsetTop - 15; + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// Theme picker setup +$(document).ready(function () { + // onchange callback + $("#documenter-themepicker").change(function themepick_callback(ev) { + var themename = $("#documenter-themepicker option:selected").attr("value"); + if (themename === "auto") { + // set_theme(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'); + window.localStorage.removeItem("documenter-theme"); + } else { + // set_theme(themename); + window.localStorage.setItem("documenter-theme", themename); + } + // We re-use the global function from themeswap.js to actually do the swapping. + set_theme_from_local_storage(); + }); + + // Make sure that the themepicker displays the correct theme when the theme is retrieved + // from localStorage + if (typeof window.localStorage !== "undefined") { + var theme = window.localStorage.getItem("documenter-theme"); + if (theme !== null) { + $("#documenter-themepicker option").each(function (i, e) { + e.selected = e.value === theme; + }); + } + } +}); + +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { + +// update the version selector with info from the siteinfo.js and ../versions.js files +$(document).ready(function () { + // If the version selector is disabled with DOCUMENTER_VERSION_SELECTOR_DISABLED in the + // siteinfo.js file, we just return immediately and not display the version selector. + if ( + typeof DOCUMENTER_VERSION_SELECTOR_DISABLED === "boolean" && + DOCUMENTER_VERSION_SELECTOR_DISABLED + ) { + return; + } + + var version_selector = $("#documenter .docs-version-selector"); + var version_selector_select = $("#documenter .docs-version-selector select"); + + version_selector_select.change(function (x) { + target_href = version_selector_select + .children("option:selected") + .get(0).value; + window.location.href = target_href; + }); + + // add the current version to the selector based on siteinfo.js, but only if the selector is empty + if ( + typeof DOCUMENTER_CURRENT_VERSION !== "undefined" && + $("#version-selector > option").length == 0 + ) { + var option = $( + "" + ); + version_selector_select.append(option); + } + + if (typeof DOC_VERSIONS !== "undefined") { + var existing_versions = version_selector_select.children("option"); + var existing_versions_texts = existing_versions.map(function (i, x) { + return x.text; + }); + DOC_VERSIONS.forEach(function (each) { + var version_url = documenterBaseURL + "/../" + each + "/"; + var existing_id = $.inArray(each, existing_versions_texts); + // if not already in the version selector, add it as a new option, + // otherwise update the old option with the URL and enable it + if (existing_id == -1) { + var option = $( + "" + ); + version_selector_select.append(option); + } else { + var option = existing_versions[existing_id]; + option.value = version_url; + option.disabled = false; + } + }); + } + + // only show the version selector if the selector has been populated + if (version_selector_select.children("option").length > 0) { + version_selector.toggleClass("visible"); + } +}); + +}) diff --git a/v2.16.2/assets/examples/Active Inference Mountain car_4_1.png b/v2.16.2/assets/examples/Active Inference Mountain car_4_1.png new file mode 100644 index 000000000..9394d1730 Binary files /dev/null and b/v2.16.2/assets/examples/Active Inference Mountain car_4_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_12_1.png b/v2.16.2/assets/examples/Autoregressive Models_12_1.png new file mode 100644 index 000000000..5f7b543d9 Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_12_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_13_1.png b/v2.16.2/assets/examples/Autoregressive Models_13_1.png new file mode 100644 index 000000000..99416e777 Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_13_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_14_1.png b/v2.16.2/assets/examples/Autoregressive Models_14_1.png new file mode 100644 index 000000000..e4b52db2e Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_14_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_24_1.png b/v2.16.2/assets/examples/Autoregressive Models_24_1.png new file mode 100644 index 000000000..92d942e95 Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_24_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_32_1.png b/v2.16.2/assets/examples/Autoregressive Models_32_1.png new file mode 100644 index 000000000..9b30d0046 Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_32_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_36_1.png b/v2.16.2/assets/examples/Autoregressive Models_36_1.png new file mode 100644 index 000000000..047100331 Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_36_1.png differ diff --git a/v2.16.2/assets/examples/Autoregressive Models_6_1.png b/v2.16.2/assets/examples/Autoregressive Models_6_1.png new file mode 100644 index 000000000..309eadff5 Binary files /dev/null and b/v2.16.2/assets/examples/Autoregressive Models_6_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_10_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_10_1.png new file mode 100644 index 000000000..4ecb12eef Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_10_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_12_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_12_1.png new file mode 100644 index 000000000..21f2cf9b8 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_12_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_14_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_14_1.png new file mode 100644 index 000000000..d35fb5850 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_14_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_15_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_15_1.png new file mode 100644 index 000000000..8068d76e2 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_15_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_16_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_16_1.png new file mode 100644 index 000000000..2dd3fcb12 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_16_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_17_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_17_1.png new file mode 100644 index 000000000..ddcc56f62 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_17_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_18_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_18_1.png new file mode 100644 index 000000000..89f29aa9d Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_18_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_21_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_21_1.png new file mode 100644 index 000000000..157bce417 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_21_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_24_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_24_1.png new file mode 100644 index 000000000..f308e70a3 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_24_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_25_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_25_1.png new file mode 100644 index 000000000..da8387995 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_25_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_26_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_26_1.png new file mode 100644 index 000000000..0b3299f1c Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_26_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_27_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_27_1.png new file mode 100644 index 000000000..dc2785db5 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_27_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_34_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_34_1.png new file mode 100644 index 000000000..e935ce86c Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_34_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_40_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_40_1.png new file mode 100644 index 000000000..a7f23a09f Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_40_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_42_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_42_1.png new file mode 100644 index 000000000..3249d9b3c Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_42_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_4_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_4_1.png new file mode 100644 index 000000000..3851d2ea5 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_4_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_51_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_51_1.png new file mode 100644 index 000000000..df1ae996a Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_51_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_54_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_54_1.png new file mode 100644 index 000000000..8da279955 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_54_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_55_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_55_1.png new file mode 100644 index 000000000..ca615bf2c Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_55_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_7_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_7_1.png new file mode 100644 index 000000000..564b04161 Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_7_1.png differ diff --git a/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_8_1.png b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_8_1.png new file mode 100644 index 000000000..b86dc84cd Binary files /dev/null and b/v2.16.2/assets/examples/Bayesian Linear Regression Tutorial_8_1.png differ diff --git a/v2.16.2/assets/examples/Chance Constraints_11_1.png b/v2.16.2/assets/examples/Chance Constraints_11_1.png new file mode 100644 index 000000000..b7b9be536 Binary files /dev/null and b/v2.16.2/assets/examples/Chance Constraints_11_1.png differ diff --git a/v2.16.2/assets/examples/Coin Toss Model_7_1.png b/v2.16.2/assets/examples/Coin Toss Model_7_1.png new file mode 100644 index 000000000..180821d61 Binary files /dev/null and b/v2.16.2/assets/examples/Coin Toss Model_7_1.png differ diff --git a/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png b/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png new file mode 100644 index 000000000..d90df26c0 Binary files /dev/null and b/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_10_1.png differ diff --git a/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png b/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png new file mode 100644 index 000000000..14f524963 Binary files /dev/null and b/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_12_1.png differ diff --git a/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png b/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png new file mode 100644 index 000000000..2e19804fb Binary files /dev/null and b/v2.16.2/assets/examples/Conjugate-Computational Variational Message Passing_4_1.png differ diff --git a/v2.16.2/assets/examples/GP Regression by SSM_10_1.png b/v2.16.2/assets/examples/GP Regression by SSM_10_1.png new file mode 100644 index 000000000..be25d53d3 Binary files /dev/null and b/v2.16.2/assets/examples/GP Regression by SSM_10_1.png differ diff --git a/v2.16.2/assets/examples/GP Regression by SSM_5_1.png b/v2.16.2/assets/examples/GP Regression by SSM_5_1.png new file mode 100644 index 000000000..3246e6256 Binary files /dev/null and b/v2.16.2/assets/examples/GP Regression by SSM_5_1.png differ diff --git a/v2.16.2/assets/examples/Gamma Mixture_10_1.png b/v2.16.2/assets/examples/Gamma Mixture_10_1.png new file mode 100644 index 000000000..bd8ce343b Binary files /dev/null and b/v2.16.2/assets/examples/Gamma Mixture_10_1.png differ diff --git a/v2.16.2/assets/examples/Gaussian Mixture_12_1.png b/v2.16.2/assets/examples/Gaussian Mixture_12_1.png new file mode 100644 index 000000000..fc21b9942 Binary files /dev/null and b/v2.16.2/assets/examples/Gaussian Mixture_12_1.png differ diff --git a/v2.16.2/assets/examples/Gaussian Mixture_4_1.png b/v2.16.2/assets/examples/Gaussian Mixture_4_1.png new file mode 100644 index 000000000..aedf37236 Binary files /dev/null and b/v2.16.2/assets/examples/Gaussian Mixture_4_1.png differ diff --git a/v2.16.2/assets/examples/Gaussian Mixture_7_1.png b/v2.16.2/assets/examples/Gaussian Mixture_7_1.png new file mode 100644 index 000000000..338fe2092 Binary files /dev/null and b/v2.16.2/assets/examples/Gaussian Mixture_7_1.png differ diff --git a/v2.16.2/assets/examples/Gaussian Mixture_9_1.png b/v2.16.2/assets/examples/Gaussian Mixture_9_1.png new file mode 100644 index 000000000..64adeef14 Binary files /dev/null and b/v2.16.2/assets/examples/Gaussian Mixture_9_1.png differ diff --git a/v2.16.2/assets/examples/Global Parameter Optimisation_14_1.png b/v2.16.2/assets/examples/Global Parameter Optimisation_14_1.png new file mode 100644 index 000000000..70f61d1cf Binary files /dev/null and b/v2.16.2/assets/examples/Global Parameter Optimisation_14_1.png differ diff --git a/v2.16.2/assets/examples/Global Parameter Optimisation_18_1.png b/v2.16.2/assets/examples/Global Parameter Optimisation_18_1.png new file mode 100644 index 000000000..eac50a682 Binary files /dev/null and b/v2.16.2/assets/examples/Global Parameter Optimisation_18_1.png differ diff --git a/v2.16.2/assets/examples/Global Parameter Optimisation_22_1.png b/v2.16.2/assets/examples/Global Parameter Optimisation_22_1.png new file mode 100644 index 000000000..c24630442 Binary files /dev/null and b/v2.16.2/assets/examples/Global Parameter Optimisation_22_1.png differ diff --git a/v2.16.2/assets/examples/Global Parameter Optimisation_28_1.png b/v2.16.2/assets/examples/Global Parameter Optimisation_28_1.png new file mode 100644 index 000000000..09970c16b Binary files /dev/null and b/v2.16.2/assets/examples/Global Parameter Optimisation_28_1.png differ diff --git a/v2.16.2/assets/examples/Global Parameter Optimisation_32_1.png b/v2.16.2/assets/examples/Global Parameter Optimisation_32_1.png new file mode 100644 index 000000000..cf55c8da0 Binary files /dev/null and b/v2.16.2/assets/examples/Global Parameter Optimisation_32_1.png differ diff --git a/v2.16.2/assets/examples/Global Parameter Optimisation_35_1.png b/v2.16.2/assets/examples/Global Parameter Optimisation_35_1.png new file mode 100644 index 000000000..fddb20942 Binary files /dev/null and b/v2.16.2/assets/examples/Global Parameter Optimisation_35_1.png differ diff --git a/v2.16.2/assets/examples/Hidden Markov Model_4_1.png b/v2.16.2/assets/examples/Hidden Markov Model_4_1.png new file mode 100644 index 000000000..a15a96215 Binary files /dev/null and b/v2.16.2/assets/examples/Hidden Markov Model_4_1.png differ diff --git a/v2.16.2/assets/examples/Hidden Markov Model_9_1.png b/v2.16.2/assets/examples/Hidden Markov Model_9_1.png new file mode 100644 index 000000000..32d9bbc46 Binary files /dev/null and b/v2.16.2/assets/examples/Hidden Markov Model_9_1.png differ diff --git a/v2.16.2/assets/examples/Hierarchical Gaussian Filter_10_1.png b/v2.16.2/assets/examples/Hierarchical Gaussian Filter_10_1.png new file mode 100644 index 000000000..6a3b9c9dc Binary files /dev/null and b/v2.16.2/assets/examples/Hierarchical Gaussian Filter_10_1.png differ diff --git a/v2.16.2/assets/examples/Hierarchical Gaussian Filter_5_1.png b/v2.16.2/assets/examples/Hierarchical Gaussian Filter_5_1.png new file mode 100644 index 000000000..2d74bff5a Binary files /dev/null and b/v2.16.2/assets/examples/Hierarchical Gaussian Filter_5_1.png differ diff --git a/v2.16.2/assets/examples/Hierarchical Gaussian Filter_9_1.png b/v2.16.2/assets/examples/Hierarchical Gaussian Filter_9_1.png new file mode 100644 index 000000000..9821f6bc9 Binary files /dev/null and b/v2.16.2/assets/examples/Hierarchical Gaussian Filter_9_1.png differ diff --git a/v2.16.2/assets/examples/Infinite Data Stream_11_1.png b/v2.16.2/assets/examples/Infinite Data Stream_11_1.png new file mode 100644 index 000000000..b089a8898 Binary files /dev/null and b/v2.16.2/assets/examples/Infinite Data Stream_11_1.png differ diff --git a/v2.16.2/assets/examples/Invertible Neural Network Tutorial_10_1.png b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_10_1.png new file mode 100644 index 000000000..009e76bec Binary files /dev/null and b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_10_1.png differ diff --git a/v2.16.2/assets/examples/Invertible Neural Network Tutorial_14_1.png b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_14_1.png new file mode 100644 index 000000000..95edfacc0 Binary files /dev/null and b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_14_1.png differ diff --git a/v2.16.2/assets/examples/Invertible Neural Network Tutorial_15_1.png b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_15_1.png new file mode 100644 index 000000000..ab077a912 Binary files /dev/null and b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_15_1.png differ diff --git a/v2.16.2/assets/examples/Invertible Neural Network Tutorial_17_1.png b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_17_1.png new file mode 100644 index 000000000..201b882c0 Binary files /dev/null and b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_17_1.png differ diff --git a/v2.16.2/assets/examples/Invertible Neural Network Tutorial_23_1.png b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_23_1.png new file mode 100644 index 000000000..a639d283d Binary files /dev/null and b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_23_1.png differ diff --git a/v2.16.2/assets/examples/Invertible Neural Network Tutorial_24_1.png b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_24_1.png new file mode 100644 index 000000000..b38e5ab4e Binary files /dev/null and b/v2.16.2/assets/examples/Invertible Neural Network Tutorial_24_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_10_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_10_1.png new file mode 100644 index 000000000..404cd2073 Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_10_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_15_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_15_1.png new file mode 100644 index 000000000..387f83e00 Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_15_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_20_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_20_1.png new file mode 100644 index 000000000..0332168c8 Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_20_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_23_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_23_1.png new file mode 100644 index 000000000..3997d6305 Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_23_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_25_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_25_1.png new file mode 100644 index 000000000..baae896e0 Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_25_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_30_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_30_1.png new file mode 100644 index 000000000..0ca63d89e Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_30_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_33_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_33_1.png new file mode 100644 index 000000000..230f9e497 Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_33_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_39_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_39_1.png new file mode 100644 index 000000000..50f0fbc5f Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_39_1.png differ diff --git a/v2.16.2/assets/examples/Kalman filtering and smoothing_6_1.png b/v2.16.2/assets/examples/Kalman filtering and smoothing_6_1.png new file mode 100644 index 000000000..868c31a7a Binary files /dev/null and b/v2.16.2/assets/examples/Kalman filtering and smoothing_6_1.png differ diff --git a/v2.16.2/assets/examples/Nonlinear Sensor Fusion_12_1.png b/v2.16.2/assets/examples/Nonlinear Sensor Fusion_12_1.png new file mode 100644 index 000000000..b2722f776 Binary files /dev/null and b/v2.16.2/assets/examples/Nonlinear Sensor Fusion_12_1.png differ diff --git a/v2.16.2/assets/examples/Nonlinear Sensor Fusion_17_1.png b/v2.16.2/assets/examples/Nonlinear Sensor Fusion_17_1.png new file mode 100644 index 000000000..4d1e2bd3c Binary files /dev/null and b/v2.16.2/assets/examples/Nonlinear Sensor Fusion_17_1.png differ diff --git a/v2.16.2/assets/examples/Nonlinear Sensor Fusion_4_1.png b/v2.16.2/assets/examples/Nonlinear Sensor Fusion_4_1.png new file mode 100644 index 000000000..6be9531bf Binary files /dev/null and b/v2.16.2/assets/examples/Nonlinear Sensor Fusion_4_1.png differ diff --git a/v2.16.2/assets/examples/Predicting Bike Rental Demand_17_1.png b/v2.16.2/assets/examples/Predicting Bike Rental Demand_17_1.png new file mode 100644 index 000000000..49ebabbfb Binary files /dev/null and b/v2.16.2/assets/examples/Predicting Bike Rental Demand_17_1.png differ diff --git a/v2.16.2/assets/examples/Predicting Bike Rental Demand_18_1.png b/v2.16.2/assets/examples/Predicting Bike Rental Demand_18_1.png new file mode 100644 index 000000000..ed7f08607 Binary files /dev/null and b/v2.16.2/assets/examples/Predicting Bike Rental Demand_18_1.png differ diff --git a/v2.16.2/assets/examples/Probit Model (EP)_6_1.png b/v2.16.2/assets/examples/Probit Model (EP)_6_1.png new file mode 100644 index 000000000..b9b15d04b Binary files /dev/null and b/v2.16.2/assets/examples/Probit Model (EP)_6_1.png differ diff --git a/v2.16.2/assets/examples/Probit Model (EP)_9_1.png b/v2.16.2/assets/examples/Probit Model (EP)_9_1.png new file mode 100644 index 000000000..baf1f1c80 Binary files /dev/null and b/v2.16.2/assets/examples/Probit Model (EP)_9_1.png differ diff --git a/v2.16.2/assets/examples/RTS vs BIFM Smoothing_11_1.png b/v2.16.2/assets/examples/RTS vs BIFM Smoothing_11_1.png new file mode 100644 index 000000000..8e89768c7 Binary files /dev/null and b/v2.16.2/assets/examples/RTS vs BIFM Smoothing_11_1.png differ diff --git a/v2.16.2/assets/examples/RTS vs BIFM Smoothing_12_1.png b/v2.16.2/assets/examples/RTS vs BIFM Smoothing_12_1.png new file mode 100644 index 000000000..89297743e Binary files /dev/null and b/v2.16.2/assets/examples/RTS vs BIFM Smoothing_12_1.png differ diff --git a/v2.16.2/assets/examples/RTS vs BIFM Smoothing_5_1.png b/v2.16.2/assets/examples/RTS vs BIFM Smoothing_5_1.png new file mode 100644 index 000000000..a62eee61d Binary files /dev/null and b/v2.16.2/assets/examples/RTS vs BIFM Smoothing_5_1.png differ diff --git a/v2.16.2/assets/examples/Simple Nonlinear Node_14_1.png b/v2.16.2/assets/examples/Simple Nonlinear Node_14_1.png new file mode 100644 index 000000000..3ef40817f Binary files /dev/null and b/v2.16.2/assets/examples/Simple Nonlinear Node_14_1.png differ diff --git a/v2.16.2/assets/examples/Tiny Benchmark_11_1.png b/v2.16.2/assets/examples/Tiny Benchmark_11_1.png new file mode 100644 index 000000000..97ee402ca Binary files /dev/null and b/v2.16.2/assets/examples/Tiny Benchmark_11_1.png differ diff --git a/v2.16.2/assets/examples/Tiny Benchmark_7_1.png b/v2.16.2/assets/examples/Tiny Benchmark_7_1.png new file mode 100644 index 000000000..36c08b460 Binary files /dev/null and b/v2.16.2/assets/examples/Tiny Benchmark_7_1.png differ diff --git a/v2.16.2/assets/examples/Universal Mixtures_10_1.png b/v2.16.2/assets/examples/Universal Mixtures_10_1.png new file mode 100644 index 000000000..fd23f884a Binary files /dev/null and b/v2.16.2/assets/examples/Universal Mixtures_10_1.png differ diff --git a/v2.16.2/assets/examples/Universal Mixtures_13_1.png b/v2.16.2/assets/examples/Universal Mixtures_13_1.png new file mode 100644 index 000000000..cf2c5244c Binary files /dev/null and b/v2.16.2/assets/examples/Universal Mixtures_13_1.png differ diff --git a/v2.16.2/assets/examples/Universal Mixtures_3_1.png b/v2.16.2/assets/examples/Universal Mixtures_3_1.png new file mode 100644 index 000000000..cec0904cc Binary files /dev/null and b/v2.16.2/assets/examples/Universal Mixtures_3_1.png differ diff --git a/v2.16.2/assets/examples/Universal Mixtures_9_1.png b/v2.16.2/assets/examples/Universal Mixtures_9_1.png new file mode 100644 index 000000000..a6c946c8b Binary files /dev/null and b/v2.16.2/assets/examples/Universal Mixtures_9_1.png differ diff --git a/v2.16.2/assets/examples/pics/ai-mountain-car-ai.gif b/v2.16.2/assets/examples/pics/ai-mountain-car-ai.gif new file mode 100644 index 000000000..87f6cc774 Binary files /dev/null and b/v2.16.2/assets/examples/pics/ai-mountain-car-ai.gif differ diff --git a/v2.16.2/assets/examples/pics/ai-mountain-car-naive.gif b/v2.16.2/assets/examples/pics/ai-mountain-car-naive.gif new file mode 100644 index 000000000..80fdf4e1c Binary files /dev/null and b/v2.16.2/assets/examples/pics/ai-mountain-car-naive.gif differ diff --git a/v2.16.2/assets/examples/pics/hblr-matrix-completion.jpeg b/v2.16.2/assets/examples/pics/hblr-matrix-completion.jpeg new file mode 100644 index 000000000..be0f78e1c Binary files /dev/null and b/v2.16.2/assets/examples/pics/hblr-matrix-completion.jpeg differ diff --git a/v2.16.2/assets/examples/pics/infinite-data-stream-inference.gif b/v2.16.2/assets/examples/pics/infinite-data-stream-inference.gif new file mode 100644 index 000000000..21fd053a5 Binary files /dev/null and b/v2.16.2/assets/examples/pics/infinite-data-stream-inference.gif differ diff --git a/v2.16.2/assets/examples/pics/infinite-data-stream.gif b/v2.16.2/assets/examples/pics/infinite-data-stream.gif new file mode 100644 index 000000000..035aeaa0d Binary files /dev/null and b/v2.16.2/assets/examples/pics/infinite-data-stream.gif differ diff --git a/v2.16.2/assets/examples/pics/online-coin-bias-inference.gif b/v2.16.2/assets/examples/pics/online-coin-bias-inference.gif new file mode 100644 index 000000000..1cb791bc1 Binary files /dev/null and b/v2.16.2/assets/examples/pics/online-coin-bias-inference.gif differ diff --git a/v2.16.2/assets/examples/pics/pipeline.png b/v2.16.2/assets/examples/pics/pipeline.png new file mode 100644 index 000000000..d8302e166 Binary files /dev/null and b/v2.16.2/assets/examples/pics/pipeline.png differ diff --git a/v2.16.2/assets/examples/pics/posterior.png b/v2.16.2/assets/examples/pics/posterior.png new file mode 100644 index 000000000..4fa49edff Binary files /dev/null and b/v2.16.2/assets/examples/pics/posterior.png differ diff --git a/v2.16.2/assets/examples/pics/rts_bifm_benchmark.png b/v2.16.2/assets/examples/pics/rts_bifm_benchmark.png new file mode 100644 index 000000000..51a066062 Binary files /dev/null and b/v2.16.2/assets/examples/pics/rts_bifm_benchmark.png differ diff --git a/v2.16.2/assets/examples/pics/sp.png b/v2.16.2/assets/examples/pics/sp.png new file mode 100644 index 000000000..dedc65431 Binary files /dev/null and b/v2.16.2/assets/examples/pics/sp.png differ diff --git a/v2.16.2/assets/examples/pics/vmp.png b/v2.16.2/assets/examples/pics/vmp.png new file mode 100644 index 000000000..0561f27e3 Binary files /dev/null and b/v2.16.2/assets/examples/pics/vmp.png differ diff --git a/v2.16.2/assets/header.css b/v2.16.2/assets/header.css new file mode 100644 index 000000000..155b10a3b --- /dev/null +++ b/v2.16.2/assets/header.css @@ -0,0 +1,138 @@ + +@media all and (max-width: 560px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar { + min-height: 1rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + min-height: 1rem !important; + margin-left: 0.5rem !important; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: visible !important; + display: block !important; + margin: 0.5rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + visibility: hidden; + display: none; + } + + header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a { + visibility: hidden; + display: none; + } + + html:not(.theme--documenter-dark) body #documenter .docs-main { + margin-top: 2rem !important; + } +} + +@media all and (max-width: 1055px) and (min-width: 561px){ + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 0rem; + } + + header.navigation div.container nav.navbar ul.navbar-nav { + width: 80% !important; + } +} + +@media all and (min-width: 1056px) { + header.navigation { + position: fixed !important; + left:0; + top: 0; + width: 100%; + } + + header.navigation div.container { + margin-left: 18rem; + } + +} + +html.theme--documenter-dark header.navigation { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container { + border-bottom: 1px solid #5e6d6f; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar { + background-color: #1f2424 !important; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: white; + transition: color 100ms; +} + +html.theme--documenter-dark header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +html header.navigation { + background-color: white !important; +} + +html header.navigation div.container { + border-bottom: 1px solid #dbdbdb; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link { + color: #222; + transition: color 100ms; +} + +html header.navigation div.container nav.navbar ul.navbar-nav li.nav-item a.nav-link:hover { + color: #0aa8a7 +} + +header.navigation { + z-index: 3; +} + +header.navigation div.container nav.navbar ul.navbar-nav { + margin-left: 4rem; + min-height: 3.25rem; + width: 70%; + display: flex; + align-self: auto; + flex-direction: row; + justify-content: space-around; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.nav-item { + align-self: stretch; + align-content: space-around; + justify-content: center; + display: flex; + flex-direction: column; +} + +header.navigation div.container nav.navbar ul.navbar-nav li.small-item { + visibility: hidden; + display: none; +} \ No newline at end of file diff --git a/v2.16.2/assets/header.js b/v2.16.2/assets/header.js new file mode 100644 index 000000000..7f15cae83 --- /dev/null +++ b/v2.16.2/assets/header.js @@ -0,0 +1,97 @@ + +// We add a simple `onload` hook to inject the custom header for our `HTML`-generated pages +window.onload = function() { + //
+ const header = document.createElement('header') + header.classList.add("navigation") + header.appendChild((() => { + const container = document.createElement('div') + container.classList.add('container') + container.appendChild((() => { + const nav = document.createElement('nav') + nav.classList.add("navbar") + + nav.appendChild((() => { + const ul = document.createElement("ul") + ul.classList.add("navbar-nav") + + ul.appendChild((() => { + const smalllink = document.createElement('li') + smalllink.classList.add('small-item') + smalllink.appendChild((() => { + const a = document.createElement('a') + a.classList.add("nav-link") + a.href = 'http://www.rxinfer.ml' + a.innerHTML = 'RxInfer.jl' + a.title = 'RxInfer.jl' + return a + })()) + return smalllink + })()) + + const items = [ + { title: "Home", link: "http://www.rxinfer.ml", icon: [ "fas", "fa-diagram-project" ] }, + { title: "Get Started", link: "https://reactivebayes.github.io/RxInfer.jl/stable/manuals/getting-started/" }, + { title: "Documentation", link: "https://reactivebayes.github.io/RxInfer.jl/stable/" }, + { title: "Examples", link: "https://reactivebayes.github.io/RxInfer.jl/stable/examples/overview/" }, + { title: "Papers", link: "https://reactivebayes.github.io/publication/" }, + { title: "Team", link: "https://reactivebayes.github.io/team/" }, + // { title: "Contact", link: "http://www.rxinfer.ml/contact/" }, the redirect is broken for now + { title: "GitHub", link: "https://github.com/reactivebayes/RxInfer.jl", icon: [ "fab", "fa-github" ] }, + ] + + items.forEach((item) => { + ul.appendChild(((item) => { + const li = document.createElement("li") + li.classList.add("nav-item") + li.appendChild((() => { + const a = document.createElement("a") + + if (item.icon !== undefined) { + a.appendChild((() => { + const i = document.createElement("i") + i.classList.add(...(item.icon)) + return i + })()) + } + + a.classList.add("nav-link") + a.href = item.link + a.title = item.title + + a.appendChild((() => { + const span = document.createElement("span") + span.innerHTML = ` ${item.title}` + return span + })()) + + return a + })()) + return li + })(item)) + }) + return ul + })()) + return nav + })()) + return container + })()) + + const documenterTarget = document.querySelector('#documenter'); + + documenterTarget.parentNode.insertBefore(header, documenterTarget); + + // Edit broken links in the examples, see issue #70 + const editOnGithubLinkTarget = document.querySelector('.docs-edit-link'); + + if (editOnGithubLinkTarget) { + const link = editOnGithubLinkTarget.href; + if (link.includes('docs/src/examples')) { + const fixedLink = link.replace('docs/src/', '').replace('.md', '.ipynb'); + editOnGithubLinkTarget.href = fixedLink; + console.log('Fixed link for the example: ', fixedLink) + } + } + +} + diff --git a/v2.16.2/assets/img/bp-message.svg b/v2.16.2/assets/img/bp-message.svg new file mode 100644 index 000000000..259b70803 --- /dev/null +++ b/v2.16.2/assets/img/bp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.16.2/assets/img/coin-flip.png b/v2.16.2/assets/img/coin-flip.png new file mode 100644 index 000000000..2ed0f04c0 Binary files /dev/null and b/v2.16.2/assets/img/coin-flip.png differ diff --git a/v2.16.2/assets/img/coin-flip.svg b/v2.16.2/assets/img/coin-flip.svg new file mode 100644 index 000000000..a85960c12 --- /dev/null +++ b/v2.16.2/assets/img/coin-flip.svg @@ -0,0 +1,794 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/assets/img/debugging_graph.png b/v2.16.2/assets/img/debugging_graph.png new file mode 100644 index 000000000..b97ef1a06 Binary files /dev/null and b/v2.16.2/assets/img/debugging_graph.png differ diff --git a/v2.16.2/assets/img/debugging_messages.png b/v2.16.2/assets/img/debugging_messages.png new file mode 100644 index 000000000..8ec84e778 Binary files /dev/null and b/v2.16.2/assets/img/debugging_messages.png differ diff --git a/v2.16.2/assets/img/linear_regresion_model.png b/v2.16.2/assets/img/linear_regresion_model.png new file mode 100644 index 000000000..bb4e34422 Binary files /dev/null and b/v2.16.2/assets/img/linear_regresion_model.png differ diff --git a/v2.16.2/assets/img/release_comment.png b/v2.16.2/assets/img/release_comment.png new file mode 100644 index 000000000..743fe9614 Binary files /dev/null and b/v2.16.2/assets/img/release_comment.png differ diff --git a/v2.16.2/assets/img/vmp-message.svg b/v2.16.2/assets/img/vmp-message.svg new file mode 100644 index 000000000..475cd7f49 --- /dev/null +++ b/v2.16.2/assets/img/vmp-message.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v2.16.2/assets/logo-dark.svg b/v2.16.2/assets/logo-dark.svg new file mode 100644 index 000000000..63b4f65fa --- /dev/null +++ b/v2.16.2/assets/logo-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + diff --git a/v2.16.2/assets/logo.svg b/v2.16.2/assets/logo.svg new file mode 100644 index 000000000..b799e5beb --- /dev/null +++ b/v2.16.2/assets/logo.svg @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/v2.16.2/assets/theme.css b/v2.16.2/assets/theme.css new file mode 100644 index 000000000..1b060cdef --- /dev/null +++ b/v2.16.2/assets/theme.css @@ -0,0 +1,27 @@ +html body #documenter .docs-main { + margin-top: 4rem; +} + +html body #documenter .docs-sidebar.visible { + margin-top: 0px !important; +} + +html div.light-biglogo { + display: block; +} + +html.theme--documenter-dark div.light-biglogo { + display: none; +} + +html div.dark-biglogo { + display: none; +} + +html.theme--documenter-dark div.dark-biglogo { + display: block; +} + +#documenter .docs-main article.content img { + width: 100%; +} diff --git a/v2.16.2/assets/themes/documenter-dark.css b/v2.16.2/assets/themes/documenter-dark.css new file mode 100644 index 000000000..9f5449f4b --- /dev/null +++ b/v2.16.2/assets/themes/documenter-dark.css @@ -0,0 +1,7 @@ +html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:.4em;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus,html.theme--documenter-dark .pagination-ellipsis:focus,html.theme--documenter-dark .file-cta:focus,html.theme--documenter-dark .file-name:focus,html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .button:focus,html.theme--documenter-dark .is-focused.pagination-previous,html.theme--documenter-dark .is-focused.pagination-next,html.theme--documenter-dark .is-focused.pagination-link,html.theme--documenter-dark .is-focused.pagination-ellipsis,html.theme--documenter-dark .is-focused.file-cta,html.theme--documenter-dark .is-focused.file-name,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-focused.button,html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active,html.theme--documenter-dark .pagination-ellipsis:active,html.theme--documenter-dark .file-cta:active,html.theme--documenter-dark .file-name:active,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .button:active,html.theme--documenter-dark .is-active.pagination-previous,html.theme--documenter-dark .is-active.pagination-next,html.theme--documenter-dark .is-active.pagination-link,html.theme--documenter-dark .is-active.pagination-ellipsis,html.theme--documenter-dark .is-active.file-cta,html.theme--documenter-dark .is-active.file-name,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .is-active.button{outline:none}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-ellipsis[disabled],html.theme--documenter-dark .file-cta[disabled],html.theme--documenter-dark .file-name[disabled],html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark fieldset[disabled] .pagination-previous,fieldset[disabled] html.theme--documenter-dark .pagination-next,html.theme--documenter-dark fieldset[disabled] .pagination-next,fieldset[disabled] html.theme--documenter-dark .pagination-link,html.theme--documenter-dark fieldset[disabled] .pagination-link,fieldset[disabled] html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark fieldset[disabled] .pagination-ellipsis,fieldset[disabled] html.theme--documenter-dark .file-cta,html.theme--documenter-dark fieldset[disabled] .file-cta,fieldset[disabled] html.theme--documenter-dark .file-name,html.theme--documenter-dark fieldset[disabled] .file-name,fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark fieldset[disabled] .select select,html.theme--documenter-dark .select fieldset[disabled] select,html.theme--documenter-dark fieldset[disabled] .textarea,html.theme--documenter-dark fieldset[disabled] .input,html.theme--documenter-dark fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] html.theme--documenter-dark .button,html.theme--documenter-dark fieldset[disabled] .button{cursor:not-allowed}html.theme--documenter-dark .tabs,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .breadcrumb,html.theme--documenter-dark .file,html.theme--documenter-dark .button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after,html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}html.theme--documenter-dark .admonition:not(:last-child),html.theme--documenter-dark .tabs:not(:last-child),html.theme--documenter-dark .pagination:not(:last-child),html.theme--documenter-dark .message:not(:last-child),html.theme--documenter-dark .level:not(:last-child),html.theme--documenter-dark .breadcrumb:not(:last-child),html.theme--documenter-dark .block:not(:last-child),html.theme--documenter-dark .title:not(:last-child),html.theme--documenter-dark .subtitle:not(:last-child),html.theme--documenter-dark .table-container:not(:last-child),html.theme--documenter-dark .table:not(:last-child),html.theme--documenter-dark .progress:not(:last-child),html.theme--documenter-dark .notification:not(:last-child),html.theme--documenter-dark .content:not(:last-child),html.theme--documenter-dark .box:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .modal-close,html.theme--documenter-dark .delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before,html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .modal-close::before,html.theme--documenter-dark .delete::before{height:2px;width:50%}html.theme--documenter-dark .modal-close::after,html.theme--documenter-dark .delete::after{height:50%;width:2px}html.theme--documenter-dark .modal-close:hover,html.theme--documenter-dark .delete:hover,html.theme--documenter-dark .modal-close:focus,html.theme--documenter-dark .delete:focus{background-color:rgba(10,10,10,0.3)}html.theme--documenter-dark .modal-close:active,html.theme--documenter-dark .delete:active{background-color:rgba(10,10,10,0.4)}html.theme--documenter-dark .is-small.modal-close,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.modal-close,html.theme--documenter-dark .is-small.delete,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}html.theme--documenter-dark .is-medium.modal-close,html.theme--documenter-dark .is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}html.theme--documenter-dark .is-large.modal-close,html.theme--documenter-dark .is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}html.theme--documenter-dark .control.is-loading::after,html.theme--documenter-dark .select.is-loading::after,html.theme--documenter-dark .loader,html.theme--documenter-dark .button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdee0;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}html.theme--documenter-dark .hero-video,html.theme--documenter-dark .modal-background,html.theme--documenter-dark .modal,html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}html.theme--documenter-dark .navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#ecf0f1 !important}a.has-text-light:hover,a.has-text-light:focus{color:#cfd9db !important}.has-background-light{background-color:#ecf0f1 !important}.has-text-dark{color:#282f2f !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#111414 !important}.has-background-dark{background-color:#282f2f !important}.has-text-primary{color:#375a7f !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#28415b !important}.has-background-primary{background-color:#375a7f !important}.has-text-primary-light{color:#f1f5f9 !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#cddbe9 !important}.has-background-primary-light{background-color:#f1f5f9 !important}.has-text-primary-dark{color:#4d7eb2 !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#7198c1 !important}.has-background-primary-dark{background-color:#4d7eb2 !important}.has-text-link{color:#1abc9c !important}a.has-text-link:hover,a.has-text-link:focus{color:#148f77 !important}.has-background-link{background-color:#1abc9c !important}.has-text-link-light{color:#edfdf9 !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c0f6ec !important}.has-background-link-light{background-color:#edfdf9 !important}.has-text-link-dark{color:#15987e !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#1bc5a4 !important}.has-background-link-dark{background-color:#15987e !important}.has-text-info{color:#024c7d !important}a.has-text-info:hover,a.has-text-info:focus{color:#012d4b !important}.has-background-info{background-color:#024c7d !important}.has-text-info-light{color:#ebf7ff !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#b9e2fe !important}.has-background-info-light{background-color:#ebf7ff !important}.has-text-info-dark{color:#0e9dfb !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#40b1fc !important}.has-background-info-dark{background-color:#0e9dfb !important}.has-text-success{color:#008438 !important}a.has-text-success:hover,a.has-text-success:focus{color:#005122 !important}.has-background-success{background-color:#008438 !important}.has-text-success-light{color:#ebfff3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#b8ffd6 !important}.has-background-success-light{background-color:#ebfff3 !important}.has-text-success-dark{color:#00eb64 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#1fff7e !important}.has-background-success-dark{background-color:#00eb64 !important}.has-text-warning{color:#ad8100 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#7a5b00 !important}.has-background-warning{background-color:#ad8100 !important}.has-text-warning-light{color:#fffaeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#ffedb8 !important}.has-background-warning-light{background-color:#fffaeb !important}.has-text-warning-dark{color:#d19c00 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#ffbf05 !important}.has-background-warning-dark{background-color:#d19c00 !important}.has-text-danger{color:#9e1b0d !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#6f1309 !important}.has-background-danger{background-color:#9e1b0d !important}.has-text-danger-light{color:#fdeeec !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#fac3bd !important}.has-background-danger-light{background-color:#fdeeec !important}.has-text-danger-dark{color:#ec311d !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#f05c4c !important}.has-background-danger-dark{background-color:#ec311d !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#282f2f !important}.has-background-grey-darker{background-color:#282f2f !important}.has-text-grey-dark{color:#343c3d !important}.has-background-grey-dark{background-color:#343c3d !important}.has-text-grey{color:#5e6d6f !important}.has-background-grey{background-color:#5e6d6f !important}.has-text-grey-light{color:#8c9b9d !important}.has-background-grey-light{background-color:#8c9b9d !important}.has-text-grey-lighter{color:#dbdee0 !important}.has-background-grey-lighter{background-color:#dbdee0 !important}.has-text-white-ter{color:#ecf0f1 !important}.has-background-white-ter{background-color:#ecf0f1 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}html.theme--documenter-dark{/*! + Theme: a11y-dark + Author: @ericwbailey + Maintainer: @ericwbailey + + Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css +*/}html.theme--documenter-dark html{background-color:#1f2424;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark article,html.theme--documenter-dark aside,html.theme--documenter-dark figure,html.theme--documenter-dark footer,html.theme--documenter-dark header,html.theme--documenter-dark hgroup,html.theme--documenter-dark section{display:block}html.theme--documenter-dark body,html.theme--documenter-dark button,html.theme--documenter-dark input,html.theme--documenter-dark optgroup,html.theme--documenter-dark select,html.theme--documenter-dark textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}html.theme--documenter-dark code,html.theme--documenter-dark pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark body{color:#fff;font-size:1em;font-weight:400;line-height:1.5}html.theme--documenter-dark a{color:#1abc9c;cursor:pointer;text-decoration:none}html.theme--documenter-dark a strong{color:currentColor}html.theme--documenter-dark a:hover{color:#1dd2af}html.theme--documenter-dark code{background-color:rgba(255,255,255,0.05);color:#ececec;font-size:.875em;font-weight:normal;padding:.1em}html.theme--documenter-dark hr{background-color:#282f2f;border:none;display:block;height:2px;margin:1.5rem 0}html.theme--documenter-dark img{height:auto;max-width:100%}html.theme--documenter-dark input[type="checkbox"],html.theme--documenter-dark input[type="radio"]{vertical-align:baseline}html.theme--documenter-dark small{font-size:.875em}html.theme--documenter-dark span{font-style:inherit;font-weight:inherit}html.theme--documenter-dark strong{color:#f2f2f2;font-weight:700}html.theme--documenter-dark fieldset{border:none}html.theme--documenter-dark pre{-webkit-overflow-scrolling:touch;background-color:#282f2f;color:#fff;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}html.theme--documenter-dark pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}html.theme--documenter-dark table td,html.theme--documenter-dark table th{vertical-align:top}html.theme--documenter-dark table td:not([align]),html.theme--documenter-dark table th:not([align]){text-align:inherit}html.theme--documenter-dark table th{color:#f2f2f2}html.theme--documenter-dark .box{background-color:#343c3d;border-radius:8px;box-shadow:none;color:#fff;display:block;padding:1.25rem}html.theme--documenter-dark a.box:hover,html.theme--documenter-dark a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #1abc9c}html.theme--documenter-dark a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #1abc9c}html.theme--documenter-dark .button{background-color:#282f2f;border-color:#4c5759;border-width:1px;color:#375a7f;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}html.theme--documenter-dark .button strong{color:inherit}html.theme--documenter-dark .button .icon,html.theme--documenter-dark .button .icon.is-small,html.theme--documenter-dark .button #documenter .docs-sidebar form.docs-search>input.icon,html.theme--documenter-dark #documenter .docs-sidebar .button form.docs-search>input.icon,html.theme--documenter-dark .button .icon.is-medium,html.theme--documenter-dark .button .icon.is-large{height:1.5em;width:1.5em}html.theme--documenter-dark .button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}html.theme--documenter-dark .button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}html.theme--documenter-dark .button:hover,html.theme--documenter-dark .button.is-hovered{border-color:#8c9b9d;color:#f2f2f2}html.theme--documenter-dark .button:focus,html.theme--documenter-dark .button.is-focused{border-color:#8c9b9d;color:#17a689}html.theme--documenter-dark .button:focus:not(:active),html.theme--documenter-dark .button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button:active,html.theme--documenter-dark .button.is-active{border-color:#343c3d;color:#f2f2f2}html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;color:#fff;text-decoration:underline}html.theme--documenter-dark .button.is-text:hover,html.theme--documenter-dark .button.is-text.is-hovered,html.theme--documenter-dark .button.is-text:focus,html.theme--documenter-dark .button.is-text.is-focused{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .button.is-text:active,html.theme--documenter-dark .button.is-text.is-active{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .button.is-text[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}html.theme--documenter-dark .button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#1abc9c;text-decoration:none}html.theme--documenter-dark .button.is-ghost:hover,html.theme--documenter-dark .button.is-ghost.is-hovered{color:#1abc9c;text-decoration:underline}html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:hover,html.theme--documenter-dark .button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus,html.theme--documenter-dark .button.is-white.is-focused{border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white:focus:not(:active),html.theme--documenter-dark .button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .button.is-white[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-hovered{background-color:#000}html.theme--documenter-dark .button.is-white.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-white.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-white.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:hover,html.theme--documenter-dark .button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus,html.theme--documenter-dark .button.is-black.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black:focus:not(:active),html.theme--documenter-dark .button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-black[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-black.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-black.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}html.theme--documenter-dark .button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:hover,html.theme--documenter-dark .button.is-light.is-hovered{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus,html.theme--documenter-dark .button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light:focus:not(:active),html.theme--documenter-dark .button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light.is-active{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light{background-color:#ecf0f1;border-color:#ecf0f1;box-shadow:none}html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-outlined.is-focused{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}html.theme--documenter-dark .button.is-light.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-outlined{background-color:transparent;border-color:#ecf0f1;box-shadow:none;color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ecf0f1 #ecf0f1 !important}html.theme--documenter-dark .button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .button.is-dark,html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover,html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark:focus:not(:active),html.theme--documenter-dark .content kbd.button:focus:not(:active),html.theme--documenter-dark .button.is-dark.is-focused:not(:active),html.theme--documenter-dark .content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-dark[disabled],html.theme--documenter-dark .content kbd.button[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark,fieldset[disabled] html.theme--documenter-dark .content kbd.button{background-color:#282f2f;border-color:#282f2f;box-shadow:none}html.theme--documenter-dark .button.is-dark.is-inverted,html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted:hover,html.theme--documenter-dark .content kbd.button.is-inverted:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-dark.is-inverted[disabled],html.theme--documenter-dark .content kbd.button.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-loading::after,html.theme--documenter-dark .content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined,html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-outlined.is-focused{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-dark.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-outlined{background-color:transparent;border-color:#282f2f;box-shadow:none;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:hover,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined:focus,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#282f2f}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #282f2f #282f2f !important}html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined[disabled],html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-dark.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary:focus:not(:active),html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus:not(:active),html.theme--documenter-dark .button.is-primary.is-focused:not(:active),html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-primary[disabled],html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;box-shadow:none}html.theme--documenter-dark .button.is-primary.is-inverted,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}html.theme--documenter-dark .button.is-primary.is-inverted[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-primary.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#375a7f;box-shadow:none;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:hover,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined:focus,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#375a7f}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #375a7f #375a7f !important}html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined[disabled],html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-primary.is-inverted.is-outlined,fieldset[disabled] html.theme--documenter-dark .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:hover,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:hover,html.theme--documenter-dark .button.is-primary.is-light.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e8eef5;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-primary.is-light:active,html.theme--documenter-dark .docstring>section>a.button.is-light.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary.is-light.is-active,html.theme--documenter-dark .docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#dfe8f1;border-color:transparent;color:#4d7eb2}html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:hover,html.theme--documenter-dark .button.is-link.is-hovered{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus,html.theme--documenter-dark .button.is-link.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link:focus:not(:active),html.theme--documenter-dark .button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link.is-active{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-link[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link{background-color:#1abc9c;border-color:#1abc9c;box-shadow:none}html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-link.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-outlined.is-focused{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-link.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-outlined{background-color:transparent;border-color:#1abc9c;box-shadow:none;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#1abc9c}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #1abc9c #1abc9c !important}html.theme--documenter-dark .button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:hover,html.theme--documenter-dark .button.is-link.is-light.is-hovered{background-color:#e2fbf6;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-link.is-light:active,html.theme--documenter-dark .button.is-link.is-light.is-active{background-color:#d7f9f3;border-color:transparent;color:#15987e}html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:hover,html.theme--documenter-dark .button.is-info.is-hovered{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus,html.theme--documenter-dark .button.is-info.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info:focus:not(:active),html.theme--documenter-dark .button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info.is-active{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-info[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info{background-color:#024c7d;border-color:#024c7d;box-shadow:none}html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-info.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;color:#024c7d}html.theme--documenter-dark .button.is-info.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-outlined.is-focused{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-info.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-outlined{background-color:transparent;border-color:#024c7d;box-shadow:none;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#024c7d}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #024c7d #024c7d !important}html.theme--documenter-dark .button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:hover,html.theme--documenter-dark .button.is-info.is-light.is-hovered{background-color:#def2fe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-info.is-light:active,html.theme--documenter-dark .button.is-info.is-light.is-active{background-color:#d2edfe;border-color:transparent;color:#0e9dfb}html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:hover,html.theme--documenter-dark .button.is-success.is-hovered{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus,html.theme--documenter-dark .button.is-success.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success:focus:not(:active),html.theme--documenter-dark .button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success.is-active{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-success[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success{background-color:#008438;border-color:#008438;box-shadow:none}html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-success.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;color:#008438}html.theme--documenter-dark .button.is-success.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-outlined.is-focused{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-success.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-outlined{background-color:transparent;border-color:#008438;box-shadow:none;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#008438}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #008438 #008438 !important}html.theme--documenter-dark .button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:hover,html.theme--documenter-dark .button.is-success.is-light.is-hovered{background-color:#deffec;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-success.is-light:active,html.theme--documenter-dark .button.is-success.is-light.is-active{background-color:#d1ffe5;border-color:transparent;color:#00eb64}html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:hover,html.theme--documenter-dark .button.is-warning.is-hovered{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus,html.theme--documenter-dark .button.is-warning.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning:focus:not(:active),html.theme--documenter-dark .button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning.is-active{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-warning[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning{background-color:#ad8100;border-color:#ad8100;box-shadow:none}html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-warning.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-outlined.is-focused{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-warning.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-outlined{background-color:transparent;border-color:#ad8100;box-shadow:none;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-focused{background-color:#fff;color:#ad8100}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ad8100 #ad8100 !important}html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:hover,html.theme--documenter-dark .button.is-warning.is-light.is-hovered{background-color:#fff7de;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-warning.is-light:active,html.theme--documenter-dark .button.is-warning.is-light.is-active{background-color:#fff3d1;border-color:transparent;color:#d19c00}html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:hover,html.theme--documenter-dark .button.is-danger.is-hovered{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus,html.theme--documenter-dark .button.is-danger.is-focused{border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger:focus:not(:active),html.theme--documenter-dark .button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger.is-active{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .button.is-danger[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;box-shadow:none}html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}html.theme--documenter-dark .button.is-danger.is-inverted[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-outlined.is-focused{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}html.theme--documenter-dark .button.is-danger.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-outlined{background-color:transparent;border-color:#9e1b0d;box-shadow:none;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:hover,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-hovered,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined:focus,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#9e1b0d}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:hover::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading:focus::after,html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #9e1b0d #9e1b0d !important}html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] html.theme--documenter-dark .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}html.theme--documenter-dark .button.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:hover,html.theme--documenter-dark .button.is-danger.is-light.is-hovered{background-color:#fce3e0;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-danger.is-light:active,html.theme--documenter-dark .button.is-danger.is-light.is-active{background-color:#fcd8d5;border-color:transparent;color:#ec311d}html.theme--documenter-dark .button.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}html.theme--documenter-dark .button.is-small:not(.is-rounded),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:3px}html.theme--documenter-dark .button.is-normal{font-size:1rem}html.theme--documenter-dark .button.is-medium{font-size:1.25rem}html.theme--documenter-dark .button.is-large{font-size:1.5rem}html.theme--documenter-dark .button[disabled],fieldset[disabled] html.theme--documenter-dark .button{background-color:#8c9b9d;border-color:#5e6d6f;box-shadow:none;opacity:.5}html.theme--documenter-dark .button.is-fullwidth{display:flex;width:100%}html.theme--documenter-dark .button.is-loading{color:transparent !important;pointer-events:none}html.theme--documenter-dark .button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}html.theme--documenter-dark .button.is-static{background-color:#282f2f;border-color:#5e6d6f;color:#dbdee0;box-shadow:none;pointer-events:none}html.theme--documenter-dark .button.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}html.theme--documenter-dark .buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .buttons .button{margin-bottom:0.5rem}html.theme--documenter-dark .buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}html.theme--documenter-dark .buttons:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .buttons:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}html.theme--documenter-dark .buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:3px}html.theme--documenter-dark .buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}html.theme--documenter-dark .buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}html.theme--documenter-dark .buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}html.theme--documenter-dark .buttons.has-addons .button:last-child{margin-right:0}html.theme--documenter-dark .buttons.has-addons .button:hover,html.theme--documenter-dark .buttons.has-addons .button.is-hovered{z-index:2}html.theme--documenter-dark .buttons.has-addons .button:focus,html.theme--documenter-dark .buttons.has-addons .button.is-focused,html.theme--documenter-dark .buttons.has-addons .button:active,html.theme--documenter-dark .buttons.has-addons .button.is-active,html.theme--documenter-dark .buttons.has-addons .button.is-selected{z-index:3}html.theme--documenter-dark .buttons.has-addons .button:focus:hover,html.theme--documenter-dark .buttons.has-addons .button.is-focused:hover,html.theme--documenter-dark .buttons.has-addons .button:active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-active:hover,html.theme--documenter-dark .buttons.has-addons .button.is-selected:hover{z-index:4}html.theme--documenter-dark .buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .buttons.is-centered{justify-content:center}html.theme--documenter-dark .buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}html.theme--documenter-dark .buttons.is-right{justify-content:flex-end}html.theme--documenter-dark .buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .button.is-responsive.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}html.theme--documenter-dark .button.is-responsive,html.theme--documenter-dark .button.is-responsive.is-normal{font-size:.75rem}html.theme--documenter-dark .button.is-responsive.is-medium{font-size:1rem}html.theme--documenter-dark .button.is-responsive.is-large{font-size:1.25rem}}html.theme--documenter-dark .container{flex-grow:1;margin:0 auto;position:relative;width:auto}html.theme--documenter-dark .container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){html.theme--documenter-dark .container{max-width:992px}}@media screen and (max-width: 1215px){html.theme--documenter-dark .container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){html.theme--documenter-dark .container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){html.theme--documenter-dark .container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){html.theme--documenter-dark .container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}html.theme--documenter-dark .content li+li{margin-top:0.25em}html.theme--documenter-dark .content p:not(:last-child),html.theme--documenter-dark .content dl:not(:last-child),html.theme--documenter-dark .content ol:not(:last-child),html.theme--documenter-dark .content ul:not(:last-child),html.theme--documenter-dark .content blockquote:not(:last-child),html.theme--documenter-dark .content pre:not(:last-child),html.theme--documenter-dark .content table:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .content h1,html.theme--documenter-dark .content h2,html.theme--documenter-dark .content h3,html.theme--documenter-dark .content h4,html.theme--documenter-dark .content h5,html.theme--documenter-dark .content h6{color:#f2f2f2;font-weight:600;line-height:1.125}html.theme--documenter-dark .content h1{font-size:2em;margin-bottom:0.5em}html.theme--documenter-dark .content h1:not(:first-child){margin-top:1em}html.theme--documenter-dark .content h2{font-size:1.75em;margin-bottom:0.5714em}html.theme--documenter-dark .content h2:not(:first-child){margin-top:1.1428em}html.theme--documenter-dark .content h3{font-size:1.5em;margin-bottom:0.6666em}html.theme--documenter-dark .content h3:not(:first-child){margin-top:1.3333em}html.theme--documenter-dark .content h4{font-size:1.25em;margin-bottom:0.8em}html.theme--documenter-dark .content h5{font-size:1.125em;margin-bottom:0.8888em}html.theme--documenter-dark .content h6{font-size:1em;margin-bottom:1em}html.theme--documenter-dark .content blockquote{background-color:#282f2f;border-left:5px solid #5e6d6f;padding:1.25em 1.5em}html.theme--documenter-dark .content ol{list-style-position:outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ol:not([type]){list-style-type:decimal}html.theme--documenter-dark .content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}html.theme--documenter-dark .content ol.is-lower-roman:not([type]){list-style-type:lower-roman}html.theme--documenter-dark .content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}html.theme--documenter-dark .content ol.is-upper-roman:not([type]){list-style-type:upper-roman}html.theme--documenter-dark .content ul{list-style:disc outside;margin-left:2em;margin-top:1em}html.theme--documenter-dark .content ul ul{list-style-type:circle;margin-top:0.5em}html.theme--documenter-dark .content ul ul ul{list-style-type:square}html.theme--documenter-dark .content dd{margin-left:2em}html.theme--documenter-dark .content figure{margin-left:2em;margin-right:2em;text-align:center}html.theme--documenter-dark .content figure:not(:first-child){margin-top:2em}html.theme--documenter-dark .content figure:not(:last-child){margin-bottom:2em}html.theme--documenter-dark .content figure img{display:inline-block}html.theme--documenter-dark .content figure figcaption{font-style:italic}html.theme--documenter-dark .content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}html.theme--documenter-dark .content sup,html.theme--documenter-dark .content sub{font-size:75%}html.theme--documenter-dark .content table{width:100%}html.theme--documenter-dark .content table td,html.theme--documenter-dark .content table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .content table th{color:#f2f2f2}html.theme--documenter-dark .content table th:not([align]){text-align:inherit}html.theme--documenter-dark .content table thead td,html.theme--documenter-dark .content table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .content table tfoot td,html.theme--documenter-dark .content table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .content table tbody tr:last-child td,html.theme--documenter-dark .content table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .content .tabs li+li{margin-top:0}html.theme--documenter-dark .content.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}html.theme--documenter-dark .content.is-normal{font-size:1rem}html.theme--documenter-dark .content.is-medium{font-size:1.25rem}html.theme--documenter-dark .content.is-large{font-size:1.5rem}html.theme--documenter-dark .icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}html.theme--documenter-dark .icon.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}html.theme--documenter-dark .icon.is-medium{height:2rem;width:2rem}html.theme--documenter-dark .icon.is-large{height:3rem;width:3rem}html.theme--documenter-dark .icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}html.theme--documenter-dark .icon-text .icon{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .icon-text .icon:not(:last-child){margin-right:.25em}html.theme--documenter-dark .icon-text .icon:not(:first-child){margin-left:.25em}html.theme--documenter-dark div.icon-text{display:flex}html.theme--documenter-dark .image,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{display:block;position:relative}html.theme--documenter-dark .image img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}html.theme--documenter-dark .image img.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}html.theme--documenter-dark .image.is-fullwidth,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}html.theme--documenter-dark .image.is-square img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square img,html.theme--documenter-dark .image.is-square .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,html.theme--documenter-dark .image.is-1by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 img,html.theme--documenter-dark .image.is-1by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,html.theme--documenter-dark .image.is-5by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 img,html.theme--documenter-dark .image.is-5by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,html.theme--documenter-dark .image.is-4by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 img,html.theme--documenter-dark .image.is-4by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,html.theme--documenter-dark .image.is-3by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 img,html.theme--documenter-dark .image.is-3by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,html.theme--documenter-dark .image.is-5by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 img,html.theme--documenter-dark .image.is-5by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,html.theme--documenter-dark .image.is-16by9 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 img,html.theme--documenter-dark .image.is-16by9 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,html.theme--documenter-dark .image.is-2by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 img,html.theme--documenter-dark .image.is-2by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,html.theme--documenter-dark .image.is-3by1 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 img,html.theme--documenter-dark .image.is-3by1 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,html.theme--documenter-dark .image.is-4by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 img,html.theme--documenter-dark .image.is-4by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,html.theme--documenter-dark .image.is-3by4 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 img,html.theme--documenter-dark .image.is-3by4 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,html.theme--documenter-dark .image.is-2by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 img,html.theme--documenter-dark .image.is-2by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,html.theme--documenter-dark .image.is-3by5 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 img,html.theme--documenter-dark .image.is-3by5 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,html.theme--documenter-dark .image.is-9by16 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 img,html.theme--documenter-dark .image.is-9by16 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,html.theme--documenter-dark .image.is-1by2 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 img,html.theme--documenter-dark .image.is-1by2 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,html.theme--documenter-dark .image.is-1by3 img,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 img,html.theme--documenter-dark .image.is-1by3 .has-ratio,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}html.theme--documenter-dark .image.is-square,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-square,html.theme--documenter-dark .image.is-1by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}html.theme--documenter-dark .image.is-5by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}html.theme--documenter-dark .image.is-4by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}html.theme--documenter-dark .image.is-3by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}html.theme--documenter-dark .image.is-5by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}html.theme--documenter-dark .image.is-16by9,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}html.theme--documenter-dark .image.is-2by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}html.theme--documenter-dark .image.is-3by1,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}html.theme--documenter-dark .image.is-4by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}html.theme--documenter-dark .image.is-3by4,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}html.theme--documenter-dark .image.is-2by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}html.theme--documenter-dark .image.is-3by5,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}html.theme--documenter-dark .image.is-9by16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}html.theme--documenter-dark .image.is-1by2,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}html.theme--documenter-dark .image.is-1by3,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}html.theme--documenter-dark .image.is-16x16,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}html.theme--documenter-dark .image.is-24x24,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}html.theme--documenter-dark .image.is-32x32,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}html.theme--documenter-dark .image.is-48x48,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}html.theme--documenter-dark .image.is-64x64,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}html.theme--documenter-dark .image.is-96x96,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}html.theme--documenter-dark .image.is-128x128,html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}html.theme--documenter-dark .notification{background-color:#282f2f;border-radius:.4em;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}html.theme--documenter-dark .notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .notification strong{color:currentColor}html.theme--documenter-dark .notification code,html.theme--documenter-dark .notification pre{background:#fff}html.theme--documenter-dark .notification pre code{background:transparent}html.theme--documenter-dark .notification>.delete{right:.5rem;position:absolute;top:0.5rem}html.theme--documenter-dark .notification .title,html.theme--documenter-dark .notification .subtitle,html.theme--documenter-dark .notification .content{color:currentColor}html.theme--documenter-dark .notification.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .notification.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .notification.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .notification.is-dark,html.theme--documenter-dark .content kbd.notification{background-color:#282f2f;color:#fff}html.theme--documenter-dark .notification.is-primary,html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .notification.is-primary.is-light,html.theme--documenter-dark .docstring>section>a.notification.is-light.docs-sourcelink{background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .notification.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .notification.is-link.is-light{background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .notification.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .notification.is-info.is-light{background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .notification.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .notification.is-success.is-light{background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .notification.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .notification.is-warning.is-light{background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .notification.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .notification.is-danger.is-light{background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}html.theme--documenter-dark .progress::-webkit-progress-bar{background-color:#343c3d}html.theme--documenter-dark .progress::-webkit-progress-value{background-color:#dbdee0}html.theme--documenter-dark .progress::-moz-progress-bar{background-color:#dbdee0}html.theme--documenter-dark .progress::-ms-fill{background-color:#dbdee0;border:none}html.theme--documenter-dark .progress.is-white::-webkit-progress-value{background-color:#fff}html.theme--documenter-dark .progress.is-white::-moz-progress-bar{background-color:#fff}html.theme--documenter-dark .progress.is-white::-ms-fill{background-color:#fff}html.theme--documenter-dark .progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-black::-webkit-progress-value{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-moz-progress-bar{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black::-ms-fill{background-color:#0a0a0a}html.theme--documenter-dark .progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-light::-webkit-progress-value{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-moz-progress-bar{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light::-ms-fill{background-color:#ecf0f1}html.theme--documenter-dark .progress.is-light:indeterminate{background-image:linear-gradient(to right, #ecf0f1 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-dark::-webkit-progress-value,html.theme--documenter-dark .content kbd.progress::-webkit-progress-value{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-moz-progress-bar,html.theme--documenter-dark .content kbd.progress::-moz-progress-bar{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark::-ms-fill,html.theme--documenter-dark .content kbd.progress::-ms-fill{background-color:#282f2f}html.theme--documenter-dark .progress.is-dark:indeterminate,html.theme--documenter-dark .content kbd.progress:indeterminate{background-image:linear-gradient(to right, #282f2f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-primary::-webkit-progress-value,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-moz-progress-bar,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary::-ms-fill,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#375a7f}html.theme--documenter-dark .progress.is-primary:indeterminate,html.theme--documenter-dark .docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #375a7f 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-link::-webkit-progress-value{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-moz-progress-bar{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link::-ms-fill{background-color:#1abc9c}html.theme--documenter-dark .progress.is-link:indeterminate{background-image:linear-gradient(to right, #1abc9c 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-info::-webkit-progress-value{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-moz-progress-bar{background-color:#024c7d}html.theme--documenter-dark .progress.is-info::-ms-fill{background-color:#024c7d}html.theme--documenter-dark .progress.is-info:indeterminate{background-image:linear-gradient(to right, #024c7d 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-success::-webkit-progress-value{background-color:#008438}html.theme--documenter-dark .progress.is-success::-moz-progress-bar{background-color:#008438}html.theme--documenter-dark .progress.is-success::-ms-fill{background-color:#008438}html.theme--documenter-dark .progress.is-success:indeterminate{background-image:linear-gradient(to right, #008438 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-warning::-webkit-progress-value{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-moz-progress-bar{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning::-ms-fill{background-color:#ad8100}html.theme--documenter-dark .progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ad8100 30%, #343c3d 30%)}html.theme--documenter-dark .progress.is-danger::-webkit-progress-value{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-moz-progress-bar{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger::-ms-fill{background-color:#9e1b0d}html.theme--documenter-dark .progress.is-danger:indeterminate{background-image:linear-gradient(to right, #9e1b0d 30%, #343c3d 30%)}html.theme--documenter-dark .progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#343c3d;background-image:linear-gradient(to right, #fff 30%, #343c3d 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}html.theme--documenter-dark .progress:indeterminate::-webkit-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-moz-progress-bar{background-color:transparent}html.theme--documenter-dark .progress:indeterminate::-ms-fill{animation-name:none}html.theme--documenter-dark .progress.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}html.theme--documenter-dark .progress.is-medium{height:1.25rem}html.theme--documenter-dark .progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}html.theme--documenter-dark .table{background-color:#343c3d;color:#fff}html.theme--documenter-dark .table td,html.theme--documenter-dark .table th{border:1px solid #5e6d6f;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}html.theme--documenter-dark .table td.is-white,html.theme--documenter-dark .table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .table td.is-black,html.theme--documenter-dark .table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .table td.is-light,html.theme--documenter-dark .table th.is-light{background-color:#ecf0f1;border-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .table td.is-dark,html.theme--documenter-dark .table th.is-dark{background-color:#282f2f;border-color:#282f2f;color:#fff}html.theme--documenter-dark .table td.is-primary,html.theme--documenter-dark .table th.is-primary{background-color:#375a7f;border-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-link,html.theme--documenter-dark .table th.is-link{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .table td.is-info,html.theme--documenter-dark .table th.is-info{background-color:#024c7d;border-color:#024c7d;color:#fff}html.theme--documenter-dark .table td.is-success,html.theme--documenter-dark .table th.is-success{background-color:#008438;border-color:#008438;color:#fff}html.theme--documenter-dark .table td.is-warning,html.theme--documenter-dark .table th.is-warning{background-color:#ad8100;border-color:#ad8100;color:#fff}html.theme--documenter-dark .table td.is-danger,html.theme--documenter-dark .table th.is-danger{background-color:#9e1b0d;border-color:#9e1b0d;color:#fff}html.theme--documenter-dark .table td.is-narrow,html.theme--documenter-dark .table th.is-narrow{white-space:nowrap;width:1%}html.theme--documenter-dark .table td.is-selected,html.theme--documenter-dark .table th.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table td.is-selected a,html.theme--documenter-dark .table td.is-selected strong,html.theme--documenter-dark .table th.is-selected a,html.theme--documenter-dark .table th.is-selected strong{color:currentColor}html.theme--documenter-dark .table td.is-vcentered,html.theme--documenter-dark .table th.is-vcentered{vertical-align:middle}html.theme--documenter-dark .table th{color:#f2f2f2}html.theme--documenter-dark .table th:not([align]){text-align:left}html.theme--documenter-dark .table tr.is-selected{background-color:#375a7f;color:#fff}html.theme--documenter-dark .table tr.is-selected a,html.theme--documenter-dark .table tr.is-selected strong{color:currentColor}html.theme--documenter-dark .table tr.is-selected td,html.theme--documenter-dark .table tr.is-selected th{border-color:#fff;color:currentColor}html.theme--documenter-dark .table thead{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table thead td,html.theme--documenter-dark .table thead th{border-width:0 0 2px;color:#f2f2f2}html.theme--documenter-dark .table tfoot{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tfoot td,html.theme--documenter-dark .table tfoot th{border-width:2px 0 0;color:#f2f2f2}html.theme--documenter-dark .table tbody{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .table tbody tr:last-child td,html.theme--documenter-dark .table tbody tr:last-child th{border-bottom-width:0}html.theme--documenter-dark .table.is-bordered td,html.theme--documenter-dark .table.is-bordered th{border-width:1px}html.theme--documenter-dark .table.is-bordered tr:last-child td,html.theme--documenter-dark .table.is-bordered tr:last-child th{border-bottom-width:1px}html.theme--documenter-dark .table.is-fullwidth{width:100%}html.theme--documenter-dark .table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#282f2f}html.theme--documenter-dark .table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#2d3435}html.theme--documenter-dark .table.is-narrow td,html.theme--documenter-dark .table.is-narrow th{padding:0.25em 0.5em}html.theme--documenter-dark .table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#282f2f}html.theme--documenter-dark .table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}html.theme--documenter-dark .tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .tags .tag,html.theme--documenter-dark .tags .content kbd,html.theme--documenter-dark .content .tags kbd,html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}html.theme--documenter-dark .tags .tag:not(:last-child),html.theme--documenter-dark .tags .content kbd:not(:last-child),html.theme--documenter-dark .content .tags kbd:not(:last-child),html.theme--documenter-dark .tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}html.theme--documenter-dark .tags:last-child{margin-bottom:-0.5rem}html.theme--documenter-dark .tags:not(:last-child){margin-bottom:1rem}html.theme--documenter-dark .tags.are-medium .tag:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .content kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .content .tags.are-medium kbd:not(.is-normal):not(.is-large),html.theme--documenter-dark .tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}html.theme--documenter-dark .tags.are-large .tag:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .content kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .content .tags.are-large kbd:not(.is-normal):not(.is-medium),html.theme--documenter-dark .tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}html.theme--documenter-dark .tags.is-centered{justify-content:center}html.theme--documenter-dark .tags.is-centered .tag,html.theme--documenter-dark .tags.is-centered .content kbd,html.theme--documenter-dark .content .tags.is-centered kbd,html.theme--documenter-dark .tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}html.theme--documenter-dark .tags.is-right{justify-content:flex-end}html.theme--documenter-dark .tags.is-right .tag:not(:first-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:first-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}html.theme--documenter-dark .tags.is-right .tag:not(:last-child),html.theme--documenter-dark .tags.is-right .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.is-right kbd:not(:last-child),html.theme--documenter-dark .tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}html.theme--documenter-dark .tags.has-addons .tag,html.theme--documenter-dark .tags.has-addons .content kbd,html.theme--documenter-dark .content .tags.has-addons kbd,html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}html.theme--documenter-dark .tags.has-addons .tag:not(:first-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:first-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:first-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}html.theme--documenter-dark .tags.has-addons .tag:not(:last-child),html.theme--documenter-dark .tags.has-addons .content kbd:not(:last-child),html.theme--documenter-dark .content .tags.has-addons kbd:not(:last-child),html.theme--documenter-dark .tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}html.theme--documenter-dark .tag:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#282f2f;border-radius:.4em;color:#fff;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}html.theme--documenter-dark .tag:not(body) .delete,html.theme--documenter-dark .content kbd:not(body) .delete,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}html.theme--documenter-dark .tag.is-white:not(body),html.theme--documenter-dark .content kbd.is-white:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .tag.is-black:not(body),html.theme--documenter-dark .content kbd.is-black:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .tag.is-light:not(body),html.theme--documenter-dark .content kbd.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .tag.is-dark:not(body),html.theme--documenter-dark .content kbd:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-dark:not(body),html.theme--documenter-dark .content .docstring>section>kbd:not(body){background-color:#282f2f;color:#fff}html.theme--documenter-dark .tag.is-primary:not(body),html.theme--documenter-dark .content kbd.is-primary:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body){background-color:#375a7f;color:#fff}html.theme--documenter-dark .tag.is-primary.is-light:not(body),html.theme--documenter-dark .content kbd.is-primary.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f1f5f9;color:#4d7eb2}html.theme--documenter-dark .tag.is-link:not(body),html.theme--documenter-dark .content kbd.is-link:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#1abc9c;color:#fff}html.theme--documenter-dark .tag.is-link.is-light:not(body),html.theme--documenter-dark .content kbd.is-link.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#edfdf9;color:#15987e}html.theme--documenter-dark .tag.is-info:not(body),html.theme--documenter-dark .content kbd.is-info:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#024c7d;color:#fff}html.theme--documenter-dark .tag.is-info.is-light:not(body),html.theme--documenter-dark .content kbd.is-info.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ebf7ff;color:#0e9dfb}html.theme--documenter-dark .tag.is-success:not(body),html.theme--documenter-dark .content kbd.is-success:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#008438;color:#fff}html.theme--documenter-dark .tag.is-success.is-light:not(body),html.theme--documenter-dark .content kbd.is-success.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#ebfff3;color:#00eb64}html.theme--documenter-dark .tag.is-warning:not(body),html.theme--documenter-dark .content kbd.is-warning:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ad8100;color:#fff}html.theme--documenter-dark .tag.is-warning.is-light:not(body),html.theme--documenter-dark .content kbd.is-warning.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffaeb;color:#d19c00}html.theme--documenter-dark .tag.is-danger:not(body),html.theme--documenter-dark .content kbd.is-danger:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .tag.is-danger.is-light:not(body),html.theme--documenter-dark .content kbd.is-danger.is-light:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#fdeeec;color:#ec311d}html.theme--documenter-dark .tag.is-normal:not(body),html.theme--documenter-dark .content kbd.is-normal:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}html.theme--documenter-dark .tag.is-medium:not(body),html.theme--documenter-dark .content kbd.is-medium:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}html.theme--documenter-dark .tag.is-large:not(body),html.theme--documenter-dark .content kbd.is-large:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}html.theme--documenter-dark .tag:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .content kbd:not(body) .icon:first-child:not(:last-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}html.theme--documenter-dark .tag:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .content kbd:not(body) .icon:last-child:not(:first-child),html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}html.theme--documenter-dark .tag:not(body) .icon:first-child:last-child,html.theme--documenter-dark .content kbd:not(body) .icon:first-child:last-child,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}html.theme--documenter-dark .tag.is-delete:not(body),html.theme--documenter-dark .content kbd.is-delete:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before,html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}html.theme--documenter-dark .tag.is-delete:not(body)::before,html.theme--documenter-dark .content kbd.is-delete:not(body)::before,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}html.theme--documenter-dark .tag.is-delete:not(body)::after,html.theme--documenter-dark .content kbd.is-delete:not(body)::after,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}html.theme--documenter-dark .tag.is-delete:not(body):hover,html.theme--documenter-dark .content kbd.is-delete:not(body):hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):hover,html.theme--documenter-dark .tag.is-delete:not(body):focus,html.theme--documenter-dark .content kbd.is-delete:not(body):focus,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#1d2122}html.theme--documenter-dark .tag.is-delete:not(body):active,html.theme--documenter-dark .content kbd.is-delete:not(body):active,html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#111414}html.theme--documenter-dark .tag.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:not(body),html.theme--documenter-dark .content kbd.is-rounded:not(body),html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input:not(body),html.theme--documenter-dark .docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}html.theme--documenter-dark a.tag:hover,html.theme--documenter-dark .docstring>section>a.docs-sourcelink:hover{text-decoration:underline}html.theme--documenter-dark .title,html.theme--documenter-dark .subtitle{word-break:break-word}html.theme--documenter-dark .title em,html.theme--documenter-dark .title span,html.theme--documenter-dark .subtitle em,html.theme--documenter-dark .subtitle span{font-weight:inherit}html.theme--documenter-dark .title sub,html.theme--documenter-dark .subtitle sub{font-size:.75em}html.theme--documenter-dark .title sup,html.theme--documenter-dark .subtitle sup{font-size:.75em}html.theme--documenter-dark .title .tag,html.theme--documenter-dark .title .content kbd,html.theme--documenter-dark .content .title kbd,html.theme--documenter-dark .title .docstring>section>a.docs-sourcelink,html.theme--documenter-dark .subtitle .tag,html.theme--documenter-dark .subtitle .content kbd,html.theme--documenter-dark .content .subtitle kbd,html.theme--documenter-dark .subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}html.theme--documenter-dark .title{color:#fff;font-size:2rem;font-weight:500;line-height:1.125}html.theme--documenter-dark .title strong{color:inherit;font-weight:inherit}html.theme--documenter-dark .title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}html.theme--documenter-dark .title.is-1{font-size:3rem}html.theme--documenter-dark .title.is-2{font-size:2.5rem}html.theme--documenter-dark .title.is-3{font-size:2rem}html.theme--documenter-dark .title.is-4{font-size:1.5rem}html.theme--documenter-dark .title.is-5{font-size:1.25rem}html.theme--documenter-dark .title.is-6{font-size:1rem}html.theme--documenter-dark .title.is-7{font-size:.75rem}html.theme--documenter-dark .subtitle{color:#8c9b9d;font-size:1.25rem;font-weight:400;line-height:1.25}html.theme--documenter-dark .subtitle strong{color:#8c9b9d;font-weight:600}html.theme--documenter-dark .subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}html.theme--documenter-dark .subtitle.is-1{font-size:3rem}html.theme--documenter-dark .subtitle.is-2{font-size:2.5rem}html.theme--documenter-dark .subtitle.is-3{font-size:2rem}html.theme--documenter-dark .subtitle.is-4{font-size:1.5rem}html.theme--documenter-dark .subtitle.is-5{font-size:1.25rem}html.theme--documenter-dark .subtitle.is-6{font-size:1rem}html.theme--documenter-dark .subtitle.is-7{font-size:.75rem}html.theme--documenter-dark .heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}html.theme--documenter-dark .number{align-items:center;background-color:#282f2f;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#1f2424;border-color:#5e6d6f;border-radius:.4em;color:#dbdee0}html.theme--documenter-dark .select select::-moz-placeholder,html.theme--documenter-dark .textarea::-moz-placeholder,html.theme--documenter-dark .input::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select::-webkit-input-placeholder,html.theme--documenter-dark .textarea::-webkit-input-placeholder,html.theme--documenter-dark .input::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:-moz-placeholder,html.theme--documenter-dark .textarea:-moz-placeholder,html.theme--documenter-dark .input:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#868c98}html.theme--documenter-dark .select select:-ms-input-placeholder,html.theme--documenter-dark .textarea:-ms-input-placeholder,html.theme--documenter-dark .input:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#868c98}html.theme--documenter-dark .select select:hover,html.theme--documenter-dark .textarea:hover,html.theme--documenter-dark .input:hover,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:hover,html.theme--documenter-dark .select select.is-hovered,html.theme--documenter-dark .is-hovered.textarea,html.theme--documenter-dark .is-hovered.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#8c9b9d}html.theme--documenter-dark .select select:focus,html.theme--documenter-dark .textarea:focus,html.theme--documenter-dark .input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:focus,html.theme--documenter-dark .select select.is-focused,html.theme--documenter-dark .is-focused.textarea,html.theme--documenter-dark .is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .select select:active,html.theme--documenter-dark .textarea:active,html.theme--documenter-dark .input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:active,html.theme--documenter-dark .select select.is-active,html.theme--documenter-dark .is-active.textarea,html.theme--documenter-dark .is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{border-color:#1abc9c;box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select select[disabled],html.theme--documenter-dark .textarea[disabled],html.theme--documenter-dark .input[disabled],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] html.theme--documenter-dark .select select,fieldset[disabled] html.theme--documenter-dark .textarea,fieldset[disabled] html.theme--documenter-dark .input,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{background-color:#8c9b9d;border-color:#282f2f;box-shadow:none;color:#fff}html.theme--documenter-dark .select select[disabled]::-moz-placeholder,html.theme--documenter-dark .textarea[disabled]::-moz-placeholder,html.theme--documenter-dark .input[disabled]::-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .textarea[disabled]::-webkit-input-placeholder,html.theme--documenter-dark .input[disabled]::-webkit-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input::-webkit-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-moz-placeholder,html.theme--documenter-dark .textarea[disabled]:-moz-placeholder,html.theme--documenter-dark .input[disabled]:-moz-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-moz-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .select select[disabled]:-ms-input-placeholder,html.theme--documenter-dark .textarea[disabled]:-ms-input-placeholder,html.theme--documenter-dark .input[disabled]:-ms-input-placeholder,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .select select:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .textarea:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark .input:-ms-input-placeholder,fieldset[disabled] html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:rgba(255,255,255,0.3)}html.theme--documenter-dark .textarea,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}html.theme--documenter-dark .textarea[readonly],html.theme--documenter-dark .input[readonly],html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}html.theme--documenter-dark .is-white.textarea,html.theme--documenter-dark .is-white.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}html.theme--documenter-dark .is-white.textarea:focus,html.theme--documenter-dark .is-white.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:focus,html.theme--documenter-dark .is-white.is-focused.textarea,html.theme--documenter-dark .is-white.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-white.textarea:active,html.theme--documenter-dark .is-white.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-white:active,html.theme--documenter-dark .is-white.is-active.textarea,html.theme--documenter-dark .is-white.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .is-black.textarea,html.theme--documenter-dark .is-black.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}html.theme--documenter-dark .is-black.textarea:focus,html.theme--documenter-dark .is-black.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:focus,html.theme--documenter-dark .is-black.is-focused.textarea,html.theme--documenter-dark .is-black.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-black.textarea:active,html.theme--documenter-dark .is-black.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-black:active,html.theme--documenter-dark .is-black.is-active.textarea,html.theme--documenter-dark .is-black.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .is-light.textarea,html.theme--documenter-dark .is-light.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light{border-color:#ecf0f1}html.theme--documenter-dark .is-light.textarea:focus,html.theme--documenter-dark .is-light.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:focus,html.theme--documenter-dark .is-light.is-focused.textarea,html.theme--documenter-dark .is-light.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-light.textarea:active,html.theme--documenter-dark .is-light.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-light:active,html.theme--documenter-dark .is-light.is-active.textarea,html.theme--documenter-dark .is-light.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .is-dark.textarea,html.theme--documenter-dark .content kbd.textarea,html.theme--documenter-dark .is-dark.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark,html.theme--documenter-dark .content kbd.input{border-color:#282f2f}html.theme--documenter-dark .is-dark.textarea:focus,html.theme--documenter-dark .content kbd.textarea:focus,html.theme--documenter-dark .is-dark.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:focus,html.theme--documenter-dark .content kbd.input:focus,html.theme--documenter-dark .is-dark.is-focused.textarea,html.theme--documenter-dark .content kbd.is-focused.textarea,html.theme--documenter-dark .is-dark.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .content kbd.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-focused,html.theme--documenter-dark .is-dark.textarea:active,html.theme--documenter-dark .content kbd.textarea:active,html.theme--documenter-dark .is-dark.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-dark:active,html.theme--documenter-dark .content kbd.input:active,html.theme--documenter-dark .is-dark.is-active.textarea,html.theme--documenter-dark .content kbd.is-active.textarea,html.theme--documenter-dark .is-dark.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .content kbd.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .is-primary.textarea,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink{border-color:#375a7f}html.theme--documenter-dark .is-primary.textarea:focus,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:focus,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:focus,html.theme--documenter-dark .is-primary.is-focused.textarea,html.theme--documenter-dark .docstring>section>a.is-focused.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .docstring>section>a.is-focused.input.docs-sourcelink,html.theme--documenter-dark .is-primary.textarea:active,html.theme--documenter-dark .docstring>section>a.textarea.docs-sourcelink:active,html.theme--documenter-dark .is-primary.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-primary:active,html.theme--documenter-dark .docstring>section>a.input.docs-sourcelink:active,html.theme--documenter-dark .is-primary.is-active.textarea,html.theme--documenter-dark .docstring>section>a.is-active.textarea.docs-sourcelink,html.theme--documenter-dark .is-primary.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active,html.theme--documenter-dark .docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .is-link.textarea,html.theme--documenter-dark .is-link.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link{border-color:#1abc9c}html.theme--documenter-dark .is-link.textarea:focus,html.theme--documenter-dark .is-link.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:focus,html.theme--documenter-dark .is-link.is-focused.textarea,html.theme--documenter-dark .is-link.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-link.textarea:active,html.theme--documenter-dark .is-link.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-link:active,html.theme--documenter-dark .is-link.is-active.textarea,html.theme--documenter-dark .is-link.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .is-info.textarea,html.theme--documenter-dark .is-info.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info{border-color:#024c7d}html.theme--documenter-dark .is-info.textarea:focus,html.theme--documenter-dark .is-info.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:focus,html.theme--documenter-dark .is-info.is-focused.textarea,html.theme--documenter-dark .is-info.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-info.textarea:active,html.theme--documenter-dark .is-info.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-info:active,html.theme--documenter-dark .is-info.is-active.textarea,html.theme--documenter-dark .is-info.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .is-success.textarea,html.theme--documenter-dark .is-success.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success{border-color:#008438}html.theme--documenter-dark .is-success.textarea:focus,html.theme--documenter-dark .is-success.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:focus,html.theme--documenter-dark .is-success.is-focused.textarea,html.theme--documenter-dark .is-success.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-success.textarea:active,html.theme--documenter-dark .is-success.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-success:active,html.theme--documenter-dark .is-success.is-active.textarea,html.theme--documenter-dark .is-success.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .is-warning.textarea,html.theme--documenter-dark .is-warning.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ad8100}html.theme--documenter-dark .is-warning.textarea:focus,html.theme--documenter-dark .is-warning.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:focus,html.theme--documenter-dark .is-warning.is-focused.textarea,html.theme--documenter-dark .is-warning.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-warning.textarea:active,html.theme--documenter-dark .is-warning.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-warning:active,html.theme--documenter-dark .is-warning.is-active.textarea,html.theme--documenter-dark .is-warning.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .is-danger.textarea,html.theme--documenter-dark .is-danger.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#9e1b0d}html.theme--documenter-dark .is-danger.textarea:focus,html.theme--documenter-dark .is-danger.input:focus,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:focus,html.theme--documenter-dark .is-danger.is-focused.textarea,html.theme--documenter-dark .is-danger.is-focused.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-focused,html.theme--documenter-dark .is-danger.textarea:active,html.theme--documenter-dark .is-danger.input:active,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-danger:active,html.theme--documenter-dark .is-danger.is-active.textarea,html.theme--documenter-dark .is-danger.is-active.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .is-small.textarea,html.theme--documenter-dark .is-small.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .is-medium.textarea,html.theme--documenter-dark .is-medium.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}html.theme--documenter-dark .is-large.textarea,html.theme--documenter-dark .is-large.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}html.theme--documenter-dark .is-fullwidth.textarea,html.theme--documenter-dark .is-fullwidth.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}html.theme--documenter-dark .is-inline.textarea,html.theme--documenter-dark .is-inline.input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}html.theme--documenter-dark .input.is-rounded,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}html.theme--documenter-dark .input.is-static,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}html.theme--documenter-dark .textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}html.theme--documenter-dark .textarea:not([rows]){max-height:40em;min-height:8em}html.theme--documenter-dark .textarea[rows]{height:initial}html.theme--documenter-dark .textarea.has-fixed-size{resize:none}html.theme--documenter-dark .radio,html.theme--documenter-dark .checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}html.theme--documenter-dark .radio input,html.theme--documenter-dark .checkbox input{cursor:pointer}html.theme--documenter-dark .radio:hover,html.theme--documenter-dark .checkbox:hover{color:#8c9b9d}html.theme--documenter-dark .radio[disabled],html.theme--documenter-dark .checkbox[disabled],fieldset[disabled] html.theme--documenter-dark .radio,fieldset[disabled] html.theme--documenter-dark .checkbox,html.theme--documenter-dark .radio input[disabled],html.theme--documenter-dark .checkbox input[disabled]{color:#fff;cursor:not-allowed}html.theme--documenter-dark .radio+.radio{margin-left:.5em}html.theme--documenter-dark .select{display:inline-block;max-width:100%;position:relative;vertical-align:top}html.theme--documenter-dark .select:not(.is-multiple){height:2.5em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading)::after{border-color:#1abc9c;right:1.125em;z-index:4}html.theme--documenter-dark .select.is-rounded select,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}html.theme--documenter-dark .select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}html.theme--documenter-dark .select select::-ms-expand{display:none}html.theme--documenter-dark .select select[disabled]:hover,fieldset[disabled] html.theme--documenter-dark .select select:hover{border-color:#282f2f}html.theme--documenter-dark .select select:not([multiple]){padding-right:2.5em}html.theme--documenter-dark .select select[multiple]{height:auto;padding:0}html.theme--documenter-dark .select select[multiple] option{padding:0.5em 1em}html.theme--documenter-dark .select:not(.is-multiple):not(.is-loading):hover::after{border-color:#8c9b9d}html.theme--documenter-dark .select.is-white:not(:hover)::after{border-color:#fff}html.theme--documenter-dark .select.is-white select{border-color:#fff}html.theme--documenter-dark .select.is-white select:hover,html.theme--documenter-dark .select.is-white select.is-hovered{border-color:#f2f2f2}html.theme--documenter-dark .select.is-white select:focus,html.theme--documenter-dark .select.is-white select.is-focused,html.theme--documenter-dark .select.is-white select:active,html.theme--documenter-dark .select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}html.theme--documenter-dark .select.is-black:not(:hover)::after{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select{border-color:#0a0a0a}html.theme--documenter-dark .select.is-black select:hover,html.theme--documenter-dark .select.is-black select.is-hovered{border-color:#000}html.theme--documenter-dark .select.is-black select:focus,html.theme--documenter-dark .select.is-black select.is-focused,html.theme--documenter-dark .select.is-black select:active,html.theme--documenter-dark .select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}html.theme--documenter-dark .select.is-light:not(:hover)::after{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select{border-color:#ecf0f1}html.theme--documenter-dark .select.is-light select:hover,html.theme--documenter-dark .select.is-light select.is-hovered{border-color:#dde4e6}html.theme--documenter-dark .select.is-light select:focus,html.theme--documenter-dark .select.is-light select.is-focused,html.theme--documenter-dark .select.is-light select:active,html.theme--documenter-dark .select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(236,240,241,0.25)}html.theme--documenter-dark .select.is-dark:not(:hover)::after,html.theme--documenter-dark .content kbd.select:not(:hover)::after{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select,html.theme--documenter-dark .content kbd.select select{border-color:#282f2f}html.theme--documenter-dark .select.is-dark select:hover,html.theme--documenter-dark .content kbd.select select:hover,html.theme--documenter-dark .select.is-dark select.is-hovered,html.theme--documenter-dark .content kbd.select select.is-hovered{border-color:#1d2122}html.theme--documenter-dark .select.is-dark select:focus,html.theme--documenter-dark .content kbd.select select:focus,html.theme--documenter-dark .select.is-dark select.is-focused,html.theme--documenter-dark .content kbd.select select.is-focused,html.theme--documenter-dark .select.is-dark select:active,html.theme--documenter-dark .content kbd.select select:active,html.theme--documenter-dark .select.is-dark select.is-active,html.theme--documenter-dark .content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(40,47,47,0.25)}html.theme--documenter-dark .select.is-primary:not(:hover)::after,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select{border-color:#375a7f}html.theme--documenter-dark .select.is-primary select:hover,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:hover,html.theme--documenter-dark .select.is-primary select.is-hovered,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#2f4d6d}html.theme--documenter-dark .select.is-primary select:focus,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:focus,html.theme--documenter-dark .select.is-primary select.is-focused,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-focused,html.theme--documenter-dark .select.is-primary select:active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select:active,html.theme--documenter-dark .select.is-primary select.is-active,html.theme--documenter-dark .docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(55,90,127,0.25)}html.theme--documenter-dark .select.is-link:not(:hover)::after{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select{border-color:#1abc9c}html.theme--documenter-dark .select.is-link select:hover,html.theme--documenter-dark .select.is-link select.is-hovered{border-color:#17a689}html.theme--documenter-dark .select.is-link select:focus,html.theme--documenter-dark .select.is-link select.is-focused,html.theme--documenter-dark .select.is-link select:active,html.theme--documenter-dark .select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(26,188,156,0.25)}html.theme--documenter-dark .select.is-info:not(:hover)::after{border-color:#024c7d}html.theme--documenter-dark .select.is-info select{border-color:#024c7d}html.theme--documenter-dark .select.is-info select:hover,html.theme--documenter-dark .select.is-info select.is-hovered{border-color:#023d64}html.theme--documenter-dark .select.is-info select:focus,html.theme--documenter-dark .select.is-info select.is-focused,html.theme--documenter-dark .select.is-info select:active,html.theme--documenter-dark .select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(2,76,125,0.25)}html.theme--documenter-dark .select.is-success:not(:hover)::after{border-color:#008438}html.theme--documenter-dark .select.is-success select{border-color:#008438}html.theme--documenter-dark .select.is-success select:hover,html.theme--documenter-dark .select.is-success select.is-hovered{border-color:#006b2d}html.theme--documenter-dark .select.is-success select:focus,html.theme--documenter-dark .select.is-success select.is-focused,html.theme--documenter-dark .select.is-success select:active,html.theme--documenter-dark .select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(0,132,56,0.25)}html.theme--documenter-dark .select.is-warning:not(:hover)::after{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select{border-color:#ad8100}html.theme--documenter-dark .select.is-warning select:hover,html.theme--documenter-dark .select.is-warning select.is-hovered{border-color:#946e00}html.theme--documenter-dark .select.is-warning select:focus,html.theme--documenter-dark .select.is-warning select.is-focused,html.theme--documenter-dark .select.is-warning select:active,html.theme--documenter-dark .select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(173,129,0,0.25)}html.theme--documenter-dark .select.is-danger:not(:hover)::after{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select{border-color:#9e1b0d}html.theme--documenter-dark .select.is-danger select:hover,html.theme--documenter-dark .select.is-danger select.is-hovered{border-color:#86170b}html.theme--documenter-dark .select.is-danger select:focus,html.theme--documenter-dark .select.is-danger select.is-focused,html.theme--documenter-dark .select.is-danger select:active,html.theme--documenter-dark .select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(158,27,13,0.25)}html.theme--documenter-dark .select.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.select{border-radius:3px;font-size:.75rem}html.theme--documenter-dark .select.is-medium{font-size:1.25rem}html.theme--documenter-dark .select.is-large{font-size:1.5rem}html.theme--documenter-dark .select.is-disabled::after{border-color:#fff !important;opacity:0.5}html.theme--documenter-dark .select.is-fullwidth{width:100%}html.theme--documenter-dark .select.is-fullwidth select{width:100%}html.theme--documenter-dark .select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}html.theme--documenter-dark .select.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .select.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .select.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}html.theme--documenter-dark .file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:hover .file-cta,html.theme--documenter-dark .file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-white:focus .file-cta,html.theme--documenter-dark .file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}html.theme--documenter-dark .file.is-white:active .file-cta,html.theme--documenter-dark .file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}html.theme--documenter-dark .file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:hover .file-cta,html.theme--documenter-dark .file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-black:focus .file-cta,html.theme--documenter-dark .file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}html.theme--documenter-dark .file.is-black:active .file-cta,html.theme--documenter-dark .file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-light .file-cta{background-color:#ecf0f1;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:hover .file-cta,html.theme--documenter-dark .file.is-light.is-hovered .file-cta{background-color:#e5eaec;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:focus .file-cta,html.theme--documenter-dark .file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(236,240,241,0.25);color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-light:active .file-cta,html.theme--documenter-dark .file.is-light.is-active .file-cta{background-color:#dde4e6;border-color:transparent;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .file.is-dark .file-cta,html.theme--documenter-dark .content kbd.file .file-cta{background-color:#282f2f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:hover .file-cta,html.theme--documenter-dark .content kbd.file:hover .file-cta,html.theme--documenter-dark .file.is-dark.is-hovered .file-cta,html.theme--documenter-dark .content kbd.file.is-hovered .file-cta{background-color:#232829;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-dark:focus .file-cta,html.theme--documenter-dark .content kbd.file:focus .file-cta,html.theme--documenter-dark .file.is-dark.is-focused .file-cta,html.theme--documenter-dark .content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(40,47,47,0.25);color:#fff}html.theme--documenter-dark .file.is-dark:active .file-cta,html.theme--documenter-dark .content kbd.file:active .file-cta,html.theme--documenter-dark .file.is-dark.is-active .file-cta,html.theme--documenter-dark .content kbd.file.is-active .file-cta{background-color:#1d2122;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink .file-cta{background-color:#375a7f;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:hover .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:hover .file-cta,html.theme--documenter-dark .file.is-primary.is-hovered .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#335476;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-primary:focus .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:focus .file-cta,html.theme--documenter-dark .file.is-primary.is-focused .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(55,90,127,0.25);color:#fff}html.theme--documenter-dark .file.is-primary:active .file-cta,html.theme--documenter-dark .docstring>section>a.file.docs-sourcelink:active .file-cta,html.theme--documenter-dark .file.is-primary.is-active .file-cta,html.theme--documenter-dark .docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#2f4d6d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link .file-cta{background-color:#1abc9c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:hover .file-cta,html.theme--documenter-dark .file.is-link.is-hovered .file-cta{background-color:#18b193;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-link:focus .file-cta,html.theme--documenter-dark .file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(26,188,156,0.25);color:#fff}html.theme--documenter-dark .file.is-link:active .file-cta,html.theme--documenter-dark .file.is-link.is-active .file-cta{background-color:#17a689;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info .file-cta{background-color:#024c7d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:hover .file-cta,html.theme--documenter-dark .file.is-info.is-hovered .file-cta{background-color:#024470;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-info:focus .file-cta,html.theme--documenter-dark .file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(2,76,125,0.25);color:#fff}html.theme--documenter-dark .file.is-info:active .file-cta,html.theme--documenter-dark .file.is-info.is-active .file-cta{background-color:#023d64;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success .file-cta{background-color:#008438;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:hover .file-cta,html.theme--documenter-dark .file.is-success.is-hovered .file-cta{background-color:#073;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-success:focus .file-cta,html.theme--documenter-dark .file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(0,132,56,0.25);color:#fff}html.theme--documenter-dark .file.is-success:active .file-cta,html.theme--documenter-dark .file.is-success.is-active .file-cta{background-color:#006b2d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning .file-cta{background-color:#ad8100;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:hover .file-cta,html.theme--documenter-dark .file.is-warning.is-hovered .file-cta{background-color:#a07700;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-warning:focus .file-cta,html.theme--documenter-dark .file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(173,129,0,0.25);color:#fff}html.theme--documenter-dark .file.is-warning:active .file-cta,html.theme--documenter-dark .file.is-warning.is-active .file-cta{background-color:#946e00;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger .file-cta{background-color:#9e1b0d;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:hover .file-cta,html.theme--documenter-dark .file.is-danger.is-hovered .file-cta{background-color:#92190c;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-danger:focus .file-cta,html.theme--documenter-dark .file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(158,27,13,0.25);color:#fff}html.theme--documenter-dark .file.is-danger:active .file-cta,html.theme--documenter-dark .file.is-danger.is-active .file-cta{background-color:#86170b;border-color:transparent;color:#fff}html.theme--documenter-dark .file.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}html.theme--documenter-dark .file.is-normal{font-size:1rem}html.theme--documenter-dark .file.is-medium{font-size:1.25rem}html.theme--documenter-dark .file.is-medium .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-large{font-size:1.5rem}html.theme--documenter-dark .file.is-large .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .file.has-name.is-empty .file-cta{border-radius:.4em}html.theme--documenter-dark .file.has-name.is-empty .file-name{display:none}html.theme--documenter-dark .file.is-boxed .file-label{flex-direction:column}html.theme--documenter-dark .file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}html.theme--documenter-dark .file.is-boxed .file-name{border-width:0 1px 1px}html.theme--documenter-dark .file.is-boxed .file-icon{height:1.5em;width:1.5em}html.theme--documenter-dark .file.is-boxed .file-icon .fa{font-size:21px}html.theme--documenter-dark .file.is-boxed.is-small .file-icon .fa,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}html.theme--documenter-dark .file.is-boxed.is-medium .file-icon .fa{font-size:28px}html.theme--documenter-dark .file.is-boxed.is-large .file-icon .fa{font-size:35px}html.theme--documenter-dark .file.is-boxed.has-name .file-cta{border-radius:.4em .4em 0 0}html.theme--documenter-dark .file.is-boxed.has-name .file-name{border-radius:0 0 .4em .4em;border-width:0 1px 1px}html.theme--documenter-dark .file.is-centered{justify-content:center}html.theme--documenter-dark .file.is-fullwidth .file-label{width:100%}html.theme--documenter-dark .file.is-fullwidth .file-name{flex-grow:1;max-width:none}html.theme--documenter-dark .file.is-right{justify-content:flex-end}html.theme--documenter-dark .file.is-right .file-cta{border-radius:0 .4em .4em 0}html.theme--documenter-dark .file.is-right .file-name{border-radius:.4em 0 0 .4em;border-width:1px 0 1px 1px;order:-1}html.theme--documenter-dark .file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}html.theme--documenter-dark .file-label:hover .file-cta{background-color:#232829;color:#f2f2f2}html.theme--documenter-dark .file-label:hover .file-name{border-color:#596668}html.theme--documenter-dark .file-label:active .file-cta{background-color:#1d2122;color:#f2f2f2}html.theme--documenter-dark .file-label:active .file-name{border-color:#535f61}html.theme--documenter-dark .file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}html.theme--documenter-dark .file-cta,html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-radius:.4em;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}html.theme--documenter-dark .file-cta{background-color:#282f2f;color:#fff}html.theme--documenter-dark .file-name{border-color:#5e6d6f;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}html.theme--documenter-dark .file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}html.theme--documenter-dark .file-icon .fa{font-size:14px}html.theme--documenter-dark .label{color:#f2f2f2;display:block;font-size:1rem;font-weight:700}html.theme--documenter-dark .label:not(:last-child){margin-bottom:0.5em}html.theme--documenter-dark .label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}html.theme--documenter-dark .label.is-medium{font-size:1.25rem}html.theme--documenter-dark .label.is-large{font-size:1.5rem}html.theme--documenter-dark .help{display:block;font-size:.75rem;margin-top:0.25rem}html.theme--documenter-dark .help.is-white{color:#fff}html.theme--documenter-dark .help.is-black{color:#0a0a0a}html.theme--documenter-dark .help.is-light{color:#ecf0f1}html.theme--documenter-dark .help.is-dark,html.theme--documenter-dark .content kbd.help{color:#282f2f}html.theme--documenter-dark .help.is-primary,html.theme--documenter-dark .docstring>section>a.help.docs-sourcelink{color:#375a7f}html.theme--documenter-dark .help.is-link{color:#1abc9c}html.theme--documenter-dark .help.is-info{color:#024c7d}html.theme--documenter-dark .help.is-success{color:#008438}html.theme--documenter-dark .help.is-warning{color:#ad8100}html.theme--documenter-dark .help.is-danger{color:#9e1b0d}html.theme--documenter-dark .field:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.has-addons{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.has-addons .control:not(:last-child){margin-right:-1px}html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .button,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .button,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,html.theme--documenter-dark .field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]),html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]){z-index:3}html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .button.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .button:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .button.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark #documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):focus:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-focused:not([disabled]):hover,html.theme--documenter-dark .field.has-addons .control .select select:not([disabled]):active:hover,html.theme--documenter-dark .field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}html.theme--documenter-dark .field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.has-addons.has-addons-centered{justify-content:center}html.theme--documenter-dark .field.has-addons.has-addons-right{justify-content:flex-end}html.theme--documenter-dark .field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .field.is-grouped{display:flex;justify-content:flex-start}html.theme--documenter-dark .field.is-grouped>.control{flex-shrink:0}html.theme--documenter-dark .field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .field.is-grouped.is-grouped-centered{justify-content:center}html.theme--documenter-dark .field.is-grouped.is-grouped-right{justify-content:flex-end}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline{flex-wrap:wrap}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:last-child,html.theme--documenter-dark .field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}html.theme--documenter-dark .field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field.is-horizontal{display:flex}}html.theme--documenter-dark .field-label .label{font-size:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}html.theme--documenter-dark .field-label.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-normal{padding-top:0.375em}html.theme--documenter-dark .field-label.is-medium{font-size:1.25rem;padding-top:0.375em}html.theme--documenter-dark .field-label.is-large{font-size:1.5rem;padding-top:0.375em}}html.theme--documenter-dark .field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{html.theme--documenter-dark .field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}html.theme--documenter-dark .field-body .field{margin-bottom:0}html.theme--documenter-dark .field-body>.field{flex-shrink:1}html.theme--documenter-dark .field-body>.field:not(.is-narrow){flex-grow:1}html.theme--documenter-dark .field-body>.field:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}html.theme--documenter-dark .control.has-icons-left .input:focus~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-left .select:focus~.icon,html.theme--documenter-dark .control.has-icons-right .input:focus~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,html.theme--documenter-dark .control.has-icons-right .select:focus~.icon{color:#282f2f}html.theme--documenter-dark .control.has-icons-left .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-small~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-small~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-small~.icon{font-size:.75rem}html.theme--documenter-dark .control.has-icons-left .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}html.theme--documenter-dark .control.has-icons-left .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-left .select.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,html.theme--documenter-dark .control.has-icons-right .select.is-large~.icon{font-size:1.5rem}html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon{color:#5e6d6f;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}html.theme--documenter-dark .control.has-icons-left .input,html.theme--documenter-dark .control.has-icons-left #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-left form.docs-search>input,html.theme--documenter-dark .control.has-icons-left .select select{padding-left:2.5em}html.theme--documenter-dark .control.has-icons-left .icon.is-left{left:0}html.theme--documenter-dark .control.has-icons-right .input,html.theme--documenter-dark .control.has-icons-right #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-icons-right form.docs-search>input,html.theme--documenter-dark .control.has-icons-right .select select{padding-right:2.5em}html.theme--documenter-dark .control.has-icons-right .icon.is-right{right:0}html.theme--documenter-dark .control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}html.theme--documenter-dark .control.is-loading.is-small:after,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}html.theme--documenter-dark .control.is-loading.is-medium:after{font-size:1.25rem}html.theme--documenter-dark .control.is-loading.is-large:after{font-size:1.5rem}html.theme--documenter-dark .breadcrumb{font-size:1rem;white-space:nowrap}html.theme--documenter-dark .breadcrumb a{align-items:center;color:#1abc9c;display:flex;justify-content:center;padding:0 .75em}html.theme--documenter-dark .breadcrumb a:hover{color:#1dd2af}html.theme--documenter-dark .breadcrumb li{align-items:center;display:flex}html.theme--documenter-dark .breadcrumb li:first-child a{padding-left:0}html.theme--documenter-dark .breadcrumb li.is-active a{color:#f2f2f2;cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb li+li::before{color:#8c9b9d;content:"\0002f"}html.theme--documenter-dark .breadcrumb ul,html.theme--documenter-dark .breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}html.theme--documenter-dark .breadcrumb .icon:first-child{margin-right:.5em}html.theme--documenter-dark .breadcrumb .icon:last-child{margin-left:.5em}html.theme--documenter-dark .breadcrumb.is-centered ol,html.theme--documenter-dark .breadcrumb.is-centered ul{justify-content:center}html.theme--documenter-dark .breadcrumb.is-right ol,html.theme--documenter-dark .breadcrumb.is-right ul{justify-content:flex-end}html.theme--documenter-dark .breadcrumb.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}html.theme--documenter-dark .breadcrumb.is-medium{font-size:1.25rem}html.theme--documenter-dark .breadcrumb.is-large{font-size:1.5rem}html.theme--documenter-dark .breadcrumb.has-arrow-separator li+li::before{content:"\02192"}html.theme--documenter-dark .breadcrumb.has-bullet-separator li+li::before{content:"\02022"}html.theme--documenter-dark .breadcrumb.has-dot-separator li+li::before{content:"\000b7"}html.theme--documenter-dark .breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}html.theme--documenter-dark .card{background-color:#fff;border-radius:.25rem;box-shadow:#171717;color:#fff;max-width:100%;position:relative}html.theme--documenter-dark .card-footer:first-child,html.theme--documenter-dark .card-content:first-child,html.theme--documenter-dark .card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-footer:last-child,html.theme--documenter-dark .card-content:last-child,html.theme--documenter-dark .card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}html.theme--documenter-dark .card-header-title{align-items:center;color:#f2f2f2;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}html.theme--documenter-dark .card-header-title.is-centered{justify-content:center}html.theme--documenter-dark .card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}html.theme--documenter-dark .card-image{display:block;position:relative}html.theme--documenter-dark .card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}html.theme--documenter-dark .card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}html.theme--documenter-dark .card-content{background-color:rgba(0,0,0,0);padding:1.5rem}html.theme--documenter-dark .card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}html.theme--documenter-dark .card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}html.theme--documenter-dark .card-footer-item:not(:last-child){border-right:1px solid #ededed}html.theme--documenter-dark .card .media:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .dropdown{display:inline-flex;position:relative;vertical-align:top}html.theme--documenter-dark .dropdown.is-active .dropdown-menu,html.theme--documenter-dark .dropdown.is-hoverable:hover .dropdown-menu{display:block}html.theme--documenter-dark .dropdown.is-right .dropdown-menu{left:auto;right:0}html.theme--documenter-dark .dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}html.theme--documenter-dark .dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .dropdown-content{background-color:#282f2f;border-radius:.4em;box-shadow:#171717;padding-bottom:.5rem;padding-top:.5rem}html.theme--documenter-dark .dropdown-item{color:#fff;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}html.theme--documenter-dark a.dropdown-item,html.theme--documenter-dark button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}html.theme--documenter-dark a.dropdown-item:hover,html.theme--documenter-dark button.dropdown-item:hover{background-color:#282f2f;color:#0a0a0a}html.theme--documenter-dark a.dropdown-item.is-active,html.theme--documenter-dark button.dropdown-item.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}html.theme--documenter-dark .level{align-items:center;justify-content:space-between}html.theme--documenter-dark .level code{border-radius:.4em}html.theme--documenter-dark .level img{display:inline-block;vertical-align:top}html.theme--documenter-dark .level.is-mobile{display:flex}html.theme--documenter-dark .level.is-mobile .level-left,html.theme--documenter-dark .level.is-mobile .level-right{display:flex}html.theme--documenter-dark .level.is-mobile .level-left+.level-right{margin-top:0}html.theme--documenter-dark .level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}html.theme--documenter-dark .level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level{display:flex}html.theme--documenter-dark .level>.level-item:not(.is-narrow){flex-grow:1}}html.theme--documenter-dark .level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}html.theme--documenter-dark .level-item .title,html.theme--documenter-dark .level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){html.theme--documenter-dark .level-item:not(:last-child){margin-bottom:.75rem}}html.theme--documenter-dark .level-left,html.theme--documenter-dark .level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .level-left .level-item.is-flexible,html.theme--documenter-dark .level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left .level-item:not(:last-child),html.theme--documenter-dark .level-right .level-item:not(:last-child){margin-right:.75rem}}html.theme--documenter-dark .level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){html.theme--documenter-dark .level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-left{display:flex}}html.theme--documenter-dark .level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{html.theme--documenter-dark .level-right{display:flex}}html.theme--documenter-dark .media{align-items:flex-start;display:flex;text-align:inherit}html.theme--documenter-dark .media .content:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .media .media{border-top:1px solid rgba(94,109,111,0.5);display:flex;padding-top:.75rem}html.theme--documenter-dark .media .media .content:not(:last-child),html.theme--documenter-dark .media .media .control:not(:last-child){margin-bottom:.5rem}html.theme--documenter-dark .media .media .media{padding-top:.5rem}html.theme--documenter-dark .media .media .media+.media{margin-top:.5rem}html.theme--documenter-dark .media+.media{border-top:1px solid rgba(94,109,111,0.5);margin-top:1rem;padding-top:1rem}html.theme--documenter-dark .media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}html.theme--documenter-dark .media-left,html.theme--documenter-dark .media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}html.theme--documenter-dark .media-left{margin-right:1rem}html.theme--documenter-dark .media-right{margin-left:1rem}html.theme--documenter-dark .media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){html.theme--documenter-dark .media-content{overflow-x:auto}}html.theme--documenter-dark .menu{font-size:1rem}html.theme--documenter-dark .menu.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}html.theme--documenter-dark .menu.is-medium{font-size:1.25rem}html.theme--documenter-dark .menu.is-large{font-size:1.5rem}html.theme--documenter-dark .menu-list{line-height:1.25}html.theme--documenter-dark .menu-list a{border-radius:3px;color:#fff;display:block;padding:0.5em 0.75em}html.theme--documenter-dark .menu-list a:hover{background-color:#282f2f;color:#f2f2f2}html.theme--documenter-dark .menu-list a.is-active{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .menu-list li ul{border-left:1px solid #5e6d6f;margin:.75em;padding-left:.75em}html.theme--documenter-dark .menu-label{color:#fff;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}html.theme--documenter-dark .menu-label:not(:first-child){margin-top:1em}html.theme--documenter-dark .menu-label:not(:last-child){margin-bottom:1em}html.theme--documenter-dark .message{background-color:#282f2f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .message strong{color:currentColor}html.theme--documenter-dark .message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}html.theme--documenter-dark .message.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}html.theme--documenter-dark .message.is-medium{font-size:1.25rem}html.theme--documenter-dark .message.is-large{font-size:1.5rem}html.theme--documenter-dark .message.is-white{background-color:#fff}html.theme--documenter-dark .message.is-white .message-header{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .message.is-white .message-body{border-color:#fff}html.theme--documenter-dark .message.is-black{background-color:#fafafa}html.theme--documenter-dark .message.is-black .message-header{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .message.is-black .message-body{border-color:#0a0a0a}html.theme--documenter-dark .message.is-light{background-color:#f9fafb}html.theme--documenter-dark .message.is-light .message-header{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .message.is-light .message-body{border-color:#ecf0f1}html.theme--documenter-dark .message.is-dark,html.theme--documenter-dark .content kbd.message{background-color:#f9fafa}html.theme--documenter-dark .message.is-dark .message-header,html.theme--documenter-dark .content kbd.message .message-header{background-color:#282f2f;color:#fff}html.theme--documenter-dark .message.is-dark .message-body,html.theme--documenter-dark .content kbd.message .message-body{border-color:#282f2f}html.theme--documenter-dark .message.is-primary,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink{background-color:#f1f5f9}html.theme--documenter-dark .message.is-primary .message-header,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-header{background-color:#375a7f;color:#fff}html.theme--documenter-dark .message.is-primary .message-body,html.theme--documenter-dark .docstring>section>a.message.docs-sourcelink .message-body{border-color:#375a7f;color:#4d7eb2}html.theme--documenter-dark .message.is-link{background-color:#edfdf9}html.theme--documenter-dark .message.is-link .message-header{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .message.is-link .message-body{border-color:#1abc9c;color:#15987e}html.theme--documenter-dark .message.is-info{background-color:#ebf7ff}html.theme--documenter-dark .message.is-info .message-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .message.is-info .message-body{border-color:#024c7d;color:#0e9dfb}html.theme--documenter-dark .message.is-success{background-color:#ebfff3}html.theme--documenter-dark .message.is-success .message-header{background-color:#008438;color:#fff}html.theme--documenter-dark .message.is-success .message-body{border-color:#008438;color:#00eb64}html.theme--documenter-dark .message.is-warning{background-color:#fffaeb}html.theme--documenter-dark .message.is-warning .message-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .message.is-warning .message-body{border-color:#ad8100;color:#d19c00}html.theme--documenter-dark .message.is-danger{background-color:#fdeeec}html.theme--documenter-dark .message.is-danger .message-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .message.is-danger .message-body{border-color:#9e1b0d;color:#ec311d}html.theme--documenter-dark .message-header{align-items:center;background-color:#fff;border-radius:.4em .4em 0 0;color:rgba(0,0,0,0.7);display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}html.theme--documenter-dark .message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}html.theme--documenter-dark .message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}html.theme--documenter-dark .message-body{border-color:#5e6d6f;border-radius:.4em;border-style:solid;border-width:0 0 0 4px;color:#fff;padding:1.25em 1.5em}html.theme--documenter-dark .message-body code,html.theme--documenter-dark .message-body pre{background-color:#fff}html.theme--documenter-dark .message-body pre code{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}html.theme--documenter-dark .modal.is-active{display:flex}html.theme--documenter-dark .modal-background{background-color:rgba(10,10,10,0.86)}html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){html.theme--documenter-dark .modal-content,html.theme--documenter-dark .modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}html.theme--documenter-dark .modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}html.theme--documenter-dark .modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}html.theme--documenter-dark .modal-card-head,html.theme--documenter-dark .modal-card-foot{align-items:center;background-color:#282f2f;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}html.theme--documenter-dark .modal-card-head{border-bottom:1px solid #5e6d6f;border-top-left-radius:8px;border-top-right-radius:8px}html.theme--documenter-dark .modal-card-title{color:#f2f2f2;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}html.theme--documenter-dark .modal-card-foot{border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid #5e6d6f}html.theme--documenter-dark .modal-card-foot .button:not(:last-child){margin-right:.5em}html.theme--documenter-dark .modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}html.theme--documenter-dark .navbar{background-color:#375a7f;min-height:4rem;position:relative;z-index:30}html.theme--documenter-dark .navbar.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-white .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-white .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}html.theme--documenter-dark .navbar.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-black .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-black .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}html.theme--documenter-dark .navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}html.theme--documenter-dark .navbar.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-light .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-light .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}}html.theme--documenter-dark .navbar.is-dark,html.theme--documenter-dark .content kbd.navbar{background-color:#282f2f;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-brand .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-burger,html.theme--documenter-dark .content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-dark .navbar-start>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-end>.navbar-item,html.theme--documenter-dark .content kbd.navbar .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:focus,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link:hover,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-start .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-dark .navbar-end .navbar-link::after,html.theme--documenter-dark .content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1d2122;color:#fff}html.theme--documenter-dark .navbar.is-dark .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#282f2f;color:#fff}}html.theme--documenter-dark .navbar.is-primary,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-brand .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-burger,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-primary .navbar-start>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-end>.navbar-item,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:focus,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-start .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-primary .navbar-end .navbar-link::after,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#375a7f;color:#fff}}html.theme--documenter-dark .navbar.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-link .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-link .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#17a689;color:#fff}html.theme--documenter-dark .navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c;color:#fff}}html.theme--documenter-dark .navbar.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-info .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-info .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#023d64;color:#fff}html.theme--documenter-dark .navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#024c7d;color:#fff}}html.theme--documenter-dark .navbar.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-success .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-success .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#006b2d;color:#fff}html.theme--documenter-dark .navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#008438;color:#fff}}html.theme--documenter-dark .navbar.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-warning .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-warning .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#946e00;color:#fff}html.theme--documenter-dark .navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ad8100;color:#fff}}html.theme--documenter-dark .navbar.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar.is-danger .navbar-start>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-end>.navbar-item,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link{color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end>a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:focus,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link:hover,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-start .navbar-link::after,html.theme--documenter-dark .navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#86170b;color:#fff}html.theme--documenter-dark .navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#9e1b0d;color:#fff}}html.theme--documenter-dark .navbar>.container{align-items:stretch;display:flex;min-height:4rem;width:100%}html.theme--documenter-dark .navbar.has-shadow{box-shadow:0 2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-bottom,html.theme--documenter-dark .navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #282f2f}html.theme--documenter-dark .navbar.is-fixed-top{top:0}html.theme--documenter-dark html.has-navbar-fixed-top,html.theme--documenter-dark body.has-navbar-fixed-top{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom,html.theme--documenter-dark body.has-navbar-fixed-bottom{padding-bottom:4rem}html.theme--documenter-dark .navbar-brand,html.theme--documenter-dark .navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:4rem}html.theme--documenter-dark .navbar-brand a.navbar-item:focus,html.theme--documenter-dark .navbar-brand a.navbar-item:hover{background-color:transparent}html.theme--documenter-dark .navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}html.theme--documenter-dark .navbar-burger{color:#fff;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:4rem;position:relative;width:4rem;margin-left:auto}html.theme--documenter-dark .navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}html.theme--documenter-dark .navbar-burger span:nth-child(1){top:calc(50% - 6px)}html.theme--documenter-dark .navbar-burger span:nth-child(2){top:calc(50% - 1px)}html.theme--documenter-dark .navbar-burger span:nth-child(3){top:calc(50% + 4px)}html.theme--documenter-dark .navbar-burger:hover{background-color:rgba(0,0,0,0.05)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(2){opacity:0}html.theme--documenter-dark .navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}html.theme--documenter-dark .navbar-menu{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{color:#fff;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}html.theme--documenter-dark .navbar-item .icon:only-child,html.theme--documenter-dark .navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}html.theme--documenter-dark a.navbar-item,html.theme--documenter-dark .navbar-link{cursor:pointer}html.theme--documenter-dark a.navbar-item:focus,html.theme--documenter-dark a.navbar-item:focus-within,html.theme--documenter-dark a.navbar-item:hover,html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link:focus,html.theme--documenter-dark .navbar-link:focus-within,html.theme--documenter-dark .navbar-link:hover,html.theme--documenter-dark .navbar-link.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-item{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .navbar-item img{max-height:1.75rem}html.theme--documenter-dark .navbar-item.has-dropdown{padding:0}html.theme--documenter-dark .navbar-item.is-expanded{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-item.is-tab{border-bottom:1px solid transparent;min-height:4rem;padding-bottom:calc(0.5rem - 1px)}html.theme--documenter-dark .navbar-item.is-tab:focus,html.theme--documenter-dark .navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c}html.theme--documenter-dark .navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#1abc9c;border-bottom-style:solid;border-bottom-width:3px;color:#1abc9c;padding-bottom:calc(0.5rem - 3px)}html.theme--documenter-dark .navbar-content{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .navbar-link:not(.is-arrowless){padding-right:2.5em}html.theme--documenter-dark .navbar-link:not(.is-arrowless)::after{border-color:#fff;margin-top:-0.375em;right:1.125em}html.theme--documenter-dark .navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}html.theme--documenter-dark .navbar-divider{background-color:rgba(0,0,0,0.2);border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar>.container{display:block}html.theme--documenter-dark .navbar-brand .navbar-item,html.theme--documenter-dark .navbar-tabs .navbar-item{align-items:center;display:flex}html.theme--documenter-dark .navbar-link::after{display:none}html.theme--documenter-dark .navbar-menu{background-color:#375a7f;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}html.theme--documenter-dark .navbar-menu.is-active{display:block}html.theme--documenter-dark .navbar.is-fixed-bottom-touch,html.theme--documenter-dark .navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-touch{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-touch{top:0}html.theme--documenter-dark .navbar.is-fixed-top .navbar-menu,html.theme--documenter-dark .navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 4rem);overflow:auto}html.theme--documenter-dark html.has-navbar-fixed-top-touch,html.theme--documenter-dark body.has-navbar-fixed-top-touch{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-touch,html.theme--documenter-dark body.has-navbar-fixed-bottom-touch{padding-bottom:4rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .navbar,html.theme--documenter-dark .navbar-menu,html.theme--documenter-dark .navbar-start,html.theme--documenter-dark .navbar-end{align-items:stretch;display:flex}html.theme--documenter-dark .navbar{min-height:4rem}html.theme--documenter-dark .navbar.is-spaced{padding:1rem 2rem}html.theme--documenter-dark .navbar.is-spaced .navbar-start,html.theme--documenter-dark .navbar.is-spaced .navbar-end{align-items:center}html.theme--documenter-dark .navbar.is-spaced a.navbar-item,html.theme--documenter-dark .navbar.is-spaced .navbar-link{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent a.navbar-item:hover,html.theme--documenter-dark .navbar.is-transparent a.navbar-item.is-active,html.theme--documenter-dark .navbar.is-transparent .navbar-link:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-link:hover,html.theme--documenter-dark .navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,html.theme--documenter-dark .navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}html.theme--documenter-dark .navbar-burger{display:none}html.theme--documenter-dark .navbar-item,html.theme--documenter-dark .navbar-link{align-items:center;display:flex}html.theme--documenter-dark .navbar-item.has-dropdown{align-items:stretch}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}html.theme--documenter-dark .navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:1px solid rgba(0,0,0,0.2);border-radius:8px 8px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown,html.theme--documenter-dark .navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}html.theme--documenter-dark .navbar-menu{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .navbar-start{justify-content:flex-start;margin-right:auto}html.theme--documenter-dark .navbar-end{justify-content:flex-end;margin-left:auto}html.theme--documenter-dark .navbar-dropdown{background-color:#375a7f;border-bottom-left-radius:8px;border-bottom-right-radius:8px;border-top:1px solid rgba(0,0,0,0.2);box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}html.theme--documenter-dark .navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}html.theme--documenter-dark .navbar-dropdown a.navbar-item{padding-right:3rem}html.theme--documenter-dark .navbar-dropdown a.navbar-item:focus,html.theme--documenter-dark .navbar-dropdown a.navbar-item:hover{background-color:rgba(0,0,0,0);color:#dbdee0}html.theme--documenter-dark .navbar-dropdown a.navbar-item.is-active{background-color:rgba(0,0,0,0);color:#1abc9c}.navbar.is-spaced html.theme--documenter-dark .navbar-dropdown,html.theme--documenter-dark .navbar-dropdown.is-boxed{border-radius:8px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}html.theme--documenter-dark .navbar-dropdown.is-right{left:auto;right:0}html.theme--documenter-dark .navbar-divider{display:block}html.theme--documenter-dark .navbar>.container .navbar-brand,html.theme--documenter-dark .container>.navbar .navbar-brand{margin-left:-.75rem}html.theme--documenter-dark .navbar>.container .navbar-menu,html.theme--documenter-dark .container>.navbar .navbar-menu{margin-right:-.75rem}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop,html.theme--documenter-dark .navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop{bottom:0}html.theme--documenter-dark .navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}html.theme--documenter-dark .navbar.is-fixed-top-desktop{top:0}html.theme--documenter-dark html.has-navbar-fixed-top-desktop,html.theme--documenter-dark body.has-navbar-fixed-top-desktop{padding-top:4rem}html.theme--documenter-dark html.has-navbar-fixed-bottom-desktop,html.theme--documenter-dark body.has-navbar-fixed-bottom-desktop{padding-bottom:4rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-top,html.theme--documenter-dark body.has-spaced-navbar-fixed-top{padding-top:6rem}html.theme--documenter-dark html.has-spaced-navbar-fixed-bottom,html.theme--documenter-dark body.has-spaced-navbar-fixed-bottom{padding-bottom:6rem}html.theme--documenter-dark a.navbar-item.is-active,html.theme--documenter-dark .navbar-link.is-active{color:#1abc9c}html.theme--documenter-dark a.navbar-item.is-active:not(:focus):not(:hover),html.theme--documenter-dark .navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}html.theme--documenter-dark .navbar-item.has-dropdown:focus .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown:hover .navbar-link,html.theme--documenter-dark .navbar-item.has-dropdown.is-active .navbar-link{background-color:rgba(0,0,0,0)}}html.theme--documenter-dark .hero.is-fullheight-with-navbar{min-height:calc(100vh - 4rem)}html.theme--documenter-dark .pagination{font-size:1rem;margin:-.25rem}html.theme--documenter-dark .pagination.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}html.theme--documenter-dark .pagination.is-medium{font-size:1.25rem}html.theme--documenter-dark .pagination.is-large{font-size:1.5rem}html.theme--documenter-dark .pagination.is-rounded .pagination-previous,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,html.theme--documenter-dark .pagination.is-rounded .pagination-next,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}html.theme--documenter-dark .pagination.is-rounded .pagination-link,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}html.theme--documenter-dark .pagination,html.theme--documenter-dark .pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link{border-color:#5e6d6f;color:#1abc9c;min-width:2.5em}html.theme--documenter-dark .pagination-previous:hover,html.theme--documenter-dark .pagination-next:hover,html.theme--documenter-dark .pagination-link:hover{border-color:#8c9b9d;color:#1dd2af}html.theme--documenter-dark .pagination-previous:focus,html.theme--documenter-dark .pagination-next:focus,html.theme--documenter-dark .pagination-link:focus{border-color:#8c9b9d}html.theme--documenter-dark .pagination-previous:active,html.theme--documenter-dark .pagination-next:active,html.theme--documenter-dark .pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}html.theme--documenter-dark .pagination-previous[disabled],html.theme--documenter-dark .pagination-previous.is-disabled,html.theme--documenter-dark .pagination-next[disabled],html.theme--documenter-dark .pagination-next.is-disabled,html.theme--documenter-dark .pagination-link[disabled],html.theme--documenter-dark .pagination-link.is-disabled{background-color:#5e6d6f;border-color:#5e6d6f;box-shadow:none;color:#fff;opacity:0.5}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}html.theme--documenter-dark .pagination-link.is-current{background-color:#1abc9c;border-color:#1abc9c;color:#fff}html.theme--documenter-dark .pagination-ellipsis{color:#8c9b9d;pointer-events:none}html.theme--documenter-dark .pagination-list{flex-wrap:wrap}html.theme--documenter-dark .pagination-list li{list-style:none}@media screen and (max-width: 768px){html.theme--documenter-dark .pagination{flex-wrap:wrap}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-ellipsis{margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination-previous{order:2}html.theme--documenter-dark .pagination-next{order:3}html.theme--documenter-dark .pagination{justify-content:space-between;margin-bottom:0;margin-top:0}html.theme--documenter-dark .pagination.is-centered .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-centered .pagination-list{justify-content:center;order:2}html.theme--documenter-dark .pagination.is-centered .pagination-next{order:3}html.theme--documenter-dark .pagination.is-right .pagination-previous{order:1}html.theme--documenter-dark .pagination.is-right .pagination-next{order:2}html.theme--documenter-dark .pagination.is-right .pagination-list{justify-content:flex-end;order:3}}html.theme--documenter-dark .panel{border-radius:8px;box-shadow:#171717;font-size:1rem}html.theme--documenter-dark .panel:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}html.theme--documenter-dark .panel.is-white .panel-block.is-active .panel-icon{color:#fff}html.theme--documenter-dark .panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}html.theme--documenter-dark .panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}html.theme--documenter-dark .panel.is-light .panel-heading{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .panel.is-light .panel-tabs a.is-active{border-bottom-color:#ecf0f1}html.theme--documenter-dark .panel.is-light .panel-block.is-active .panel-icon{color:#ecf0f1}html.theme--documenter-dark .panel.is-dark .panel-heading,html.theme--documenter-dark .content kbd.panel .panel-heading{background-color:#282f2f;color:#fff}html.theme--documenter-dark .panel.is-dark .panel-tabs a.is-active,html.theme--documenter-dark .content kbd.panel .panel-tabs a.is-active{border-bottom-color:#282f2f}html.theme--documenter-dark .panel.is-dark .panel-block.is-active .panel-icon,html.theme--documenter-dark .content kbd.panel .panel-block.is-active .panel-icon{color:#282f2f}html.theme--documenter-dark .panel.is-primary .panel-heading,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#375a7f;color:#fff}html.theme--documenter-dark .panel.is-primary .panel-tabs a.is-active,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#375a7f}html.theme--documenter-dark .panel.is-primary .panel-block.is-active .panel-icon,html.theme--documenter-dark .docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#375a7f}html.theme--documenter-dark .panel.is-link .panel-heading{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .panel.is-link .panel-tabs a.is-active{border-bottom-color:#1abc9c}html.theme--documenter-dark .panel.is-link .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel.is-info .panel-heading{background-color:#024c7d;color:#fff}html.theme--documenter-dark .panel.is-info .panel-tabs a.is-active{border-bottom-color:#024c7d}html.theme--documenter-dark .panel.is-info .panel-block.is-active .panel-icon{color:#024c7d}html.theme--documenter-dark .panel.is-success .panel-heading{background-color:#008438;color:#fff}html.theme--documenter-dark .panel.is-success .panel-tabs a.is-active{border-bottom-color:#008438}html.theme--documenter-dark .panel.is-success .panel-block.is-active .panel-icon{color:#008438}html.theme--documenter-dark .panel.is-warning .panel-heading{background-color:#ad8100;color:#fff}html.theme--documenter-dark .panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ad8100}html.theme--documenter-dark .panel.is-warning .panel-block.is-active .panel-icon{color:#ad8100}html.theme--documenter-dark .panel.is-danger .panel-heading{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .panel.is-danger .panel-tabs a.is-active{border-bottom-color:#9e1b0d}html.theme--documenter-dark .panel.is-danger .panel-block.is-active .panel-icon{color:#9e1b0d}html.theme--documenter-dark .panel-tabs:not(:last-child),html.theme--documenter-dark .panel-block:not(:last-child){border-bottom:1px solid #ededed}html.theme--documenter-dark .panel-heading{background-color:#343c3d;border-radius:8px 8px 0 0;color:#f2f2f2;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}html.theme--documenter-dark .panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}html.theme--documenter-dark .panel-tabs a{border-bottom:1px solid #5e6d6f;margin-bottom:-1px;padding:0.5em}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#343c3d;color:#17a689}html.theme--documenter-dark .panel-list a{color:#fff}html.theme--documenter-dark .panel-list a:hover{color:#1abc9c}html.theme--documenter-dark .panel-block{align-items:center;color:#f2f2f2;display:flex;justify-content:flex-start;padding:0.5em 0.75em}html.theme--documenter-dark .panel-block input[type="checkbox"]{margin-right:.75em}html.theme--documenter-dark .panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}html.theme--documenter-dark .panel-block.is-wrapped{flex-wrap:wrap}html.theme--documenter-dark .panel-block.is-active{border-left-color:#1abc9c;color:#17a689}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#1abc9c}html.theme--documenter-dark .panel-block:last-child{border-bottom-left-radius:8px;border-bottom-right-radius:8px}html.theme--documenter-dark a.panel-block,html.theme--documenter-dark label.panel-block{cursor:pointer}html.theme--documenter-dark a.panel-block:hover,html.theme--documenter-dark label.panel-block:hover{background-color:#282f2f}html.theme--documenter-dark .panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#fff;margin-right:.75em}html.theme--documenter-dark .panel-icon .fa{font-size:inherit;line-height:inherit}html.theme--documenter-dark .tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}html.theme--documenter-dark .tabs a{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;color:#fff;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}html.theme--documenter-dark .tabs a:hover{border-bottom-color:#f2f2f2;color:#f2f2f2}html.theme--documenter-dark .tabs li{display:block}html.theme--documenter-dark .tabs li.is-active a{border-bottom-color:#1abc9c;color:#1abc9c}html.theme--documenter-dark .tabs ul{align-items:center;border-bottom-color:#5e6d6f;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}html.theme--documenter-dark .tabs ul.is-left{padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}html.theme--documenter-dark .tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}html.theme--documenter-dark .tabs .icon:first-child{margin-right:.5em}html.theme--documenter-dark .tabs .icon:last-child{margin-left:.5em}html.theme--documenter-dark .tabs.is-centered ul{justify-content:center}html.theme--documenter-dark .tabs.is-right ul{justify-content:flex-end}html.theme--documenter-dark .tabs.is-boxed a{border:1px solid transparent;border-radius:.4em .4em 0 0}html.theme--documenter-dark .tabs.is-boxed a:hover{background-color:#282f2f;border-bottom-color:#5e6d6f}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#fff;border-color:#5e6d6f;border-bottom-color:rgba(0,0,0,0) !important}html.theme--documenter-dark .tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}html.theme--documenter-dark .tabs.is-toggle a{border-color:#5e6d6f;border-style:solid;border-width:1px;margin-bottom:0;position:relative}html.theme--documenter-dark .tabs.is-toggle a:hover{background-color:#282f2f;border-color:#8c9b9d;z-index:2}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .tabs.is-toggle li:first-child a{border-top-left-radius:.4em;border-bottom-left-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li:last-child a{border-top-right-radius:.4em;border-bottom-right-radius:.4em}html.theme--documenter-dark .tabs.is-toggle li.is-active a{background-color:#1abc9c;border-color:#1abc9c;color:#fff;z-index:1}html.theme--documenter-dark .tabs.is-toggle ul{border-bottom:none}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}html.theme--documenter-dark .tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}html.theme--documenter-dark .tabs.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}html.theme--documenter-dark .tabs.is-medium{font-size:1.25rem}html.theme--documenter-dark .tabs.is-large{font-size:1.5rem}html.theme--documenter-dark .column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>html.theme--documenter-dark .column.is-narrow{flex:none;width:unset}.columns.is-mobile>html.theme--documenter-dark .column.is-full{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-half{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-half{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>html.theme--documenter-dark .column.is-0{flex:none;width:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-0{margin-left:0%}.columns.is-mobile>html.theme--documenter-dark .column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-3{flex:none;width:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-3{margin-left:25%}.columns.is-mobile>html.theme--documenter-dark .column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-6{flex:none;width:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-6{margin-left:50%}.columns.is-mobile>html.theme--documenter-dark .column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-9{flex:none;width:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-9{margin-left:75%}.columns.is-mobile>html.theme--documenter-dark .column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>html.theme--documenter-dark .column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>html.theme--documenter-dark .column.is-12{flex:none;width:100%}.columns.is-mobile>html.theme--documenter-dark .column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){html.theme--documenter-dark .column.is-narrow-mobile{flex:none;width:unset}html.theme--documenter-dark .column.is-full-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-mobile{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-mobile{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-mobile{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-mobile{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-mobile{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-mobile{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-mobile{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-mobile{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-mobile{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-mobile{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-mobile{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-mobile{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-mobile{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-mobile{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-mobile{margin-left:80%}html.theme--documenter-dark .column.is-0-mobile{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-mobile{margin-left:0%}html.theme--documenter-dark .column.is-1-mobile{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-mobile{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-mobile{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-mobile{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-mobile{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-mobile{margin-left:25%}html.theme--documenter-dark .column.is-4-mobile{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-mobile{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-mobile{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-mobile{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-mobile{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-mobile{margin-left:50%}html.theme--documenter-dark .column.is-7-mobile{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-mobile{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-mobile{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-mobile{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-mobile{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-mobile{margin-left:75%}html.theme--documenter-dark .column.is-10-mobile{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-mobile{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-mobile{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-mobile{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-mobile{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .column.is-narrow,html.theme--documenter-dark .column.is-narrow-tablet{flex:none;width:unset}html.theme--documenter-dark .column.is-full,html.theme--documenter-dark .column.is-full-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters,html.theme--documenter-dark .column.is-three-quarters-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds,html.theme--documenter-dark .column.is-two-thirds-tablet{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half,html.theme--documenter-dark .column.is-half-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third,html.theme--documenter-dark .column.is-one-third-tablet{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter,html.theme--documenter-dark .column.is-one-quarter-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth,html.theme--documenter-dark .column.is-one-fifth-tablet{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths,html.theme--documenter-dark .column.is-two-fifths-tablet{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths,html.theme--documenter-dark .column.is-three-fifths-tablet{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths,html.theme--documenter-dark .column.is-four-fifths-tablet{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters,html.theme--documenter-dark .column.is-offset-three-quarters-tablet{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds,html.theme--documenter-dark .column.is-offset-two-thirds-tablet{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half,html.theme--documenter-dark .column.is-offset-half-tablet{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third,html.theme--documenter-dark .column.is-offset-one-third-tablet{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter,html.theme--documenter-dark .column.is-offset-one-quarter-tablet{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth,html.theme--documenter-dark .column.is-offset-one-fifth-tablet{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths,html.theme--documenter-dark .column.is-offset-two-fifths-tablet{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths,html.theme--documenter-dark .column.is-offset-three-fifths-tablet{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths,html.theme--documenter-dark .column.is-offset-four-fifths-tablet{margin-left:80%}html.theme--documenter-dark .column.is-0,html.theme--documenter-dark .column.is-0-tablet{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0,html.theme--documenter-dark .column.is-offset-0-tablet{margin-left:0%}html.theme--documenter-dark .column.is-1,html.theme--documenter-dark .column.is-1-tablet{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1,html.theme--documenter-dark .column.is-offset-1-tablet{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2,html.theme--documenter-dark .column.is-2-tablet{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2,html.theme--documenter-dark .column.is-offset-2-tablet{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3,html.theme--documenter-dark .column.is-3-tablet{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3,html.theme--documenter-dark .column.is-offset-3-tablet{margin-left:25%}html.theme--documenter-dark .column.is-4,html.theme--documenter-dark .column.is-4-tablet{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4,html.theme--documenter-dark .column.is-offset-4-tablet{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5,html.theme--documenter-dark .column.is-5-tablet{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5,html.theme--documenter-dark .column.is-offset-5-tablet{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6,html.theme--documenter-dark .column.is-6-tablet{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6,html.theme--documenter-dark .column.is-offset-6-tablet{margin-left:50%}html.theme--documenter-dark .column.is-7,html.theme--documenter-dark .column.is-7-tablet{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7,html.theme--documenter-dark .column.is-offset-7-tablet{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8,html.theme--documenter-dark .column.is-8-tablet{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8,html.theme--documenter-dark .column.is-offset-8-tablet{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9,html.theme--documenter-dark .column.is-9-tablet{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9,html.theme--documenter-dark .column.is-offset-9-tablet{margin-left:75%}html.theme--documenter-dark .column.is-10,html.theme--documenter-dark .column.is-10-tablet{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10,html.theme--documenter-dark .column.is-offset-10-tablet{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11,html.theme--documenter-dark .column.is-11-tablet{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11,html.theme--documenter-dark .column.is-offset-11-tablet{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12,html.theme--documenter-dark .column.is-12-tablet{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12,html.theme--documenter-dark .column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){html.theme--documenter-dark .column.is-narrow-touch{flex:none;width:unset}html.theme--documenter-dark .column.is-full-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-touch{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-touch{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-touch{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-touch{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-touch{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-touch{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-touch{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-touch{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-touch{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-touch{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-touch{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-touch{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-touch{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-touch{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-touch{margin-left:80%}html.theme--documenter-dark .column.is-0-touch{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-touch{margin-left:0%}html.theme--documenter-dark .column.is-1-touch{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-touch{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-touch{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-touch{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-touch{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-touch{margin-left:25%}html.theme--documenter-dark .column.is-4-touch{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-touch{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-touch{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-touch{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-touch{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-touch{margin-left:50%}html.theme--documenter-dark .column.is-7-touch{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-touch{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-touch{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-touch{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-touch{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-touch{margin-left:75%}html.theme--documenter-dark .column.is-10-touch{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-touch{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-touch{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-touch{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-touch{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){html.theme--documenter-dark .column.is-narrow-desktop{flex:none;width:unset}html.theme--documenter-dark .column.is-full-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-desktop{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-desktop{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-desktop{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-desktop{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-desktop{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-desktop{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-desktop{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-desktop{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-desktop{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-desktop{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-desktop{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-desktop{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-desktop{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-desktop{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-desktop{margin-left:80%}html.theme--documenter-dark .column.is-0-desktop{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-desktop{margin-left:0%}html.theme--documenter-dark .column.is-1-desktop{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-desktop{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-desktop{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-desktop{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-desktop{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-desktop{margin-left:25%}html.theme--documenter-dark .column.is-4-desktop{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-desktop{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-desktop{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-desktop{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-desktop{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-desktop{margin-left:50%}html.theme--documenter-dark .column.is-7-desktop{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-desktop{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-desktop{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-desktop{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-desktop{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-desktop{margin-left:75%}html.theme--documenter-dark .column.is-10-desktop{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-desktop{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-desktop{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-desktop{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-desktop{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){html.theme--documenter-dark .column.is-narrow-widescreen{flex:none;width:unset}html.theme--documenter-dark .column.is-full-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-widescreen{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-widescreen{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-widescreen{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-widescreen{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-widescreen{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-widescreen{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-widescreen{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-widescreen{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-widescreen{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-widescreen{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-widescreen{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-widescreen{margin-left:80%}html.theme--documenter-dark .column.is-0-widescreen{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-widescreen{margin-left:0%}html.theme--documenter-dark .column.is-1-widescreen{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-widescreen{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-widescreen{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-widescreen{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-widescreen{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-widescreen{margin-left:25%}html.theme--documenter-dark .column.is-4-widescreen{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-widescreen{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-widescreen{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-widescreen{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-widescreen{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-widescreen{margin-left:50%}html.theme--documenter-dark .column.is-7-widescreen{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-widescreen{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-widescreen{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-widescreen{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-widescreen{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-widescreen{margin-left:75%}html.theme--documenter-dark .column.is-10-widescreen{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-widescreen{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-widescreen{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-widescreen{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-widescreen{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){html.theme--documenter-dark .column.is-narrow-fullhd{flex:none;width:unset}html.theme--documenter-dark .column.is-full-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-three-quarters-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-two-thirds-fullhd{flex:none;width:66.6666%}html.theme--documenter-dark .column.is-half-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-one-third-fullhd{flex:none;width:33.3333%}html.theme--documenter-dark .column.is-one-quarter-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-one-fifth-fullhd{flex:none;width:20%}html.theme--documenter-dark .column.is-two-fifths-fullhd{flex:none;width:40%}html.theme--documenter-dark .column.is-three-fifths-fullhd{flex:none;width:60%}html.theme--documenter-dark .column.is-four-fifths-fullhd{flex:none;width:80%}html.theme--documenter-dark .column.is-offset-three-quarters-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-offset-two-thirds-fullhd{margin-left:66.6666%}html.theme--documenter-dark .column.is-offset-half-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-offset-one-third-fullhd{margin-left:33.3333%}html.theme--documenter-dark .column.is-offset-one-quarter-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-offset-one-fifth-fullhd{margin-left:20%}html.theme--documenter-dark .column.is-offset-two-fifths-fullhd{margin-left:40%}html.theme--documenter-dark .column.is-offset-three-fifths-fullhd{margin-left:60%}html.theme--documenter-dark .column.is-offset-four-fifths-fullhd{margin-left:80%}html.theme--documenter-dark .column.is-0-fullhd{flex:none;width:0%}html.theme--documenter-dark .column.is-offset-0-fullhd{margin-left:0%}html.theme--documenter-dark .column.is-1-fullhd{flex:none;width:8.33333337%}html.theme--documenter-dark .column.is-offset-1-fullhd{margin-left:8.33333337%}html.theme--documenter-dark .column.is-2-fullhd{flex:none;width:16.66666674%}html.theme--documenter-dark .column.is-offset-2-fullhd{margin-left:16.66666674%}html.theme--documenter-dark .column.is-3-fullhd{flex:none;width:25%}html.theme--documenter-dark .column.is-offset-3-fullhd{margin-left:25%}html.theme--documenter-dark .column.is-4-fullhd{flex:none;width:33.33333337%}html.theme--documenter-dark .column.is-offset-4-fullhd{margin-left:33.33333337%}html.theme--documenter-dark .column.is-5-fullhd{flex:none;width:41.66666674%}html.theme--documenter-dark .column.is-offset-5-fullhd{margin-left:41.66666674%}html.theme--documenter-dark .column.is-6-fullhd{flex:none;width:50%}html.theme--documenter-dark .column.is-offset-6-fullhd{margin-left:50%}html.theme--documenter-dark .column.is-7-fullhd{flex:none;width:58.33333337%}html.theme--documenter-dark .column.is-offset-7-fullhd{margin-left:58.33333337%}html.theme--documenter-dark .column.is-8-fullhd{flex:none;width:66.66666674%}html.theme--documenter-dark .column.is-offset-8-fullhd{margin-left:66.66666674%}html.theme--documenter-dark .column.is-9-fullhd{flex:none;width:75%}html.theme--documenter-dark .column.is-offset-9-fullhd{margin-left:75%}html.theme--documenter-dark .column.is-10-fullhd{flex:none;width:83.33333337%}html.theme--documenter-dark .column.is-offset-10-fullhd{margin-left:83.33333337%}html.theme--documenter-dark .column.is-11-fullhd{flex:none;width:91.66666674%}html.theme--documenter-dark .column.is-offset-11-fullhd{margin-left:91.66666674%}html.theme--documenter-dark .column.is-12-fullhd{flex:none;width:100%}html.theme--documenter-dark .column.is-offset-12-fullhd{margin-left:100%}}html.theme--documenter-dark .columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .columns:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}html.theme--documenter-dark .columns.is-centered{justify-content:center}html.theme--documenter-dark .columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}html.theme--documenter-dark .columns.is-gapless>.column{margin:0;padding:0 !important}html.theme--documenter-dark .columns.is-gapless:not(:last-child){margin-bottom:1.5rem}html.theme--documenter-dark .columns.is-gapless:last-child{margin-bottom:0}html.theme--documenter-dark .columns.is-mobile{display:flex}html.theme--documenter-dark .columns.is-multiline{flex-wrap:wrap}html.theme--documenter-dark .columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-desktop{display:flex}}html.theme--documenter-dark .columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}html.theme--documenter-dark .columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}html.theme--documenter-dark .columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-0-fullhd{--columnGap: 0rem}}html.theme--documenter-dark .columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-1-fullhd{--columnGap: .25rem}}html.theme--documenter-dark .columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-2-fullhd{--columnGap: .5rem}}html.theme--documenter-dark .columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-3-fullhd{--columnGap: .75rem}}html.theme--documenter-dark .columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-4-fullhd{--columnGap: 1rem}}html.theme--documenter-dark .columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}html.theme--documenter-dark .columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}html.theme--documenter-dark .columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}html.theme--documenter-dark .columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){html.theme--documenter-dark .columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark .columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){html.theme--documenter-dark .columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){html.theme--documenter-dark .columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){html.theme--documenter-dark .columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){html.theme--documenter-dark .columns.is-variable.is-8-fullhd{--columnGap: 2rem}}html.theme--documenter-dark .tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}html.theme--documenter-dark .tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}html.theme--documenter-dark .tile.is-ancestor:last-child{margin-bottom:-.75rem}html.theme--documenter-dark .tile.is-ancestor:not(:last-child){margin-bottom:.75rem}html.theme--documenter-dark .tile.is-child{margin:0 !important}html.theme--documenter-dark .tile.is-parent{padding:.75rem}html.theme--documenter-dark .tile.is-vertical{flex-direction:column}html.theme--documenter-dark .tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{html.theme--documenter-dark .tile:not(.is-child){display:flex}html.theme--documenter-dark .tile.is-1{flex:none;width:8.33333337%}html.theme--documenter-dark .tile.is-2{flex:none;width:16.66666674%}html.theme--documenter-dark .tile.is-3{flex:none;width:25%}html.theme--documenter-dark .tile.is-4{flex:none;width:33.33333337%}html.theme--documenter-dark .tile.is-5{flex:none;width:41.66666674%}html.theme--documenter-dark .tile.is-6{flex:none;width:50%}html.theme--documenter-dark .tile.is-7{flex:none;width:58.33333337%}html.theme--documenter-dark .tile.is-8{flex:none;width:66.66666674%}html.theme--documenter-dark .tile.is-9{flex:none;width:75%}html.theme--documenter-dark .tile.is-10{flex:none;width:83.33333337%}html.theme--documenter-dark .tile.is-11{flex:none;width:91.66666674%}html.theme--documenter-dark .tile.is-12{flex:none;width:100%}}html.theme--documenter-dark .hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}html.theme--documenter-dark .hero .navbar{background:none}html.theme--documenter-dark .hero .tabs ul{border-bottom:none}html.theme--documenter-dark .hero.is-white{background-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-white strong{color:inherit}html.theme--documenter-dark .hero.is-white .title{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .subtitle{color:rgba(10,10,10,0.9)}html.theme--documenter-dark .hero.is-white .subtitle a:not(.button),html.theme--documenter-dark .hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-white .navbar-menu{background-color:#fff}}html.theme--documenter-dark .hero.is-white .navbar-item,html.theme--documenter-dark .hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}html.theme--documenter-dark .hero.is-white a.navbar-item:hover,html.theme--documenter-dark .hero.is-white a.navbar-item.is-active,html.theme--documenter-dark .hero.is-white .navbar-link:hover,html.theme--documenter-dark .hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}html.theme--documenter-dark .hero.is-white .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a{color:#0a0a0a}html.theme--documenter-dark .hero.is-white .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}html.theme--documenter-dark .hero.is-black{background-color:#0a0a0a;color:#fff}html.theme--documenter-dark .hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-black strong{color:inherit}html.theme--documenter-dark .hero.is-black .title{color:#fff}html.theme--documenter-dark .hero.is-black .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-black .subtitle a:not(.button),html.theme--documenter-dark .hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-black .navbar-menu{background-color:#0a0a0a}}html.theme--documenter-dark .hero.is-black .navbar-item,html.theme--documenter-dark .hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-black a.navbar-item:hover,html.theme--documenter-dark .hero.is-black a.navbar-item.is-active,html.theme--documenter-dark .hero.is-black .navbar-link:hover,html.theme--documenter-dark .hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}html.theme--documenter-dark .hero.is-black .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-black .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-black .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}html.theme--documenter-dark .hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}html.theme--documenter-dark .hero.is-light{background-color:#ecf0f1;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-light strong{color:inherit}html.theme--documenter-dark .hero.is-light .title{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .subtitle{color:rgba(0,0,0,0.9)}html.theme--documenter-dark .hero.is-light .subtitle a:not(.button),html.theme--documenter-dark .hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-light .navbar-menu{background-color:#ecf0f1}}html.theme--documenter-dark .hero.is-light .navbar-item,html.theme--documenter-dark .hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light a.navbar-item:hover,html.theme--documenter-dark .hero.is-light a.navbar-item.is-active,html.theme--documenter-dark .hero.is-light .navbar-link:hover,html.theme--documenter-dark .hero.is-light .navbar-link.is-active{background-color:#dde4e6;color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}html.theme--documenter-dark .hero.is-light .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-light .tabs li.is-active a{color:#ecf0f1 !important;opacity:1}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ecf0f1}html.theme--documenter-dark .hero.is-light.is-bold{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #cadfe0 0%, #ecf0f1 71%, #fafbfc 100%)}}html.theme--documenter-dark .hero.is-dark,html.theme--documenter-dark .content kbd.hero{background-color:#282f2f;color:#fff}html.theme--documenter-dark .hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-dark strong,html.theme--documenter-dark .content kbd.hero strong{color:inherit}html.theme--documenter-dark .hero.is-dark .title,html.theme--documenter-dark .content kbd.hero .title{color:#fff}html.theme--documenter-dark .hero.is-dark .subtitle,html.theme--documenter-dark .content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-dark .subtitle a:not(.button),html.theme--documenter-dark .content kbd.hero .subtitle a:not(.button),html.theme--documenter-dark .hero.is-dark .subtitle strong,html.theme--documenter-dark .content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-dark .navbar-menu,html.theme--documenter-dark .content kbd.hero .navbar-menu{background-color:#282f2f}}html.theme--documenter-dark .hero.is-dark .navbar-item,html.theme--documenter-dark .content kbd.hero .navbar-item,html.theme--documenter-dark .hero.is-dark .navbar-link,html.theme--documenter-dark .content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-dark a.navbar-item:hover,html.theme--documenter-dark .content kbd.hero a.navbar-item:hover,html.theme--documenter-dark .hero.is-dark a.navbar-item.is-active,html.theme--documenter-dark .content kbd.hero a.navbar-item.is-active,html.theme--documenter-dark .hero.is-dark .navbar-link:hover,html.theme--documenter-dark .content kbd.hero .navbar-link:hover,html.theme--documenter-dark .hero.is-dark .navbar-link.is-active,html.theme--documenter-dark .content kbd.hero .navbar-link.is-active{background-color:#1d2122;color:#fff}html.theme--documenter-dark .hero.is-dark .tabs a,html.theme--documenter-dark .content kbd.hero .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-dark .tabs a:hover,html.theme--documenter-dark .content kbd.hero .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-dark .tabs li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs li.is-active a{color:#282f2f !important;opacity:1}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle a:hover,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a,html.theme--documenter-dark .content kbd.hero .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#282f2f}html.theme--documenter-dark .hero.is-dark.is-bold,html.theme--documenter-dark .content kbd.hero.is-bold{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-dark.is-bold .navbar-menu,html.theme--documenter-dark .content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0f1615 0%, #282f2f 71%, #313c40 100%)}}html.theme--documenter-dark .hero.is-primary,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink{background-color:#375a7f;color:#fff}html.theme--documenter-dark .hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-primary strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink strong{color:inherit}html.theme--documenter-dark .hero.is-primary .title,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .title{color:#fff}html.theme--documenter-dark .hero.is-primary .subtitle,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-primary .subtitle a:not(.button),html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),html.theme--documenter-dark .hero.is-primary .subtitle strong,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-primary .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#375a7f}}html.theme--documenter-dark .hero.is-primary .navbar-item,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-item,html.theme--documenter-dark .hero.is-primary .navbar-link,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-primary a.navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,html.theme--documenter-dark .hero.is-primary a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,html.theme--documenter-dark .hero.is-primary .navbar-link:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link:hover,html.theme--documenter-dark .hero.is-primary .navbar-link.is-active,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#2f4d6d;color:#fff}html.theme--documenter-dark .hero.is-primary .tabs a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-primary .tabs a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-primary .tabs li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#375a7f !important;opacity:1}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle a:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#375a7f}html.theme--documenter-dark .hero.is-primary.is-bold,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-primary.is-bold .navbar-menu,html.theme--documenter-dark .docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #214b62 0%, #375a7f 71%, #3a5796 100%)}}html.theme--documenter-dark .hero.is-link{background-color:#1abc9c;color:#fff}html.theme--documenter-dark .hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-link strong{color:inherit}html.theme--documenter-dark .hero.is-link .title{color:#fff}html.theme--documenter-dark .hero.is-link .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-link .subtitle a:not(.button),html.theme--documenter-dark .hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-link .navbar-menu{background-color:#1abc9c}}html.theme--documenter-dark .hero.is-link .navbar-item,html.theme--documenter-dark .hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-link a.navbar-item:hover,html.theme--documenter-dark .hero.is-link a.navbar-item.is-active,html.theme--documenter-dark .hero.is-link .navbar-link:hover,html.theme--documenter-dark .hero.is-link .navbar-link.is-active{background-color:#17a689;color:#fff}html.theme--documenter-dark .hero.is-link .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-link .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-link .tabs li.is-active a{color:#1abc9c !important;opacity:1}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-link .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#1abc9c}html.theme--documenter-dark .hero.is-link.is-bold{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #0c9764 0%, #1abc9c 71%, #17d8d2 100%)}}html.theme--documenter-dark .hero.is-info{background-color:#024c7d;color:#fff}html.theme--documenter-dark .hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-info strong{color:inherit}html.theme--documenter-dark .hero.is-info .title{color:#fff}html.theme--documenter-dark .hero.is-info .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-info .subtitle a:not(.button),html.theme--documenter-dark .hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-info .navbar-menu{background-color:#024c7d}}html.theme--documenter-dark .hero.is-info .navbar-item,html.theme--documenter-dark .hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-info a.navbar-item:hover,html.theme--documenter-dark .hero.is-info a.navbar-item.is-active,html.theme--documenter-dark .hero.is-info .navbar-link:hover,html.theme--documenter-dark .hero.is-info .navbar-link.is-active{background-color:#023d64;color:#fff}html.theme--documenter-dark .hero.is-info .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-info .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-info .tabs li.is-active a{color:#024c7d !important;opacity:1}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-info .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#024c7d}html.theme--documenter-dark .hero.is-info.is-bold{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #003a4c 0%, #024c7d 71%, #004299 100%)}}html.theme--documenter-dark .hero.is-success{background-color:#008438;color:#fff}html.theme--documenter-dark .hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-success strong{color:inherit}html.theme--documenter-dark .hero.is-success .title{color:#fff}html.theme--documenter-dark .hero.is-success .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-success .subtitle a:not(.button),html.theme--documenter-dark .hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-success .navbar-menu{background-color:#008438}}html.theme--documenter-dark .hero.is-success .navbar-item,html.theme--documenter-dark .hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-success a.navbar-item:hover,html.theme--documenter-dark .hero.is-success a.navbar-item.is-active,html.theme--documenter-dark .hero.is-success .navbar-link:hover,html.theme--documenter-dark .hero.is-success .navbar-link.is-active{background-color:#006b2d;color:#fff}html.theme--documenter-dark .hero.is-success .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-success .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-success .tabs li.is-active a{color:#008438 !important;opacity:1}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-success .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#008438}html.theme--documenter-dark .hero.is-success.is-bold{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #005115 0%, #008438 71%, #009e5d 100%)}}html.theme--documenter-dark .hero.is-warning{background-color:#ad8100;color:#fff}html.theme--documenter-dark .hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-warning strong{color:inherit}html.theme--documenter-dark .hero.is-warning .title{color:#fff}html.theme--documenter-dark .hero.is-warning .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-warning .subtitle a:not(.button),html.theme--documenter-dark .hero.is-warning .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-warning .navbar-menu{background-color:#ad8100}}html.theme--documenter-dark .hero.is-warning .navbar-item,html.theme--documenter-dark .hero.is-warning .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-warning a.navbar-item:hover,html.theme--documenter-dark .hero.is-warning a.navbar-item.is-active,html.theme--documenter-dark .hero.is-warning .navbar-link:hover,html.theme--documenter-dark .hero.is-warning .navbar-link.is-active{background-color:#946e00;color:#fff}html.theme--documenter-dark .hero.is-warning .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-warning .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-warning .tabs li.is-active a{color:#ad8100 !important;opacity:1}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#ad8100}html.theme--documenter-dark .hero.is-warning.is-bold{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #7a4700 0%, #ad8100 71%, #c7b500 100%)}}html.theme--documenter-dark .hero.is-danger{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),html.theme--documenter-dark .hero.is-danger strong{color:inherit}html.theme--documenter-dark .hero.is-danger .title{color:#fff}html.theme--documenter-dark .hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}html.theme--documenter-dark .hero.is-danger .subtitle a:not(.button),html.theme--documenter-dark .hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){html.theme--documenter-dark .hero.is-danger .navbar-menu{background-color:#9e1b0d}}html.theme--documenter-dark .hero.is-danger .navbar-item,html.theme--documenter-dark .hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}html.theme--documenter-dark .hero.is-danger a.navbar-item:hover,html.theme--documenter-dark .hero.is-danger a.navbar-item.is-active,html.theme--documenter-dark .hero.is-danger .navbar-link:hover,html.theme--documenter-dark .hero.is-danger .navbar-link.is-active{background-color:#86170b;color:#fff}html.theme--documenter-dark .hero.is-danger .tabs a{color:#fff;opacity:0.9}html.theme--documenter-dark .hero.is-danger .tabs a:hover{opacity:1}html.theme--documenter-dark .hero.is-danger .tabs li.is-active a{color:#9e1b0d !important;opacity:1}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a{color:#fff}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-boxed li.is-active a:hover,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a,html.theme--documenter-dark .hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#9e1b0d}html.theme--documenter-dark .hero.is-danger.is-bold{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}@media screen and (max-width: 768px){html.theme--documenter-dark .hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #75030b 0%, #9e1b0d 71%, #ba380a 100%)}}html.theme--documenter-dark .hero.is-small .hero-body,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero.is-large .hero-body{padding:18rem 6rem}}html.theme--documenter-dark .hero.is-halfheight .hero-body,html.theme--documenter-dark .hero.is-fullheight .hero-body,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}html.theme--documenter-dark .hero.is-halfheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight .hero-body>.container,html.theme--documenter-dark .hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}html.theme--documenter-dark .hero.is-halfheight{min-height:50vh}html.theme--documenter-dark .hero.is-fullheight{min-height:100vh}html.theme--documenter-dark .hero-video{overflow:hidden}html.theme--documenter-dark .hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}html.theme--documenter-dark .hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-video{display:none}}html.theme--documenter-dark .hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){html.theme--documenter-dark .hero-buttons .button{display:flex}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-buttons{display:flex;justify-content:center}html.theme--documenter-dark .hero-buttons .button:not(:last-child){margin-right:1.5rem}}html.theme--documenter-dark .hero-head,html.theme--documenter-dark .hero-foot{flex-grow:0;flex-shrink:0}html.theme--documenter-dark .hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{html.theme--documenter-dark .hero-body{padding:3rem 3rem}}html.theme--documenter-dark .section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){html.theme--documenter-dark .section{padding:3rem 3rem}html.theme--documenter-dark .section.is-medium{padding:9rem 4.5rem}html.theme--documenter-dark .section.is-large{padding:18rem 6rem}}html.theme--documenter-dark .footer{background-color:#282f2f;padding:3rem 1.5rem 6rem}html.theme--documenter-dark hr{height:1px}html.theme--documenter-dark h6{text-transform:uppercase;letter-spacing:0.5px}html.theme--documenter-dark .hero{background-color:#343c3d}html.theme--documenter-dark a{transition:all 200ms ease}html.theme--documenter-dark .button{transition:all 200ms ease;border-width:1px;color:#fff}html.theme--documenter-dark .button.is-active,html.theme--documenter-dark .button.is-focused,html.theme--documenter-dark .button:active,html.theme--documenter-dark .button:focus{box-shadow:0 0 0 2px rgba(140,155,157,0.5)}html.theme--documenter-dark .button.is-white.is-hovered,html.theme--documenter-dark .button.is-white:hover{background-color:#fff}html.theme--documenter-dark .button.is-white.is-active,html.theme--documenter-dark .button.is-white.is-focused,html.theme--documenter-dark .button.is-white:active,html.theme--documenter-dark .button.is-white:focus{border-color:#fff;box-shadow:0 0 0 2px rgba(255,255,255,0.5)}html.theme--documenter-dark .button.is-black.is-hovered,html.theme--documenter-dark .button.is-black:hover{background-color:#1d1d1d}html.theme--documenter-dark .button.is-black.is-active,html.theme--documenter-dark .button.is-black.is-focused,html.theme--documenter-dark .button.is-black:active,html.theme--documenter-dark .button.is-black:focus{border-color:#0a0a0a;box-shadow:0 0 0 2px rgba(10,10,10,0.5)}html.theme--documenter-dark .button.is-light.is-hovered,html.theme--documenter-dark .button.is-light:hover{background-color:#fff}html.theme--documenter-dark .button.is-light.is-active,html.theme--documenter-dark .button.is-light.is-focused,html.theme--documenter-dark .button.is-light:active,html.theme--documenter-dark .button.is-light:focus{border-color:#ecf0f1;box-shadow:0 0 0 2px rgba(236,240,241,0.5)}html.theme--documenter-dark .button.is-dark.is-hovered,html.theme--documenter-dark .content kbd.button.is-hovered,html.theme--documenter-dark .button.is-dark:hover,html.theme--documenter-dark .content kbd.button:hover{background-color:#3a4344}html.theme--documenter-dark .button.is-dark.is-active,html.theme--documenter-dark .content kbd.button.is-active,html.theme--documenter-dark .button.is-dark.is-focused,html.theme--documenter-dark .content kbd.button.is-focused,html.theme--documenter-dark .button.is-dark:active,html.theme--documenter-dark .content kbd.button:active,html.theme--documenter-dark .button.is-dark:focus,html.theme--documenter-dark .content kbd.button:focus{border-color:#282f2f;box-shadow:0 0 0 2px rgba(40,47,47,0.5)}html.theme--documenter-dark .button.is-primary.is-hovered,html.theme--documenter-dark .docstring>section>a.button.is-hovered.docs-sourcelink,html.theme--documenter-dark .button.is-primary:hover,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:hover{background-color:#436d9a}html.theme--documenter-dark .button.is-primary.is-active,html.theme--documenter-dark .docstring>section>a.button.is-active.docs-sourcelink,html.theme--documenter-dark .button.is-primary.is-focused,html.theme--documenter-dark .docstring>section>a.button.is-focused.docs-sourcelink,html.theme--documenter-dark .button.is-primary:active,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:active,html.theme--documenter-dark .button.is-primary:focus,html.theme--documenter-dark .docstring>section>a.button.docs-sourcelink:focus{border-color:#375a7f;box-shadow:0 0 0 2px rgba(55,90,127,0.5)}html.theme--documenter-dark .button.is-link.is-hovered,html.theme--documenter-dark .button.is-link:hover{background-color:#1fdeb8}html.theme--documenter-dark .button.is-link.is-active,html.theme--documenter-dark .button.is-link.is-focused,html.theme--documenter-dark .button.is-link:active,html.theme--documenter-dark .button.is-link:focus{border-color:#1abc9c;box-shadow:0 0 0 2px rgba(26,188,156,0.5)}html.theme--documenter-dark .button.is-info.is-hovered,html.theme--documenter-dark .button.is-info:hover{background-color:#0363a3}html.theme--documenter-dark .button.is-info.is-active,html.theme--documenter-dark .button.is-info.is-focused,html.theme--documenter-dark .button.is-info:active,html.theme--documenter-dark .button.is-info:focus{border-color:#024c7d;box-shadow:0 0 0 2px rgba(2,76,125,0.5)}html.theme--documenter-dark .button.is-success.is-hovered,html.theme--documenter-dark .button.is-success:hover{background-color:#00aa48}html.theme--documenter-dark .button.is-success.is-active,html.theme--documenter-dark .button.is-success.is-focused,html.theme--documenter-dark .button.is-success:active,html.theme--documenter-dark .button.is-success:focus{border-color:#008438;box-shadow:0 0 0 2px rgba(0,132,56,0.5)}html.theme--documenter-dark .button.is-warning.is-hovered,html.theme--documenter-dark .button.is-warning:hover{background-color:#d39e00}html.theme--documenter-dark .button.is-warning.is-active,html.theme--documenter-dark .button.is-warning.is-focused,html.theme--documenter-dark .button.is-warning:active,html.theme--documenter-dark .button.is-warning:focus{border-color:#ad8100;box-shadow:0 0 0 2px rgba(173,129,0,0.5)}html.theme--documenter-dark .button.is-danger.is-hovered,html.theme--documenter-dark .button.is-danger:hover{background-color:#c12110}html.theme--documenter-dark .button.is-danger.is-active,html.theme--documenter-dark .button.is-danger.is-focused,html.theme--documenter-dark .button.is-danger:active,html.theme--documenter-dark .button.is-danger:focus{border-color:#9e1b0d;box-shadow:0 0 0 2px rgba(158,27,13,0.5)}html.theme--documenter-dark .label{color:#dbdee0}html.theme--documenter-dark .button,html.theme--documenter-dark .control.has-icons-left .icon,html.theme--documenter-dark .control.has-icons-right .icon,html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .pagination-ellipsis,html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous,html.theme--documenter-dark .select,html.theme--documenter-dark .select select,html.theme--documenter-dark .textarea{height:2.5em}html.theme--documenter-dark .input,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark .textarea{transition:all 200ms ease;box-shadow:none;border-width:1px;padding-left:1em;padding-right:1em}html.theme--documenter-dark .select:after,html.theme--documenter-dark .select select{border-width:1px}html.theme--documenter-dark .control.has-addons .button,html.theme--documenter-dark .control.has-addons .input,html.theme--documenter-dark .control.has-addons #documenter .docs-sidebar form.docs-search>input,html.theme--documenter-dark #documenter .docs-sidebar .control.has-addons form.docs-search>input,html.theme--documenter-dark .control.has-addons .select{margin-right:-1px}html.theme--documenter-dark .notification{background-color:#343c3d}html.theme--documenter-dark .card{box-shadow:none;border:1px solid #343c3d;background-color:#282f2f;border-radius:.4em}html.theme--documenter-dark .card .card-image img{border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-header{box-shadow:none;background-color:rgba(18,18,18,0.2);border-radius:.4em .4em 0 0}html.theme--documenter-dark .card .card-footer{background-color:rgba(18,18,18,0.2)}html.theme--documenter-dark .card .card-footer,html.theme--documenter-dark .card .card-footer-item{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .notification.is-white a:not(.button){color:#0a0a0a;text-decoration:underline}html.theme--documenter-dark .notification.is-black a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-light a:not(.button){color:rgba(0,0,0,0.7);text-decoration:underline}html.theme--documenter-dark .notification.is-dark a:not(.button),html.theme--documenter-dark .content kbd.notification a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-primary a:not(.button),html.theme--documenter-dark .docstring>section>a.notification.docs-sourcelink a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-link a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-info a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-success a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-warning a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .notification.is-danger a:not(.button){color:#fff;text-decoration:underline}html.theme--documenter-dark .tag,html.theme--documenter-dark .content kbd,html.theme--documenter-dark .docstring>section>a.docs-sourcelink{border-radius:.4em}html.theme--documenter-dark .menu-list a{transition:all 300ms ease}html.theme--documenter-dark .modal-card-body{background-color:#282f2f}html.theme--documenter-dark .modal-card-foot,html.theme--documenter-dark .modal-card-head{border-color:#343c3d}html.theme--documenter-dark .message-header{font-weight:700;background-color:#343c3d;color:#fff}html.theme--documenter-dark .message-body{border-width:1px;border-color:#343c3d}html.theme--documenter-dark .navbar{border-radius:.4em}html.theme--documenter-dark .navbar.is-transparent{background:none}html.theme--documenter-dark .navbar.is-primary .navbar-dropdown a.navbar-item.is-active,html.theme--documenter-dark .docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#1abc9c}@media screen and (max-width: 1055px){html.theme--documenter-dark .navbar .navbar-menu{background-color:#375a7f;border-radius:0 0 .4em .4em}}html.theme--documenter-dark .hero .navbar,html.theme--documenter-dark body>.navbar{border-radius:0}html.theme--documenter-dark .pagination-link,html.theme--documenter-dark .pagination-next,html.theme--documenter-dark .pagination-previous{border-width:1px}html.theme--documenter-dark .panel-block,html.theme--documenter-dark .panel-heading,html.theme--documenter-dark .panel-tabs{border-width:1px}html.theme--documenter-dark .panel-block:first-child,html.theme--documenter-dark .panel-heading:first-child,html.theme--documenter-dark .panel-tabs:first-child{border-top-width:1px}html.theme--documenter-dark .panel-heading{font-weight:700}html.theme--documenter-dark .panel-tabs a{border-width:1px;margin-bottom:-1px}html.theme--documenter-dark .panel-tabs a.is-active{border-bottom-color:#17a689}html.theme--documenter-dark .panel-block:hover{color:#1dd2af}html.theme--documenter-dark .panel-block:hover .panel-icon{color:#1dd2af}html.theme--documenter-dark .panel-block.is-active .panel-icon{color:#17a689}html.theme--documenter-dark .tabs a{border-bottom-width:1px;margin-bottom:-1px}html.theme--documenter-dark .tabs ul{border-bottom-width:1px}html.theme--documenter-dark .tabs.is-boxed a{border-width:1px}html.theme--documenter-dark .tabs.is-boxed li.is-active a{background-color:#1f2424}html.theme--documenter-dark .tabs.is-toggle li a{border-width:1px;margin-bottom:0}html.theme--documenter-dark .tabs.is-toggle li+li{margin-left:-1px}html.theme--documenter-dark .hero.is-white .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-black .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-light .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-dark .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .content kbd.hero .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-primary .navbar .navbar-dropdown .navbar-item:hover,html.theme--documenter-dark .docstring>section>a.hero.docs-sourcelink .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-link .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-info .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-success .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-warning .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark .hero.is-danger .navbar .navbar-dropdown .navbar-item:hover{background-color:rgba(0,0,0,0)}html.theme--documenter-dark h1 .docs-heading-anchor,html.theme--documenter-dark h1 .docs-heading-anchor:hover,html.theme--documenter-dark h1 .docs-heading-anchor:visited,html.theme--documenter-dark h2 .docs-heading-anchor,html.theme--documenter-dark h2 .docs-heading-anchor:hover,html.theme--documenter-dark h2 .docs-heading-anchor:visited,html.theme--documenter-dark h3 .docs-heading-anchor,html.theme--documenter-dark h3 .docs-heading-anchor:hover,html.theme--documenter-dark h3 .docs-heading-anchor:visited,html.theme--documenter-dark h4 .docs-heading-anchor,html.theme--documenter-dark h4 .docs-heading-anchor:hover,html.theme--documenter-dark h4 .docs-heading-anchor:visited,html.theme--documenter-dark h5 .docs-heading-anchor,html.theme--documenter-dark h5 .docs-heading-anchor:hover,html.theme--documenter-dark h5 .docs-heading-anchor:visited,html.theme--documenter-dark h6 .docs-heading-anchor,html.theme--documenter-dark h6 .docs-heading-anchor:hover,html.theme--documenter-dark h6 .docs-heading-anchor:visited{color:#f2f2f2}html.theme--documenter-dark h1 .docs-heading-anchor-permalink,html.theme--documenter-dark h2 .docs-heading-anchor-permalink,html.theme--documenter-dark h3 .docs-heading-anchor-permalink,html.theme--documenter-dark h4 .docs-heading-anchor-permalink,html.theme--documenter-dark h5 .docs-heading-anchor-permalink,html.theme--documenter-dark h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}html.theme--documenter-dark h1 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h2 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h3 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h4 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h5 .docs-heading-anchor-permalink::before,html.theme--documenter-dark h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}html.theme--documenter-dark h1:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h2:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h3:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h4:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h5:hover .docs-heading-anchor-permalink,html.theme--documenter-dark h6:hover .docs-heading-anchor-permalink{visibility:visible}html.theme--documenter-dark .docs-light-only{display:none !important}html.theme--documenter-dark pre{position:relative;overflow:hidden}html.theme--documenter-dark pre code,html.theme--documenter-dark pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}html.theme--documenter-dark pre code:first-of-type,html.theme--documenter-dark pre code.hljs:first-of-type{padding-top:0.5rem !important}html.theme--documenter-dark pre code:last-of-type,html.theme--documenter-dark pre code.hljs:last-of-type{padding-bottom:0.5rem !important}html.theme--documenter-dark pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#fff;cursor:pointer;text-align:center}html.theme--documenter-dark pre .copy-button:focus,html.theme--documenter-dark pre .copy-button:hover{opacity:1;background:rgba(255,255,255,0.1);color:#1abc9c}html.theme--documenter-dark pre .copy-button.success{color:#259a12;opacity:1}html.theme--documenter-dark pre .copy-button.error{color:#cb3c33;opacity:1}html.theme--documenter-dark pre:hover .copy-button{opacity:1}html.theme--documenter-dark .admonition{background-color:#282f2f;border-style:solid;border-width:1px;border-color:#5e6d6f;border-radius:.4em;font-size:1rem}html.theme--documenter-dark .admonition strong{color:currentColor}html.theme--documenter-dark .admonition.is-small,html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}html.theme--documenter-dark .admonition.is-medium{font-size:1.25rem}html.theme--documenter-dark .admonition.is-large{font-size:1.5rem}html.theme--documenter-dark .admonition.is-default{background-color:#282f2f;border-color:#5e6d6f}html.theme--documenter-dark .admonition.is-default>.admonition-header{background-color:#5e6d6f;color:#fff}html.theme--documenter-dark .admonition.is-default>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-info{background-color:#282f2f;border-color:#024c7d}html.theme--documenter-dark .admonition.is-info>.admonition-header{background-color:#024c7d;color:#fff}html.theme--documenter-dark .admonition.is-info>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-success{background-color:#282f2f;border-color:#008438}html.theme--documenter-dark .admonition.is-success>.admonition-header{background-color:#008438;color:#fff}html.theme--documenter-dark .admonition.is-success>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-warning{background-color:#282f2f;border-color:#ad8100}html.theme--documenter-dark .admonition.is-warning>.admonition-header{background-color:#ad8100;color:#fff}html.theme--documenter-dark .admonition.is-warning>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-danger{background-color:#282f2f;border-color:#9e1b0d}html.theme--documenter-dark .admonition.is-danger>.admonition-header{background-color:#9e1b0d;color:#fff}html.theme--documenter-dark .admonition.is-danger>.admonition-body{color:#fff}html.theme--documenter-dark .admonition.is-compat{background-color:#282f2f;border-color:#137886}html.theme--documenter-dark .admonition.is-compat>.admonition-header{background-color:#137886;color:#fff}html.theme--documenter-dark .admonition.is-compat>.admonition-body{color:#fff}html.theme--documenter-dark .admonition-header{color:#fff;background-color:#5e6d6f;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}html.theme--documenter-dark .admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}html.theme--documenter-dark details.admonition.is-details>.admonition-header{list-style:none}html.theme--documenter-dark details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}html.theme--documenter-dark details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}html.theme--documenter-dark .admonition-body{color:#fff;padding:0.5rem .75rem}html.theme--documenter-dark .admonition-body pre{background-color:#282f2f}html.theme--documenter-dark .admonition-body code{background-color:rgba(255,255,255,0.05)}html.theme--documenter-dark .docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #5e6d6f;box-shadow:none;max-width:100%}html.theme--documenter-dark .docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#282f2f;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #5e6d6f;overflow:auto}html.theme--documenter-dark .docstring>header code{background-color:transparent}html.theme--documenter-dark .docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}html.theme--documenter-dark .docstring>header .docstring-binding{margin-right:0.3em}html.theme--documenter-dark .docstring>header .docstring-category{margin-left:0.3em}html.theme--documenter-dark .docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .docstring>section:last-child{border-bottom:none}html.theme--documenter-dark .docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}html.theme--documenter-dark .docstring>section>a.docs-sourcelink:focus{opacity:1 !important}html.theme--documenter-dark .docstring:hover>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}html.theme--documenter-dark .docstring>section:hover a.docs-sourcelink{opacity:1}html.theme--documenter-dark .documenter-example-output{background-color:#1f2424}html.theme--documenter-dark .outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#282f2f;color:#fff;border-bottom:3px solid #9e1b0d;padding:10px 35px;text-align:center;font-size:15px}html.theme--documenter-dark .outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}html.theme--documenter-dark .outdated-warning-overlay a{color:#1abc9c}html.theme--documenter-dark .outdated-warning-overlay a:hover{color:#1dd2af}html.theme--documenter-dark .content pre{border:1px solid #5e6d6f}html.theme--documenter-dark .content code{font-weight:inherit}html.theme--documenter-dark .content a code{color:#1abc9c}html.theme--documenter-dark .content h1 code,html.theme--documenter-dark .content h2 code,html.theme--documenter-dark .content h3 code,html.theme--documenter-dark .content h4 code,html.theme--documenter-dark .content h5 code,html.theme--documenter-dark .content h6 code{color:#f2f2f2}html.theme--documenter-dark .content table{display:block;width:initial;max-width:100%;overflow-x:auto}html.theme--documenter-dark .content blockquote>ul:first-child,html.theme--documenter-dark .content blockquote>ol:first-child,html.theme--documenter-dark .content .admonition-body>ul:first-child,html.theme--documenter-dark .content .admonition-body>ol:first-child{margin-top:0}html.theme--documenter-dark pre,html.theme--documenter-dark code{font-variant-ligatures:no-contextual}html.theme--documenter-dark .breadcrumb a.is-disabled{cursor:default;pointer-events:none}html.theme--documenter-dark .breadcrumb a.is-disabled,html.theme--documenter-dark .breadcrumb a.is-disabled:hover{color:#f2f2f2}html.theme--documenter-dark .hljs{background:initial !important}html.theme--documenter-dark .katex .katex-mathml{top:0;right:0}html.theme--documenter-dark .katex-display,html.theme--documenter-dark mjx-container,html.theme--documenter-dark .MathJax_Display{margin:0.5em 0 !important}html.theme--documenter-dark html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}html.theme--documenter-dark li.no-marker{list-style:none}html.theme--documenter-dark #documenter .docs-main>article{overflow-wrap:break-word}html.theme--documenter-dark #documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main{width:100%}html.theme--documenter-dark #documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-main>header,html.theme--documenter-dark #documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar{background-color:#1f2424;border-bottom:1px solid #5e6d6f;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-icon,html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}html.theme--documenter-dark #documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #171717;transition-duration:0.7s;-webkit-transition-duration:0.7s}html.theme--documenter-dark #documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}html.theme--documenter-dark #documenter .docs-main section.footnotes{border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-main section.footnotes li .tag:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,html.theme--documenter-dark #documenter .docs-main section.footnotes li .content kbd:first-child,html.theme--documenter-dark .content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}html.theme--documenter-dark #documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #5e6d6f;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage,html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}html.theme--documenter-dark #documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}html.theme--documenter-dark #documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}html.theme--documenter-dark #documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}html.theme--documenter-dark #documenter .docs-sidebar{display:flex;flex-direction:column;color:#fff;background-color:#282f2f;border-right:1px solid #5e6d6f;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}html.theme--documenter-dark #documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #171717}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar{left:0;top:0}}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a,html.theme--documenter-dark #documenter .docs-sidebar .docs-package-name a:hover{color:#fff}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector{border-top:1px solid #5e6d6f;display:none;padding:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar .docs-version-selector.visible{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #5e6d6f;padding-bottom:1.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#fff;background:#282f2f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu a.tocitem:hover,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#fff;background-color:#32393a}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #5e6d6f;border-bottom:1px solid #5e6d6f;background-color:#1f2424}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#1f2424;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#32393a;color:#fff}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #5e6d6f}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}html.theme--documenter-dark #documenter .docs-sidebar form.docs-search>input{width:14.4rem}html.theme--documenter-dark #documenter .docs-sidebar #documenter-search-query{color:#868c98;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}@media screen and (max-width: 1055px){html.theme--documenter-dark #documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#3b4445}html.theme--documenter-dark #documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#4e5a5c}}html.theme--documenter-dark kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(245,245,245,0.6);box-shadow:0 2px 0 1px rgba(245,245,245,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}html.theme--documenter-dark .search-min-width-50{min-width:50%}html.theme--documenter-dark .search-min-height-100{min-height:100%}html.theme--documenter-dark .search-modal-card-body{max-height:calc(100vh - 15rem)}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333;background-color:#f1f5f9}html.theme--documenter-dark .search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}html.theme--documenter-dark .search-filter:hover,html.theme--documenter-dark .search-filter:focus{color:#333}html.theme--documenter-dark .search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}html.theme--documenter-dark .search-filter-selected:hover,html.theme--documenter-dark .search-filter-selected:focus{color:#f5f5f5}html.theme--documenter-dark .search-result-highlight{background-color:#ffdd57;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f}html.theme--documenter-dark .search-result-title{width:85%;color:#f5f5f5}html.theme--documenter-dark .search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-thumb,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}html.theme--documenter-dark #search-modal .modal-card-body::-webkit-scrollbar-track,html.theme--documenter-dark #search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem}html.theme--documenter-dark .gap-8{gap:2rem}html.theme--documenter-dark{background-color:#1f2424;font-size:16px;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}html.theme--documenter-dark .ansi span.sgr1{font-weight:bolder}html.theme--documenter-dark .ansi span.sgr2{font-weight:lighter}html.theme--documenter-dark .ansi span.sgr3{font-style:italic}html.theme--documenter-dark .ansi span.sgr4{text-decoration:underline}html.theme--documenter-dark .ansi span.sgr7{color:#1f2424;background-color:#fff}html.theme--documenter-dark .ansi span.sgr8{color:transparent}html.theme--documenter-dark .ansi span.sgr8 span{color:transparent}html.theme--documenter-dark .ansi span.sgr9{text-decoration:line-through}html.theme--documenter-dark .ansi span.sgr30{color:#242424}html.theme--documenter-dark .ansi span.sgr31{color:#f6705f}html.theme--documenter-dark .ansi span.sgr32{color:#4fb43a}html.theme--documenter-dark .ansi span.sgr33{color:#f4c72f}html.theme--documenter-dark .ansi span.sgr34{color:#7587f0}html.theme--documenter-dark .ansi span.sgr35{color:#bc89d3}html.theme--documenter-dark .ansi span.sgr36{color:#49b6ca}html.theme--documenter-dark .ansi span.sgr37{color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr40{background-color:#242424}html.theme--documenter-dark .ansi span.sgr41{background-color:#f6705f}html.theme--documenter-dark .ansi span.sgr42{background-color:#4fb43a}html.theme--documenter-dark .ansi span.sgr43{background-color:#f4c72f}html.theme--documenter-dark .ansi span.sgr44{background-color:#7587f0}html.theme--documenter-dark .ansi span.sgr45{background-color:#bc89d3}html.theme--documenter-dark .ansi span.sgr46{background-color:#49b6ca}html.theme--documenter-dark .ansi span.sgr47{background-color:#b3bdbe}html.theme--documenter-dark .ansi span.sgr90{color:#92a0a2}html.theme--documenter-dark .ansi span.sgr91{color:#ff8674}html.theme--documenter-dark .ansi span.sgr92{color:#79d462}html.theme--documenter-dark .ansi span.sgr93{color:#ffe76b}html.theme--documenter-dark .ansi span.sgr94{color:#8a98ff}html.theme--documenter-dark .ansi span.sgr95{color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr96{color:#6bc8db}html.theme--documenter-dark .ansi span.sgr97{color:#ecf0f1}html.theme--documenter-dark .ansi span.sgr100{background-color:#92a0a2}html.theme--documenter-dark .ansi span.sgr101{background-color:#ff8674}html.theme--documenter-dark .ansi span.sgr102{background-color:#79d462}html.theme--documenter-dark .ansi span.sgr103{background-color:#ffe76b}html.theme--documenter-dark .ansi span.sgr104{background-color:#8a98ff}html.theme--documenter-dark .ansi span.sgr105{background-color:#d2a4e6}html.theme--documenter-dark .ansi span.sgr106{background-color:#6bc8db}html.theme--documenter-dark .ansi span.sgr107{background-color:#ecf0f1}html.theme--documenter-dark code.language-julia-repl>span.hljs-meta{color:#4fb43a;font-weight:bolder}html.theme--documenter-dark .hljs{background:#2b2b2b;color:#f8f8f2}html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-quote{color:#d4d0ab}html.theme--documenter-dark .hljs-variable,html.theme--documenter-dark .hljs-template-variable,html.theme--documenter-dark .hljs-tag,html.theme--documenter-dark .hljs-name,html.theme--documenter-dark .hljs-selector-id,html.theme--documenter-dark .hljs-selector-class,html.theme--documenter-dark .hljs-regexp,html.theme--documenter-dark .hljs-deletion{color:#ffa07a}html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-link{color:#f5ab35}html.theme--documenter-dark .hljs-attribute{color:#ffd700}html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-addition{color:#abe338}html.theme--documenter-dark .hljs-title,html.theme--documenter-dark .hljs-section{color:#00e0e0}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{color:#dcc6e0}html.theme--documenter-dark .hljs-emphasis{font-style:italic}html.theme--documenter-dark .hljs-strong{font-weight:bold}@media screen and (-ms-high-contrast: active){html.theme--documenter-dark .hljs-addition,html.theme--documenter-dark .hljs-attribute,html.theme--documenter-dark .hljs-built_in,html.theme--documenter-dark .hljs-bullet,html.theme--documenter-dark .hljs-comment,html.theme--documenter-dark .hljs-link,html.theme--documenter-dark .hljs-literal,html.theme--documenter-dark .hljs-meta,html.theme--documenter-dark .hljs-number,html.theme--documenter-dark .hljs-params,html.theme--documenter-dark .hljs-string,html.theme--documenter-dark .hljs-symbol,html.theme--documenter-dark .hljs-type,html.theme--documenter-dark .hljs-quote{color:highlight}html.theme--documenter-dark .hljs-keyword,html.theme--documenter-dark .hljs-selector-tag{font-weight:bold}}html.theme--documenter-dark .hljs-subst{color:#f8f8f2}html.theme--documenter-dark .search-result-link{border-radius:0.7em;transition:all 300ms}html.theme--documenter-dark .search-result-link:hover,html.theme--documenter-dark .search-result-link:focus{background-color:rgba(0,128,128,0.1)}html.theme--documenter-dark .search-result-link .property-search-result-badge,html.theme--documenter-dark .search-result-link .search-filter{transition:all 300ms}html.theme--documenter-dark .search-result-link:hover .property-search-result-badge,html.theme--documenter-dark .search-result-link:hover .search-filter,html.theme--documenter-dark .search-result-link:focus .property-search-result-badge,html.theme--documenter-dark .search-result-link:focus .search-filter{color:#333 !important;background-color:#f1f5f9 !important}html.theme--documenter-dark .property-search-result-badge,html.theme--documenter-dark .search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:whitesmoke;background-color:#33415580;border-radius:0.6rem}html.theme--documenter-dark .search-result-title{color:whitesmoke}html.theme--documenter-dark .search-result-highlight{background-color:greenyellow;color:black}html.theme--documenter-dark .search-divider{border-bottom:1px solid #5e6d6f50}html.theme--documenter-dark .w-100{width:100%}html.theme--documenter-dark .gap-2{gap:0.5rem}html.theme--documenter-dark .gap-4{gap:1rem} diff --git a/v2.16.2/assets/themes/documenter-light.css b/v2.16.2/assets/themes/documenter-light.css new file mode 100644 index 000000000..2f168c77b --- /dev/null +++ b/v2.16.2/assets/themes/documenter-light.css @@ -0,0 +1,9 @@ +.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.file-cta,.file-name,.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input,.button{-moz-appearance:none;-webkit-appearance:none;align-items:center;border:1px solid transparent;border-radius:4px;box-shadow:none;display:inline-flex;font-size:1rem;height:2.5em;justify-content:flex-start;line-height:1.5;padding-bottom:calc(0.5em - 1px);padding-left:calc(0.75em - 1px);padding-right:calc(0.75em - 1px);padding-top:calc(0.5em - 1px);position:relative;vertical-align:top}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus,.pagination-ellipsis:focus,.file-cta:focus,.file-name:focus,.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.button:focus,.is-focused.pagination-previous,.is-focused.pagination-next,.is-focused.pagination-link,.is-focused.pagination-ellipsis,.is-focused.file-cta,.is-focused.file-name,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-focused.button,.pagination-previous:active,.pagination-next:active,.pagination-link:active,.pagination-ellipsis:active,.file-cta:active,.file-name:active,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.button:active,.is-active.pagination-previous,.is-active.pagination-next,.is-active.pagination-link,.is-active.pagination-ellipsis,.is-active.file-cta,.is-active.file-name,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.is-active.button{outline:none}.pagination-previous[disabled],.pagination-next[disabled],.pagination-link[disabled],.pagination-ellipsis[disabled],.file-cta[disabled],.file-name[disabled],.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],.button[disabled],fieldset[disabled] .pagination-previous,fieldset[disabled] .pagination-next,fieldset[disabled] .pagination-link,fieldset[disabled] .pagination-ellipsis,fieldset[disabled] .file-cta,fieldset[disabled] .file-name,fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input,fieldset[disabled] .button{cursor:not-allowed}.tabs,.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis,.breadcrumb,.file,.button,.is-unselectable{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.navbar-link:not(.is-arrowless)::after,.select:not(.is-multiple):not(.is-loading)::after{border:3px solid rgba(0,0,0,0);border-radius:2px;border-right:0;border-top:0;content:" ";display:block;height:0.625em;margin-top:-0.4375em;pointer-events:none;position:absolute;top:50%;transform:rotate(-45deg);transform-origin:center;width:0.625em}.admonition:not(:last-child),.tabs:not(:last-child),.pagination:not(:last-child),.message:not(:last-child),.level:not(:last-child),.breadcrumb:not(:last-child),.block:not(:last-child),.title:not(:last-child),.subtitle:not(:last-child),.table-container:not(:last-child),.table:not(:last-child),.progress:not(:last-child),.notification:not(:last-child),.content:not(:last-child),.box:not(:last-child){margin-bottom:1.5rem}.modal-close,.delete{-webkit-touch-callout:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-moz-appearance:none;-webkit-appearance:none;background-color:rgba(10,10,10,0.2);border:none;border-radius:9999px;cursor:pointer;pointer-events:auto;display:inline-block;flex-grow:0;flex-shrink:0;font-size:0;height:20px;max-height:20px;max-width:20px;min-height:20px;min-width:20px;outline:none;position:relative;vertical-align:top;width:20px}.modal-close::before,.delete::before,.modal-close::after,.delete::after{background-color:#fff;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.modal-close::before,.delete::before{height:2px;width:50%}.modal-close::after,.delete::after{height:50%;width:2px}.modal-close:hover,.delete:hover,.modal-close:focus,.delete:focus{background-color:rgba(10,10,10,0.3)}.modal-close:active,.delete:active{background-color:rgba(10,10,10,0.4)}.is-small.modal-close,#documenter .docs-sidebar form.docs-search>input.modal-close,.is-small.delete,#documenter .docs-sidebar form.docs-search>input.delete{height:16px;max-height:16px;max-width:16px;min-height:16px;min-width:16px;width:16px}.is-medium.modal-close,.is-medium.delete{height:24px;max-height:24px;max-width:24px;min-height:24px;min-width:24px;width:24px}.is-large.modal-close,.is-large.delete{height:32px;max-height:32px;max-width:32px;min-height:32px;min-width:32px;width:32px}.control.is-loading::after,.select.is-loading::after,.loader,.button.is-loading::after{animation:spinAround 500ms infinite linear;border:2px solid #dbdbdb;border-radius:9999px;border-right-color:transparent;border-top-color:transparent;content:"";display:block;height:1em;position:relative;width:1em}.hero-video,.modal-background,.modal,.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio,.is-overlay{bottom:0;left:0;position:absolute;right:0;top:0}.navbar-burger{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0}.has-text-white{color:#fff !important}a.has-text-white:hover,a.has-text-white:focus{color:#e6e6e6 !important}.has-background-white{background-color:#fff !important}.has-text-black{color:#0a0a0a !important}a.has-text-black:hover,a.has-text-black:focus{color:#000 !important}.has-background-black{background-color:#0a0a0a !important}.has-text-light{color:#f5f5f5 !important}a.has-text-light:hover,a.has-text-light:focus{color:#dbdbdb !important}.has-background-light{background-color:#f5f5f5 !important}.has-text-dark{color:#363636 !important}a.has-text-dark:hover,a.has-text-dark:focus{color:#1c1c1c !important}.has-background-dark{background-color:#363636 !important}.has-text-primary{color:#4eb5de !important}a.has-text-primary:hover,a.has-text-primary:focus{color:#27a1d2 !important}.has-background-primary{background-color:#4eb5de !important}.has-text-primary-light{color:#eef8fc !important}a.has-text-primary-light:hover,a.has-text-primary-light:focus{color:#c3e6f4 !important}.has-background-primary-light{background-color:#eef8fc !important}.has-text-primary-dark{color:#1a6d8e !important}a.has-text-primary-dark:hover,a.has-text-primary-dark:focus{color:#228eb9 !important}.has-background-primary-dark{background-color:#1a6d8e !important}.has-text-link{color:#2e63b8 !important}a.has-text-link:hover,a.has-text-link:focus{color:#244d8f !important}.has-background-link{background-color:#2e63b8 !important}.has-text-link-light{color:#eff3fb !important}a.has-text-link-light:hover,a.has-text-link-light:focus{color:#c6d6f1 !important}.has-background-link-light{background-color:#eff3fb !important}.has-text-link-dark{color:#3169c4 !important}a.has-text-link-dark:hover,a.has-text-link-dark:focus{color:#5485d4 !important}.has-background-link-dark{background-color:#3169c4 !important}.has-text-info{color:#209cee !important}a.has-text-info:hover,a.has-text-info:focus{color:#1081cb !important}.has-background-info{background-color:#209cee !important}.has-text-info-light{color:#ecf7fe !important}a.has-text-info-light:hover,a.has-text-info-light:focus{color:#bde2fa !important}.has-background-info-light{background-color:#ecf7fe !important}.has-text-info-dark{color:#0e72b4 !important}a.has-text-info-dark:hover,a.has-text-info-dark:focus{color:#1190e3 !important}.has-background-info-dark{background-color:#0e72b4 !important}.has-text-success{color:#22c35b !important}a.has-text-success:hover,a.has-text-success:focus{color:#1a9847 !important}.has-background-success{background-color:#22c35b !important}.has-text-success-light{color:#eefcf3 !important}a.has-text-success-light:hover,a.has-text-success-light:focus{color:#c2f4d4 !important}.has-background-success-light{background-color:#eefcf3 !important}.has-text-success-dark{color:#198f43 !important}a.has-text-success-dark:hover,a.has-text-success-dark:focus{color:#21bb57 !important}.has-background-success-dark{background-color:#198f43 !important}.has-text-warning{color:#ffdd57 !important}a.has-text-warning:hover,a.has-text-warning:focus{color:#ffd324 !important}.has-background-warning{background-color:#ffdd57 !important}.has-text-warning-light{color:#fffbeb !important}a.has-text-warning-light:hover,a.has-text-warning-light:focus{color:#fff1b8 !important}.has-background-warning-light{background-color:#fffbeb !important}.has-text-warning-dark{color:#947600 !important}a.has-text-warning-dark:hover,a.has-text-warning-dark:focus{color:#c79f00 !important}.has-background-warning-dark{background-color:#947600 !important}.has-text-danger{color:#da0b00 !important}a.has-text-danger:hover,a.has-text-danger:focus{color:#a70800 !important}.has-background-danger{background-color:#da0b00 !important}.has-text-danger-light{color:#ffeceb !important}a.has-text-danger-light:hover,a.has-text-danger-light:focus{color:#ffbbb8 !important}.has-background-danger-light{background-color:#ffeceb !important}.has-text-danger-dark{color:#f50c00 !important}a.has-text-danger-dark:hover,a.has-text-danger-dark:focus{color:#ff3429 !important}.has-background-danger-dark{background-color:#f50c00 !important}.has-text-black-bis{color:#121212 !important}.has-background-black-bis{background-color:#121212 !important}.has-text-black-ter{color:#242424 !important}.has-background-black-ter{background-color:#242424 !important}.has-text-grey-darker{color:#363636 !important}.has-background-grey-darker{background-color:#363636 !important}.has-text-grey-dark{color:#4a4a4a !important}.has-background-grey-dark{background-color:#4a4a4a !important}.has-text-grey{color:#6b6b6b !important}.has-background-grey{background-color:#6b6b6b !important}.has-text-grey-light{color:#b5b5b5 !important}.has-background-grey-light{background-color:#b5b5b5 !important}.has-text-grey-lighter{color:#dbdbdb !important}.has-background-grey-lighter{background-color:#dbdbdb !important}.has-text-white-ter{color:#f5f5f5 !important}.has-background-white-ter{background-color:#f5f5f5 !important}.has-text-white-bis{color:#fafafa !important}.has-background-white-bis{background-color:#fafafa !important}.is-flex-direction-row{flex-direction:row !important}.is-flex-direction-row-reverse{flex-direction:row-reverse !important}.is-flex-direction-column{flex-direction:column !important}.is-flex-direction-column-reverse{flex-direction:column-reverse !important}.is-flex-wrap-nowrap{flex-wrap:nowrap !important}.is-flex-wrap-wrap{flex-wrap:wrap !important}.is-flex-wrap-wrap-reverse{flex-wrap:wrap-reverse !important}.is-justify-content-flex-start{justify-content:flex-start !important}.is-justify-content-flex-end{justify-content:flex-end !important}.is-justify-content-center{justify-content:center !important}.is-justify-content-space-between{justify-content:space-between !important}.is-justify-content-space-around{justify-content:space-around !important}.is-justify-content-space-evenly{justify-content:space-evenly !important}.is-justify-content-start{justify-content:start !important}.is-justify-content-end{justify-content:end !important}.is-justify-content-left{justify-content:left !important}.is-justify-content-right{justify-content:right !important}.is-align-content-flex-start{align-content:flex-start !important}.is-align-content-flex-end{align-content:flex-end !important}.is-align-content-center{align-content:center !important}.is-align-content-space-between{align-content:space-between !important}.is-align-content-space-around{align-content:space-around !important}.is-align-content-space-evenly{align-content:space-evenly !important}.is-align-content-stretch{align-content:stretch !important}.is-align-content-start{align-content:start !important}.is-align-content-end{align-content:end !important}.is-align-content-baseline{align-content:baseline !important}.is-align-items-stretch{align-items:stretch !important}.is-align-items-flex-start{align-items:flex-start !important}.is-align-items-flex-end{align-items:flex-end !important}.is-align-items-center{align-items:center !important}.is-align-items-baseline{align-items:baseline !important}.is-align-items-start{align-items:start !important}.is-align-items-end{align-items:end !important}.is-align-items-self-start{align-items:self-start !important}.is-align-items-self-end{align-items:self-end !important}.is-align-self-auto{align-self:auto !important}.is-align-self-flex-start{align-self:flex-start !important}.is-align-self-flex-end{align-self:flex-end !important}.is-align-self-center{align-self:center !important}.is-align-self-baseline{align-self:baseline !important}.is-align-self-stretch{align-self:stretch !important}.is-flex-grow-0{flex-grow:0 !important}.is-flex-grow-1{flex-grow:1 !important}.is-flex-grow-2{flex-grow:2 !important}.is-flex-grow-3{flex-grow:3 !important}.is-flex-grow-4{flex-grow:4 !important}.is-flex-grow-5{flex-grow:5 !important}.is-flex-shrink-0{flex-shrink:0 !important}.is-flex-shrink-1{flex-shrink:1 !important}.is-flex-shrink-2{flex-shrink:2 !important}.is-flex-shrink-3{flex-shrink:3 !important}.is-flex-shrink-4{flex-shrink:4 !important}.is-flex-shrink-5{flex-shrink:5 !important}.is-clearfix::after{clear:both;content:" ";display:table}.is-pulled-left{float:left !important}.is-pulled-right{float:right !important}.is-radiusless{border-radius:0 !important}.is-shadowless{box-shadow:none !important}.is-clickable{cursor:pointer !important;pointer-events:all !important}.is-clipped{overflow:hidden !important}.is-relative{position:relative !important}.is-marginless{margin:0 !important}.is-paddingless{padding:0 !important}.m-0{margin:0 !important}.mt-0{margin-top:0 !important}.mr-0{margin-right:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.m-1{margin:.25rem !important}.mt-1{margin-top:.25rem !important}.mr-1{margin-right:.25rem !important}.mb-1{margin-bottom:.25rem !important}.ml-1{margin-left:.25rem !important}.mx-1{margin-left:.25rem !important;margin-right:.25rem !important}.my-1{margin-top:.25rem !important;margin-bottom:.25rem !important}.m-2{margin:.5rem !important}.mt-2{margin-top:.5rem !important}.mr-2{margin-right:.5rem !important}.mb-2{margin-bottom:.5rem !important}.ml-2{margin-left:.5rem !important}.mx-2{margin-left:.5rem !important;margin-right:.5rem !important}.my-2{margin-top:.5rem !important;margin-bottom:.5rem !important}.m-3{margin:.75rem !important}.mt-3{margin-top:.75rem !important}.mr-3{margin-right:.75rem !important}.mb-3{margin-bottom:.75rem !important}.ml-3{margin-left:.75rem !important}.mx-3{margin-left:.75rem !important;margin-right:.75rem !important}.my-3{margin-top:.75rem !important;margin-bottom:.75rem !important}.m-4{margin:1rem !important}.mt-4{margin-top:1rem !important}.mr-4{margin-right:1rem !important}.mb-4{margin-bottom:1rem !important}.ml-4{margin-left:1rem !important}.mx-4{margin-left:1rem !important;margin-right:1rem !important}.my-4{margin-top:1rem !important;margin-bottom:1rem !important}.m-5{margin:1.5rem !important}.mt-5{margin-top:1.5rem !important}.mr-5{margin-right:1.5rem !important}.mb-5{margin-bottom:1.5rem !important}.ml-5{margin-left:1.5rem !important}.mx-5{margin-left:1.5rem !important;margin-right:1.5rem !important}.my-5{margin-top:1.5rem !important;margin-bottom:1.5rem !important}.m-6{margin:3rem !important}.mt-6{margin-top:3rem !important}.mr-6{margin-right:3rem !important}.mb-6{margin-bottom:3rem !important}.ml-6{margin-left:3rem !important}.mx-6{margin-left:3rem !important;margin-right:3rem !important}.my-6{margin-top:3rem !important;margin-bottom:3rem !important}.m-auto{margin:auto !important}.mt-auto{margin-top:auto !important}.mr-auto{margin-right:auto !important}.mb-auto{margin-bottom:auto !important}.ml-auto{margin-left:auto !important}.mx-auto{margin-left:auto !important;margin-right:auto !important}.my-auto{margin-top:auto !important;margin-bottom:auto !important}.p-0{padding:0 !important}.pt-0{padding-top:0 !important}.pr-0{padding-right:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.p-1{padding:.25rem !important}.pt-1{padding-top:.25rem !important}.pr-1{padding-right:.25rem !important}.pb-1{padding-bottom:.25rem !important}.pl-1{padding-left:.25rem !important}.px-1{padding-left:.25rem !important;padding-right:.25rem !important}.py-1{padding-top:.25rem !important;padding-bottom:.25rem !important}.p-2{padding:.5rem !important}.pt-2{padding-top:.5rem !important}.pr-2{padding-right:.5rem !important}.pb-2{padding-bottom:.5rem !important}.pl-2{padding-left:.5rem !important}.px-2{padding-left:.5rem !important;padding-right:.5rem !important}.py-2{padding-top:.5rem !important;padding-bottom:.5rem !important}.p-3{padding:.75rem !important}.pt-3{padding-top:.75rem !important}.pr-3{padding-right:.75rem !important}.pb-3{padding-bottom:.75rem !important}.pl-3{padding-left:.75rem !important}.px-3{padding-left:.75rem !important;padding-right:.75rem !important}.py-3{padding-top:.75rem !important;padding-bottom:.75rem !important}.p-4{padding:1rem !important}.pt-4{padding-top:1rem !important}.pr-4{padding-right:1rem !important}.pb-4{padding-bottom:1rem !important}.pl-4{padding-left:1rem !important}.px-4{padding-left:1rem !important;padding-right:1rem !important}.py-4{padding-top:1rem !important;padding-bottom:1rem !important}.p-5{padding:1.5rem !important}.pt-5{padding-top:1.5rem !important}.pr-5{padding-right:1.5rem !important}.pb-5{padding-bottom:1.5rem !important}.pl-5{padding-left:1.5rem !important}.px-5{padding-left:1.5rem !important;padding-right:1.5rem !important}.py-5{padding-top:1.5rem !important;padding-bottom:1.5rem !important}.p-6{padding:3rem !important}.pt-6{padding-top:3rem !important}.pr-6{padding-right:3rem !important}.pb-6{padding-bottom:3rem !important}.pl-6{padding-left:3rem !important}.px-6{padding-left:3rem !important;padding-right:3rem !important}.py-6{padding-top:3rem !important;padding-bottom:3rem !important}.p-auto{padding:auto !important}.pt-auto{padding-top:auto !important}.pr-auto{padding-right:auto !important}.pb-auto{padding-bottom:auto !important}.pl-auto{padding-left:auto !important}.px-auto{padding-left:auto !important;padding-right:auto !important}.py-auto{padding-top:auto !important;padding-bottom:auto !important}.is-size-1{font-size:3rem !important}.is-size-2{font-size:2.5rem !important}.is-size-3{font-size:2rem !important}.is-size-4{font-size:1.5rem !important}.is-size-5{font-size:1.25rem !important}.is-size-6{font-size:1rem !important}.is-size-7,.docstring>section>a.docs-sourcelink{font-size:.75rem !important}@media screen and (max-width: 768px){.is-size-1-mobile{font-size:3rem !important}.is-size-2-mobile{font-size:2.5rem !important}.is-size-3-mobile{font-size:2rem !important}.is-size-4-mobile{font-size:1.5rem !important}.is-size-5-mobile{font-size:1.25rem !important}.is-size-6-mobile{font-size:1rem !important}.is-size-7-mobile{font-size:.75rem !important}}@media screen and (min-width: 769px),print{.is-size-1-tablet{font-size:3rem !important}.is-size-2-tablet{font-size:2.5rem !important}.is-size-3-tablet{font-size:2rem !important}.is-size-4-tablet{font-size:1.5rem !important}.is-size-5-tablet{font-size:1.25rem !important}.is-size-6-tablet{font-size:1rem !important}.is-size-7-tablet{font-size:.75rem !important}}@media screen and (max-width: 1055px){.is-size-1-touch{font-size:3rem !important}.is-size-2-touch{font-size:2.5rem !important}.is-size-3-touch{font-size:2rem !important}.is-size-4-touch{font-size:1.5rem !important}.is-size-5-touch{font-size:1.25rem !important}.is-size-6-touch{font-size:1rem !important}.is-size-7-touch{font-size:.75rem !important}}@media screen and (min-width: 1056px){.is-size-1-desktop{font-size:3rem !important}.is-size-2-desktop{font-size:2.5rem !important}.is-size-3-desktop{font-size:2rem !important}.is-size-4-desktop{font-size:1.5rem !important}.is-size-5-desktop{font-size:1.25rem !important}.is-size-6-desktop{font-size:1rem !important}.is-size-7-desktop{font-size:.75rem !important}}@media screen and (min-width: 1216px){.is-size-1-widescreen{font-size:3rem !important}.is-size-2-widescreen{font-size:2.5rem !important}.is-size-3-widescreen{font-size:2rem !important}.is-size-4-widescreen{font-size:1.5rem !important}.is-size-5-widescreen{font-size:1.25rem !important}.is-size-6-widescreen{font-size:1rem !important}.is-size-7-widescreen{font-size:.75rem !important}}@media screen and (min-width: 1408px){.is-size-1-fullhd{font-size:3rem !important}.is-size-2-fullhd{font-size:2.5rem !important}.is-size-3-fullhd{font-size:2rem !important}.is-size-4-fullhd{font-size:1.5rem !important}.is-size-5-fullhd{font-size:1.25rem !important}.is-size-6-fullhd{font-size:1rem !important}.is-size-7-fullhd{font-size:.75rem !important}}.has-text-centered{text-align:center !important}.has-text-justified{text-align:justify !important}.has-text-left{text-align:left !important}.has-text-right{text-align:right !important}@media screen and (max-width: 768px){.has-text-centered-mobile{text-align:center !important}}@media screen and (min-width: 769px),print{.has-text-centered-tablet{text-align:center !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-centered-tablet-only{text-align:center !important}}@media screen and (max-width: 1055px){.has-text-centered-touch{text-align:center !important}}@media screen and (min-width: 1056px){.has-text-centered-desktop{text-align:center !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-centered-desktop-only{text-align:center !important}}@media screen and (min-width: 1216px){.has-text-centered-widescreen{text-align:center !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-centered-widescreen-only{text-align:center !important}}@media screen and (min-width: 1408px){.has-text-centered-fullhd{text-align:center !important}}@media screen and (max-width: 768px){.has-text-justified-mobile{text-align:justify !important}}@media screen and (min-width: 769px),print{.has-text-justified-tablet{text-align:justify !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-justified-tablet-only{text-align:justify !important}}@media screen and (max-width: 1055px){.has-text-justified-touch{text-align:justify !important}}@media screen and (min-width: 1056px){.has-text-justified-desktop{text-align:justify !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-justified-desktop-only{text-align:justify !important}}@media screen and (min-width: 1216px){.has-text-justified-widescreen{text-align:justify !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-justified-widescreen-only{text-align:justify !important}}@media screen and (min-width: 1408px){.has-text-justified-fullhd{text-align:justify !important}}@media screen and (max-width: 768px){.has-text-left-mobile{text-align:left !important}}@media screen and (min-width: 769px),print{.has-text-left-tablet{text-align:left !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-left-tablet-only{text-align:left !important}}@media screen and (max-width: 1055px){.has-text-left-touch{text-align:left !important}}@media screen and (min-width: 1056px){.has-text-left-desktop{text-align:left !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-left-desktop-only{text-align:left !important}}@media screen and (min-width: 1216px){.has-text-left-widescreen{text-align:left !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-left-widescreen-only{text-align:left !important}}@media screen and (min-width: 1408px){.has-text-left-fullhd{text-align:left !important}}@media screen and (max-width: 768px){.has-text-right-mobile{text-align:right !important}}@media screen and (min-width: 769px),print{.has-text-right-tablet{text-align:right !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.has-text-right-tablet-only{text-align:right !important}}@media screen and (max-width: 1055px){.has-text-right-touch{text-align:right !important}}@media screen and (min-width: 1056px){.has-text-right-desktop{text-align:right !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.has-text-right-desktop-only{text-align:right !important}}@media screen and (min-width: 1216px){.has-text-right-widescreen{text-align:right !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.has-text-right-widescreen-only{text-align:right !important}}@media screen and (min-width: 1408px){.has-text-right-fullhd{text-align:right !important}}.is-capitalized{text-transform:capitalize !important}.is-lowercase{text-transform:lowercase !important}.is-uppercase{text-transform:uppercase !important}.is-italic{font-style:italic !important}.is-underlined{text-decoration:underline !important}.has-text-weight-light{font-weight:300 !important}.has-text-weight-normal{font-weight:400 !important}.has-text-weight-medium{font-weight:500 !important}.has-text-weight-semibold{font-weight:600 !important}.has-text-weight-bold{font-weight:700 !important}.is-family-primary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-secondary{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-sans-serif{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif !important}.is-family-monospace{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-family-code{font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace !important}.is-block{display:block !important}@media screen and (max-width: 768px){.is-block-mobile{display:block !important}}@media screen and (min-width: 769px),print{.is-block-tablet{display:block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-block-tablet-only{display:block !important}}@media screen and (max-width: 1055px){.is-block-touch{display:block !important}}@media screen and (min-width: 1056px){.is-block-desktop{display:block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-block-desktop-only{display:block !important}}@media screen and (min-width: 1216px){.is-block-widescreen{display:block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-block-widescreen-only{display:block !important}}@media screen and (min-width: 1408px){.is-block-fullhd{display:block !important}}.is-flex{display:flex !important}@media screen and (max-width: 768px){.is-flex-mobile{display:flex !important}}@media screen and (min-width: 769px),print{.is-flex-tablet{display:flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-flex-tablet-only{display:flex !important}}@media screen and (max-width: 1055px){.is-flex-touch{display:flex !important}}@media screen and (min-width: 1056px){.is-flex-desktop{display:flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-flex-desktop-only{display:flex !important}}@media screen and (min-width: 1216px){.is-flex-widescreen{display:flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-flex-widescreen-only{display:flex !important}}@media screen and (min-width: 1408px){.is-flex-fullhd{display:flex !important}}.is-inline{display:inline !important}@media screen and (max-width: 768px){.is-inline-mobile{display:inline !important}}@media screen and (min-width: 769px),print{.is-inline-tablet{display:inline !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-tablet-only{display:inline !important}}@media screen and (max-width: 1055px){.is-inline-touch{display:inline !important}}@media screen and (min-width: 1056px){.is-inline-desktop{display:inline !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-desktop-only{display:inline !important}}@media screen and (min-width: 1216px){.is-inline-widescreen{display:inline !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-widescreen-only{display:inline !important}}@media screen and (min-width: 1408px){.is-inline-fullhd{display:inline !important}}.is-inline-block{display:inline-block !important}@media screen and (max-width: 768px){.is-inline-block-mobile{display:inline-block !important}}@media screen and (min-width: 769px),print{.is-inline-block-tablet{display:inline-block !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-block-tablet-only{display:inline-block !important}}@media screen and (max-width: 1055px){.is-inline-block-touch{display:inline-block !important}}@media screen and (min-width: 1056px){.is-inline-block-desktop{display:inline-block !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-block-desktop-only{display:inline-block !important}}@media screen and (min-width: 1216px){.is-inline-block-widescreen{display:inline-block !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-block-widescreen-only{display:inline-block !important}}@media screen and (min-width: 1408px){.is-inline-block-fullhd{display:inline-block !important}}.is-inline-flex{display:inline-flex !important}@media screen and (max-width: 768px){.is-inline-flex-mobile{display:inline-flex !important}}@media screen and (min-width: 769px),print{.is-inline-flex-tablet{display:inline-flex !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-inline-flex-tablet-only{display:inline-flex !important}}@media screen and (max-width: 1055px){.is-inline-flex-touch{display:inline-flex !important}}@media screen and (min-width: 1056px){.is-inline-flex-desktop{display:inline-flex !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-inline-flex-desktop-only{display:inline-flex !important}}@media screen and (min-width: 1216px){.is-inline-flex-widescreen{display:inline-flex !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-inline-flex-widescreen-only{display:inline-flex !important}}@media screen and (min-width: 1408px){.is-inline-flex-fullhd{display:inline-flex !important}}.is-hidden{display:none !important}.is-sr-only{border:none !important;clip:rect(0, 0, 0, 0) !important;height:0.01em !important;overflow:hidden !important;padding:0 !important;position:absolute !important;white-space:nowrap !important;width:0.01em !important}@media screen and (max-width: 768px){.is-hidden-mobile{display:none !important}}@media screen and (min-width: 769px),print{.is-hidden-tablet{display:none !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-hidden-tablet-only{display:none !important}}@media screen and (max-width: 1055px){.is-hidden-touch{display:none !important}}@media screen and (min-width: 1056px){.is-hidden-desktop{display:none !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-hidden-desktop-only{display:none !important}}@media screen and (min-width: 1216px){.is-hidden-widescreen{display:none !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-hidden-widescreen-only{display:none !important}}@media screen and (min-width: 1408px){.is-hidden-fullhd{display:none !important}}.is-invisible{visibility:hidden !important}@media screen and (max-width: 768px){.is-invisible-mobile{visibility:hidden !important}}@media screen and (min-width: 769px),print{.is-invisible-tablet{visibility:hidden !important}}@media screen and (min-width: 769px) and (max-width: 1055px){.is-invisible-tablet-only{visibility:hidden !important}}@media screen and (max-width: 1055px){.is-invisible-touch{visibility:hidden !important}}@media screen and (min-width: 1056px){.is-invisible-desktop{visibility:hidden !important}}@media screen and (min-width: 1056px) and (max-width: 1215px){.is-invisible-desktop-only{visibility:hidden !important}}@media screen and (min-width: 1216px){.is-invisible-widescreen{visibility:hidden !important}}@media screen and (min-width: 1216px) and (max-width: 1407px){.is-invisible-widescreen-only{visibility:hidden !important}}@media screen and (min-width: 1408px){.is-invisible-fullhd{visibility:hidden !important}}/*! minireset.css v0.0.6 | MIT License | github.com/jgthms/minireset.css */html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6{margin:0;padding:0}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal}ul{list-style:none}button,input,select,textarea{margin:0}html{box-sizing:border-box}*,*::before,*::after{box-sizing:inherit}img,video{height:auto;max-width:100%}iframe{border:0}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}td:not([align]),th:not([align]){text-align:inherit}html{background-color:#fff;font-size:16px;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;min-width:300px;overflow-x:auto;overflow-y:scroll;text-rendering:optimizeLegibility;text-size-adjust:100%}article,aside,figure,footer,header,hgroup,section{display:block}body,button,input,optgroup,select,textarea{font-family:"Lato Medium",-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue","Helvetica","Arial",sans-serif}code,pre{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}body{color:#222;font-size:1em;font-weight:400;line-height:1.5}a{color:#2e63b8;cursor:pointer;text-decoration:none}a strong{color:currentColor}a:hover{color:#363636}code{background-color:rgba(0,0,0,0.05);color:#000;font-size:.875em;font-weight:normal;padding:.1em}hr{background-color:#f5f5f5;border:none;display:block;height:2px;margin:1.5rem 0}img{height:auto;max-width:100%}input[type="checkbox"],input[type="radio"]{vertical-align:baseline}small{font-size:.875em}span{font-style:inherit;font-weight:inherit}strong{color:#222;font-weight:700}fieldset{border:none}pre{-webkit-overflow-scrolling:touch;background-color:#f5f5f5;color:#222;font-size:.875em;overflow-x:auto;padding:1.25rem 1.5rem;white-space:pre;word-wrap:normal}pre code{background-color:transparent;color:currentColor;font-size:1em;padding:0}table td,table th{vertical-align:top}table td:not([align]),table th:not([align]){text-align:inherit}table th{color:#222}@keyframes spinAround{from{transform:rotate(0deg)}to{transform:rotate(359deg)}}.box{background-color:#fff;border-radius:6px;box-shadow:#bbb;color:#222;display:block;padding:1.25rem}a.box:hover,a.box:focus{box-shadow:0 0.5em 1em -0.125em rgba(10,10,10,0.1),0 0 0 1px #2e63b8}a.box:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2),0 0 0 1px #2e63b8}.button{background-color:#fff;border-color:#dbdbdb;border-width:1px;color:#222;cursor:pointer;justify-content:center;padding-bottom:calc(0.5em - 1px);padding-left:1em;padding-right:1em;padding-top:calc(0.5em - 1px);text-align:center;white-space:nowrap}.button strong{color:inherit}.button .icon,.button .icon.is-small,.button #documenter .docs-sidebar form.docs-search>input.icon,#documenter .docs-sidebar .button form.docs-search>input.icon,.button .icon.is-medium,.button .icon.is-large{height:1.5em;width:1.5em}.button .icon:first-child:not(:last-child){margin-left:calc(-0.5em - 1px);margin-right:.25em}.button .icon:last-child:not(:first-child){margin-left:.25em;margin-right:calc(-0.5em - 1px)}.button .icon:first-child:last-child{margin-left:calc(-0.5em - 1px);margin-right:calc(-0.5em - 1px)}.button:hover,.button.is-hovered{border-color:#b5b5b5;color:#363636}.button:focus,.button.is-focused{border-color:#3c5dcd;color:#363636}.button:focus:not(:active),.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button:active,.button.is-active{border-color:#4a4a4a;color:#363636}.button.is-text{background-color:transparent;border-color:transparent;color:#222;text-decoration:underline}.button.is-text:hover,.button.is-text.is-hovered,.button.is-text:focus,.button.is-text.is-focused{background-color:#f5f5f5;color:#222}.button.is-text:active,.button.is-text.is-active{background-color:#e8e8e8;color:#222}.button.is-text[disabled],fieldset[disabled] .button.is-text{background-color:transparent;border-color:transparent;box-shadow:none}.button.is-ghost{background:none;border-color:rgba(0,0,0,0);color:#2e63b8;text-decoration:none}.button.is-ghost:hover,.button.is-ghost.is-hovered{color:#2e63b8;text-decoration:underline}.button.is-white{background-color:#fff;border-color:transparent;color:#0a0a0a}.button.is-white:hover,.button.is-white.is-hovered{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.button.is-white:focus,.button.is-white.is-focused{border-color:transparent;color:#0a0a0a}.button.is-white:focus:not(:active),.button.is-white.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.button.is-white:active,.button.is-white.is-active{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.button.is-white[disabled],fieldset[disabled] .button.is-white{background-color:#fff;border-color:#fff;box-shadow:none}.button.is-white.is-inverted{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted:hover,.button.is-white.is-inverted.is-hovered{background-color:#000}.button.is-white.is-inverted[disabled],fieldset[disabled] .button.is-white.is-inverted{background-color:#0a0a0a;border-color:transparent;box-shadow:none;color:#fff}.button.is-white.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-white.is-outlined:hover,.button.is-white.is-outlined.is-hovered,.button.is-white.is-outlined:focus,.button.is-white.is-outlined.is-focused{background-color:#fff;border-color:#fff;color:#0a0a0a}.button.is-white.is-outlined.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-outlined.is-loading:hover::after,.button.is-white.is-outlined.is-loading.is-hovered::after,.button.is-white.is-outlined.is-loading:focus::after,.button.is-white.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-white.is-outlined[disabled],fieldset[disabled] .button.is-white.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-white.is-inverted.is-outlined:hover,.button.is-white.is-inverted.is-outlined.is-hovered,.button.is-white.is-inverted.is-outlined:focus,.button.is-white.is-inverted.is-outlined.is-focused{background-color:#0a0a0a;color:#fff}.button.is-white.is-inverted.is-outlined.is-loading:hover::after,.button.is-white.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-white.is-inverted.is-outlined.is-loading:focus::after,.button.is-white.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-white.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-white.is-inverted.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black{background-color:#0a0a0a;border-color:transparent;color:#fff}.button.is-black:hover,.button.is-black.is-hovered{background-color:#040404;border-color:transparent;color:#fff}.button.is-black:focus,.button.is-black.is-focused{border-color:transparent;color:#fff}.button.is-black:focus:not(:active),.button.is-black.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.button.is-black:active,.button.is-black.is-active{background-color:#000;border-color:transparent;color:#fff}.button.is-black[disabled],fieldset[disabled] .button.is-black{background-color:#0a0a0a;border-color:#0a0a0a;box-shadow:none}.button.is-black.is-inverted{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted:hover,.button.is-black.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-black.is-inverted[disabled],fieldset[disabled] .button.is-black.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#0a0a0a}.button.is-black.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;color:#0a0a0a}.button.is-black.is-outlined:hover,.button.is-black.is-outlined.is-hovered,.button.is-black.is-outlined:focus,.button.is-black.is-outlined.is-focused{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.button.is-black.is-outlined.is-loading::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-outlined.is-loading:hover::after,.button.is-black.is-outlined.is-loading.is-hovered::after,.button.is-black.is-outlined.is-loading:focus::after,.button.is-black.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-black.is-outlined[disabled],fieldset[disabled] .button.is-black.is-outlined{background-color:transparent;border-color:#0a0a0a;box-shadow:none;color:#0a0a0a}.button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-black.is-inverted.is-outlined:hover,.button.is-black.is-inverted.is-outlined.is-hovered,.button.is-black.is-inverted.is-outlined:focus,.button.is-black.is-inverted.is-outlined.is-focused{background-color:#fff;color:#0a0a0a}.button.is-black.is-inverted.is-outlined.is-loading:hover::after,.button.is-black.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-black.is-inverted.is-outlined.is-loading:focus::after,.button.is-black.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #0a0a0a #0a0a0a !important}.button.is-black.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-black.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-light{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:hover,.button.is-light.is-hovered{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus,.button.is-light.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light:focus:not(:active),.button.is-light.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.button.is-light:active,.button.is-light.is-active{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-light[disabled],fieldset[disabled] .button.is-light{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none}.button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted:hover,.button.is-light.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-light.is-inverted[disabled],fieldset[disabled] .button.is-light.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#f5f5f5}.button.is-light.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;color:#f5f5f5}.button.is-light.is-outlined:hover,.button.is-light.is-outlined.is-hovered,.button.is-light.is-outlined:focus,.button.is-light.is-outlined.is-focused{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.button.is-light.is-outlined.is-loading::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-outlined.is-loading:hover::after,.button.is-light.is-outlined.is-loading.is-hovered::after,.button.is-light.is-outlined.is-loading:focus::after,.button.is-light.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-light.is-outlined[disabled],fieldset[disabled] .button.is-light.is-outlined{background-color:transparent;border-color:#f5f5f5;box-shadow:none;color:#f5f5f5}.button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-light.is-inverted.is-outlined:hover,.button.is-light.is-inverted.is-outlined.is-hovered,.button.is-light.is-inverted.is-outlined:focus,.button.is-light.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#f5f5f5}.button.is-light.is-inverted.is-outlined.is-loading:hover::after,.button.is-light.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-light.is-inverted.is-outlined.is-loading:focus::after,.button.is-light.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #f5f5f5 #f5f5f5 !important}.button.is-light.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-light.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-dark,.content kbd.button{background-color:#363636;border-color:transparent;color:#fff}.button.is-dark:hover,.content kbd.button:hover,.button.is-dark.is-hovered,.content kbd.button.is-hovered{background-color:#2f2f2f;border-color:transparent;color:#fff}.button.is-dark:focus,.content kbd.button:focus,.button.is-dark.is-focused,.content kbd.button.is-focused{border-color:transparent;color:#fff}.button.is-dark:focus:not(:active),.content kbd.button:focus:not(:active),.button.is-dark.is-focused:not(:active),.content kbd.button.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.button.is-dark:active,.content kbd.button:active,.button.is-dark.is-active,.content kbd.button.is-active{background-color:#292929;border-color:transparent;color:#fff}.button.is-dark[disabled],.content kbd.button[disabled],fieldset[disabled] .button.is-dark,fieldset[disabled] .content kbd.button,.content fieldset[disabled] kbd.button{background-color:#363636;border-color:#363636;box-shadow:none}.button.is-dark.is-inverted,.content kbd.button.is-inverted{background-color:#fff;color:#363636}.button.is-dark.is-inverted:hover,.content kbd.button.is-inverted:hover,.button.is-dark.is-inverted.is-hovered,.content kbd.button.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-dark.is-inverted[disabled],.content kbd.button.is-inverted[disabled],fieldset[disabled] .button.is-dark.is-inverted,fieldset[disabled] .content kbd.button.is-inverted,.content fieldset[disabled] kbd.button.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#363636}.button.is-dark.is-loading::after,.content kbd.button.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined,.content kbd.button.is-outlined{background-color:transparent;border-color:#363636;color:#363636}.button.is-dark.is-outlined:hover,.content kbd.button.is-outlined:hover,.button.is-dark.is-outlined.is-hovered,.content kbd.button.is-outlined.is-hovered,.button.is-dark.is-outlined:focus,.content kbd.button.is-outlined:focus,.button.is-dark.is-outlined.is-focused,.content kbd.button.is-outlined.is-focused{background-color:#363636;border-color:#363636;color:#fff}.button.is-dark.is-outlined.is-loading::after,.content kbd.button.is-outlined.is-loading::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-outlined.is-loading:hover::after,.content kbd.button.is-outlined.is-loading:hover::after,.button.is-dark.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-outlined.is-loading:focus::after,.content kbd.button.is-outlined.is-loading:focus::after,.button.is-dark.is-outlined.is-loading.is-focused::after,.content kbd.button.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-dark.is-outlined[disabled],.content kbd.button.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-outlined,fieldset[disabled] .content kbd.button.is-outlined,.content fieldset[disabled] kbd.button.is-outlined{background-color:transparent;border-color:#363636;box-shadow:none;color:#363636}.button.is-dark.is-inverted.is-outlined,.content kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-dark.is-inverted.is-outlined:hover,.content kbd.button.is-inverted.is-outlined:hover,.button.is-dark.is-inverted.is-outlined.is-hovered,.content kbd.button.is-inverted.is-outlined.is-hovered,.button.is-dark.is-inverted.is-outlined:focus,.content kbd.button.is-inverted.is-outlined:focus,.button.is-dark.is-inverted.is-outlined.is-focused,.content kbd.button.is-inverted.is-outlined.is-focused{background-color:#fff;color:#363636}.button.is-dark.is-inverted.is-outlined.is-loading:hover::after,.content kbd.button.is-inverted.is-outlined.is-loading:hover::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-hovered::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-dark.is-inverted.is-outlined.is-loading:focus::after,.content kbd.button.is-inverted.is-outlined.is-loading:focus::after,.button.is-dark.is-inverted.is-outlined.is-loading.is-focused::after,.content kbd.button.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #363636 #363636 !important}.button.is-dark.is-inverted.is-outlined[disabled],.content kbd.button.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-dark.is-inverted.is-outlined,fieldset[disabled] .content kbd.button.is-inverted.is-outlined,.content fieldset[disabled] kbd.button.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary,.docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:transparent;color:#fff}.button.is-primary:hover,.docstring>section>a.button.docs-sourcelink:hover,.button.is-primary.is-hovered,.docstring>section>a.button.is-hovered.docs-sourcelink{background-color:#43b1dc;border-color:transparent;color:#fff}.button.is-primary:focus,.docstring>section>a.button.docs-sourcelink:focus,.button.is-primary.is-focused,.docstring>section>a.button.is-focused.docs-sourcelink{border-color:transparent;color:#fff}.button.is-primary:focus:not(:active),.docstring>section>a.button.docs-sourcelink:focus:not(:active),.button.is-primary.is-focused:not(:active),.docstring>section>a.button.is-focused.docs-sourcelink:not(:active){box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.button.is-primary:active,.docstring>section>a.button.docs-sourcelink:active,.button.is-primary.is-active,.docstring>section>a.button.is-active.docs-sourcelink{background-color:#39acda;border-color:transparent;color:#fff}.button.is-primary[disabled],.docstring>section>a.button.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary,fieldset[disabled] .docstring>section>a.button.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;box-shadow:none}.button.is-primary.is-inverted,.docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted:hover,.docstring>section>a.button.is-inverted.docs-sourcelink:hover,.button.is-primary.is-inverted.is-hovered,.docstring>section>a.button.is-inverted.is-hovered.docs-sourcelink{background-color:#f2f2f2}.button.is-primary.is-inverted[disabled],.docstring>section>a.button.is-inverted.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted,fieldset[disabled] .docstring>section>a.button.is-inverted.docs-sourcelink{background-color:#fff;border-color:transparent;box-shadow:none;color:#4eb5de}.button.is-primary.is-loading::after,.docstring>section>a.button.is-loading.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined,.docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;color:#4eb5de}.button.is-primary.is-outlined:hover,.docstring>section>a.button.is-outlined.docs-sourcelink:hover,.button.is-primary.is-outlined.is-hovered,.docstring>section>a.button.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-outlined:focus,.docstring>section>a.button.is-outlined.docs-sourcelink:focus,.button.is-primary.is-outlined.is-focused,.docstring>section>a.button.is-outlined.is-focused.docs-sourcelink{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.button.is-primary.is-outlined.is-loading::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #fff #fff !important}.button.is-primary.is-outlined[disabled],.docstring>section>a.button.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-outlined,fieldset[disabled] .docstring>section>a.button.is-outlined.docs-sourcelink{background-color:transparent;border-color:#4eb5de;box-shadow:none;color:#4eb5de}.button.is-primary.is-inverted.is-outlined,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;color:#fff}.button.is-primary.is-inverted.is-outlined:hover,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:hover,.button.is-primary.is-inverted.is-outlined.is-hovered,.docstring>section>a.button.is-inverted.is-outlined.is-hovered.docs-sourcelink,.button.is-primary.is-inverted.is-outlined:focus,.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink:focus,.button.is-primary.is-inverted.is-outlined.is-focused,.docstring>section>a.button.is-inverted.is-outlined.is-focused.docs-sourcelink{background-color:#fff;color:#4eb5de}.button.is-primary.is-inverted.is-outlined.is-loading:hover::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:hover::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-hovered::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-hovered.docs-sourcelink::after,.button.is-primary.is-inverted.is-outlined.is-loading:focus::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.docs-sourcelink:focus::after,.button.is-primary.is-inverted.is-outlined.is-loading.is-focused::after,.docstring>section>a.button.is-inverted.is-outlined.is-loading.is-focused.docs-sourcelink::after{border-color:transparent transparent #4eb5de #4eb5de !important}.button.is-primary.is-inverted.is-outlined[disabled],.docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink[disabled],fieldset[disabled] .button.is-primary.is-inverted.is-outlined,fieldset[disabled] .docstring>section>a.button.is-inverted.is-outlined.docs-sourcelink{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-primary.is-light,.docstring>section>a.button.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.button.is-primary.is-light:hover,.docstring>section>a.button.is-light.docs-sourcelink:hover,.button.is-primary.is-light.is-hovered,.docstring>section>a.button.is-light.is-hovered.docs-sourcelink{background-color:#e3f3fa;border-color:transparent;color:#1a6d8e}.button.is-primary.is-light:active,.docstring>section>a.button.is-light.docs-sourcelink:active,.button.is-primary.is-light.is-active,.docstring>section>a.button.is-light.is-active.docs-sourcelink{background-color:#d8eff8;border-color:transparent;color:#1a6d8e}.button.is-link{background-color:#2e63b8;border-color:transparent;color:#fff}.button.is-link:hover,.button.is-link.is-hovered{background-color:#2b5eae;border-color:transparent;color:#fff}.button.is-link:focus,.button.is-link.is-focused{border-color:transparent;color:#fff}.button.is-link:focus:not(:active),.button.is-link.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.button.is-link:active,.button.is-link.is-active{background-color:#2958a4;border-color:transparent;color:#fff}.button.is-link[disabled],fieldset[disabled] .button.is-link{background-color:#2e63b8;border-color:#2e63b8;box-shadow:none}.button.is-link.is-inverted{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted:hover,.button.is-link.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-link.is-inverted[disabled],fieldset[disabled] .button.is-link.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#2e63b8}.button.is-link.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;color:#2e63b8}.button.is-link.is-outlined:hover,.button.is-link.is-outlined.is-hovered,.button.is-link.is-outlined:focus,.button.is-link.is-outlined.is-focused{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.button.is-link.is-outlined.is-loading::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-outlined.is-loading:hover::after,.button.is-link.is-outlined.is-loading.is-hovered::after,.button.is-link.is-outlined.is-loading:focus::after,.button.is-link.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-link.is-outlined[disabled],fieldset[disabled] .button.is-link.is-outlined{background-color:transparent;border-color:#2e63b8;box-shadow:none;color:#2e63b8}.button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-link.is-inverted.is-outlined:hover,.button.is-link.is-inverted.is-outlined.is-hovered,.button.is-link.is-inverted.is-outlined:focus,.button.is-link.is-inverted.is-outlined.is-focused{background-color:#fff;color:#2e63b8}.button.is-link.is-inverted.is-outlined.is-loading:hover::after,.button.is-link.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-link.is-inverted.is-outlined.is-loading:focus::after,.button.is-link.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #2e63b8 #2e63b8 !important}.button.is-link.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-link.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-link.is-light{background-color:#eff3fb;color:#3169c4}.button.is-link.is-light:hover,.button.is-link.is-light.is-hovered{background-color:#e4ecf8;border-color:transparent;color:#3169c4}.button.is-link.is-light:active,.button.is-link.is-light.is-active{background-color:#dae5f6;border-color:transparent;color:#3169c4}.button.is-info{background-color:#209cee;border-color:transparent;color:#fff}.button.is-info:hover,.button.is-info.is-hovered{background-color:#1497ed;border-color:transparent;color:#fff}.button.is-info:focus,.button.is-info.is-focused{border-color:transparent;color:#fff}.button.is-info:focus:not(:active),.button.is-info.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.button.is-info:active,.button.is-info.is-active{background-color:#1190e3;border-color:transparent;color:#fff}.button.is-info[disabled],fieldset[disabled] .button.is-info{background-color:#209cee;border-color:#209cee;box-shadow:none}.button.is-info.is-inverted{background-color:#fff;color:#209cee}.button.is-info.is-inverted:hover,.button.is-info.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-info.is-inverted[disabled],fieldset[disabled] .button.is-info.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#209cee}.button.is-info.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined{background-color:transparent;border-color:#209cee;color:#209cee}.button.is-info.is-outlined:hover,.button.is-info.is-outlined.is-hovered,.button.is-info.is-outlined:focus,.button.is-info.is-outlined.is-focused{background-color:#209cee;border-color:#209cee;color:#fff}.button.is-info.is-outlined.is-loading::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-outlined.is-loading:hover::after,.button.is-info.is-outlined.is-loading.is-hovered::after,.button.is-info.is-outlined.is-loading:focus::after,.button.is-info.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-info.is-outlined[disabled],fieldset[disabled] .button.is-info.is-outlined{background-color:transparent;border-color:#209cee;box-shadow:none;color:#209cee}.button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-info.is-inverted.is-outlined:hover,.button.is-info.is-inverted.is-outlined.is-hovered,.button.is-info.is-inverted.is-outlined:focus,.button.is-info.is-inverted.is-outlined.is-focused{background-color:#fff;color:#209cee}.button.is-info.is-inverted.is-outlined.is-loading:hover::after,.button.is-info.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-info.is-inverted.is-outlined.is-loading:focus::after,.button.is-info.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #209cee #209cee !important}.button.is-info.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-info.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.button.is-info.is-light:hover,.button.is-info.is-light.is-hovered{background-color:#e0f1fd;border-color:transparent;color:#0e72b4}.button.is-info.is-light:active,.button.is-info.is-light.is-active{background-color:#d4ecfc;border-color:transparent;color:#0e72b4}.button.is-success{background-color:#22c35b;border-color:transparent;color:#fff}.button.is-success:hover,.button.is-success.is-hovered{background-color:#20b856;border-color:transparent;color:#fff}.button.is-success:focus,.button.is-success.is-focused{border-color:transparent;color:#fff}.button.is-success:focus:not(:active),.button.is-success.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.button.is-success:active,.button.is-success.is-active{background-color:#1ead51;border-color:transparent;color:#fff}.button.is-success[disabled],fieldset[disabled] .button.is-success{background-color:#22c35b;border-color:#22c35b;box-shadow:none}.button.is-success.is-inverted{background-color:#fff;color:#22c35b}.button.is-success.is-inverted:hover,.button.is-success.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-success.is-inverted[disabled],fieldset[disabled] .button.is-success.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#22c35b}.button.is-success.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;color:#22c35b}.button.is-success.is-outlined:hover,.button.is-success.is-outlined.is-hovered,.button.is-success.is-outlined:focus,.button.is-success.is-outlined.is-focused{background-color:#22c35b;border-color:#22c35b;color:#fff}.button.is-success.is-outlined.is-loading::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-outlined.is-loading:hover::after,.button.is-success.is-outlined.is-loading.is-hovered::after,.button.is-success.is-outlined.is-loading:focus::after,.button.is-success.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-success.is-outlined[disabled],fieldset[disabled] .button.is-success.is-outlined{background-color:transparent;border-color:#22c35b;box-shadow:none;color:#22c35b}.button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-success.is-inverted.is-outlined:hover,.button.is-success.is-inverted.is-outlined.is-hovered,.button.is-success.is-inverted.is-outlined:focus,.button.is-success.is-inverted.is-outlined.is-focused{background-color:#fff;color:#22c35b}.button.is-success.is-inverted.is-outlined.is-loading:hover::after,.button.is-success.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-success.is-inverted.is-outlined.is-loading:focus::after,.button.is-success.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #22c35b #22c35b !important}.button.is-success.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-success.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-success.is-light{background-color:#eefcf3;color:#198f43}.button.is-success.is-light:hover,.button.is-success.is-light.is-hovered{background-color:#e3faeb;border-color:transparent;color:#198f43}.button.is-success.is-light:active,.button.is-success.is-light.is-active{background-color:#d8f8e3;border-color:transparent;color:#198f43}.button.is-warning{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:hover,.button.is-warning.is-hovered{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus,.button.is-warning.is-focused{border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning:focus:not(:active),.button.is-warning.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.button.is-warning:active,.button.is-warning.is-active{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.button.is-warning[disabled],fieldset[disabled] .button.is-warning{background-color:#ffdd57;border-color:#ffdd57;box-shadow:none}.button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted:hover,.button.is-warning.is-inverted.is-hovered{background-color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted[disabled],fieldset[disabled] .button.is-warning.is-inverted{background-color:rgba(0,0,0,0.7);border-color:transparent;box-shadow:none;color:#ffdd57}.button.is-warning.is-loading::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;color:#ffdd57}.button.is-warning.is-outlined:hover,.button.is-warning.is-outlined.is-hovered,.button.is-warning.is-outlined:focus,.button.is-warning.is-outlined.is-focused{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.button.is-warning.is-outlined.is-loading::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-outlined.is-loading:hover::after,.button.is-warning.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-outlined.is-loading:focus::after,.button.is-warning.is-outlined.is-loading.is-focused::after{border-color:transparent transparent rgba(0,0,0,0.7) rgba(0,0,0,0.7) !important}.button.is-warning.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-outlined{background-color:transparent;border-color:#ffdd57;box-shadow:none;color:#ffdd57}.button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);color:rgba(0,0,0,0.7)}.button.is-warning.is-inverted.is-outlined:hover,.button.is-warning.is-inverted.is-outlined.is-hovered,.button.is-warning.is-inverted.is-outlined:focus,.button.is-warning.is-inverted.is-outlined.is-focused{background-color:rgba(0,0,0,0.7);color:#ffdd57}.button.is-warning.is-inverted.is-outlined.is-loading:hover::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-warning.is-inverted.is-outlined.is-loading:focus::after,.button.is-warning.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #ffdd57 #ffdd57 !important}.button.is-warning.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-warning.is-inverted.is-outlined{background-color:transparent;border-color:rgba(0,0,0,0.7);box-shadow:none;color:rgba(0,0,0,0.7)}.button.is-warning.is-light{background-color:#fffbeb;color:#947600}.button.is-warning.is-light:hover,.button.is-warning.is-light.is-hovered{background-color:#fff8de;border-color:transparent;color:#947600}.button.is-warning.is-light:active,.button.is-warning.is-light.is-active{background-color:#fff6d1;border-color:transparent;color:#947600}.button.is-danger{background-color:#da0b00;border-color:transparent;color:#fff}.button.is-danger:hover,.button.is-danger.is-hovered{background-color:#cd0a00;border-color:transparent;color:#fff}.button.is-danger:focus,.button.is-danger.is-focused{border-color:transparent;color:#fff}.button.is-danger:focus:not(:active),.button.is-danger.is-focused:not(:active){box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.button.is-danger:active,.button.is-danger.is-active{background-color:#c10a00;border-color:transparent;color:#fff}.button.is-danger[disabled],fieldset[disabled] .button.is-danger{background-color:#da0b00;border-color:#da0b00;box-shadow:none}.button.is-danger.is-inverted{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted:hover,.button.is-danger.is-inverted.is-hovered{background-color:#f2f2f2}.button.is-danger.is-inverted[disabled],fieldset[disabled] .button.is-danger.is-inverted{background-color:#fff;border-color:transparent;box-shadow:none;color:#da0b00}.button.is-danger.is-loading::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;color:#da0b00}.button.is-danger.is-outlined:hover,.button.is-danger.is-outlined.is-hovered,.button.is-danger.is-outlined:focus,.button.is-danger.is-outlined.is-focused{background-color:#da0b00;border-color:#da0b00;color:#fff}.button.is-danger.is-outlined.is-loading::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-outlined.is-loading:hover::after,.button.is-danger.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-outlined.is-loading:focus::after,.button.is-danger.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #fff #fff !important}.button.is-danger.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-outlined{background-color:transparent;border-color:#da0b00;box-shadow:none;color:#da0b00}.button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;color:#fff}.button.is-danger.is-inverted.is-outlined:hover,.button.is-danger.is-inverted.is-outlined.is-hovered,.button.is-danger.is-inverted.is-outlined:focus,.button.is-danger.is-inverted.is-outlined.is-focused{background-color:#fff;color:#da0b00}.button.is-danger.is-inverted.is-outlined.is-loading:hover::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-hovered::after,.button.is-danger.is-inverted.is-outlined.is-loading:focus::after,.button.is-danger.is-inverted.is-outlined.is-loading.is-focused::after{border-color:transparent transparent #da0b00 #da0b00 !important}.button.is-danger.is-inverted.is-outlined[disabled],fieldset[disabled] .button.is-danger.is-inverted.is-outlined{background-color:transparent;border-color:#fff;box-shadow:none;color:#fff}.button.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.button.is-danger.is-light:hover,.button.is-danger.is-light.is-hovered{background-color:#ffe0de;border-color:transparent;color:#f50c00}.button.is-danger.is-light:active,.button.is-danger.is-light.is-active{background-color:#ffd3d1;border-color:transparent;color:#f50c00}.button.is-small,#documenter .docs-sidebar form.docs-search>input.button{font-size:.75rem}.button.is-small:not(.is-rounded),#documenter .docs-sidebar form.docs-search>input.button:not(.is-rounded){border-radius:2px}.button.is-normal{font-size:1rem}.button.is-medium{font-size:1.25rem}.button.is-large{font-size:1.5rem}.button[disabled],fieldset[disabled] .button{background-color:#fff;border-color:#dbdbdb;box-shadow:none;opacity:.5}.button.is-fullwidth{display:flex;width:100%}.button.is-loading{color:transparent !important;pointer-events:none}.button.is-loading::after{position:absolute;left:calc(50% - (1em * 0.5));top:calc(50% - (1em * 0.5));position:absolute !important}.button.is-static{background-color:#f5f5f5;border-color:#dbdbdb;color:#6b6b6b;box-shadow:none;pointer-events:none}.button.is-rounded,#documenter .docs-sidebar form.docs-search>input.button{border-radius:9999px;padding-left:calc(1em + 0.25em);padding-right:calc(1em + 0.25em)}.buttons{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.buttons .button{margin-bottom:0.5rem}.buttons .button:not(:last-child):not(.is-fullwidth){margin-right:.5rem}.buttons:last-child{margin-bottom:-0.5rem}.buttons:not(:last-child){margin-bottom:1rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large){font-size:.75rem}.buttons.are-small .button:not(.is-normal):not(.is-medium):not(.is-large):not(.is-rounded){border-radius:2px}.buttons.are-medium .button:not(.is-small):not(.is-normal):not(.is-large){font-size:1.25rem}.buttons.are-large .button:not(.is-small):not(.is-normal):not(.is-medium){font-size:1.5rem}.buttons.has-addons .button:not(:first-child){border-bottom-left-radius:0;border-top-left-radius:0}.buttons.has-addons .button:not(:last-child){border-bottom-right-radius:0;border-top-right-radius:0;margin-right:-1px}.buttons.has-addons .button:last-child{margin-right:0}.buttons.has-addons .button:hover,.buttons.has-addons .button.is-hovered{z-index:2}.buttons.has-addons .button:focus,.buttons.has-addons .button.is-focused,.buttons.has-addons .button:active,.buttons.has-addons .button.is-active,.buttons.has-addons .button.is-selected{z-index:3}.buttons.has-addons .button:focus:hover,.buttons.has-addons .button.is-focused:hover,.buttons.has-addons .button:active:hover,.buttons.has-addons .button.is-active:hover,.buttons.has-addons .button.is-selected:hover{z-index:4}.buttons.has-addons .button.is-expanded{flex-grow:1;flex-shrink:1}.buttons.is-centered{justify-content:center}.buttons.is-centered:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}.buttons.is-right{justify-content:flex-end}.buttons.is-right:not(.has-addons) .button:not(.is-fullwidth){margin-left:0.25rem;margin-right:0.25rem}@media screen and (max-width: 768px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.5625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.65625rem}.button.is-responsive.is-medium{font-size:.75rem}.button.is-responsive.is-large{font-size:1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.button.is-responsive.is-small,#documenter .docs-sidebar form.docs-search>input.is-responsive{font-size:.65625rem}.button.is-responsive,.button.is-responsive.is-normal{font-size:.75rem}.button.is-responsive.is-medium{font-size:1rem}.button.is-responsive.is-large{font-size:1.25rem}}.container{flex-grow:1;margin:0 auto;position:relative;width:auto}.container.is-fluid{max-width:none !important;padding-left:32px;padding-right:32px;width:100%}@media screen and (min-width: 1056px){.container{max-width:992px}}@media screen and (max-width: 1215px){.container.is-widescreen:not(.is-max-desktop){max-width:1152px}}@media screen and (max-width: 1407px){.container.is-fullhd:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}@media screen and (min-width: 1216px){.container:not(.is-max-desktop){max-width:1152px}}@media screen and (min-width: 1408px){.container:not(.is-max-desktop):not(.is-max-widescreen){max-width:1344px}}.content li+li{margin-top:0.25em}.content p:not(:last-child),.content dl:not(:last-child),.content ol:not(:last-child),.content ul:not(:last-child),.content blockquote:not(:last-child),.content pre:not(:last-child),.content table:not(:last-child){margin-bottom:1em}.content h1,.content h2,.content h3,.content h4,.content h5,.content h6{color:#222;font-weight:600;line-height:1.125}.content h1{font-size:2em;margin-bottom:0.5em}.content h1:not(:first-child){margin-top:1em}.content h2{font-size:1.75em;margin-bottom:0.5714em}.content h2:not(:first-child){margin-top:1.1428em}.content h3{font-size:1.5em;margin-bottom:0.6666em}.content h3:not(:first-child){margin-top:1.3333em}.content h4{font-size:1.25em;margin-bottom:0.8em}.content h5{font-size:1.125em;margin-bottom:0.8888em}.content h6{font-size:1em;margin-bottom:1em}.content blockquote{background-color:#f5f5f5;border-left:5px solid #dbdbdb;padding:1.25em 1.5em}.content ol{list-style-position:outside;margin-left:2em;margin-top:1em}.content ol:not([type]){list-style-type:decimal}.content ol.is-lower-alpha:not([type]){list-style-type:lower-alpha}.content ol.is-lower-roman:not([type]){list-style-type:lower-roman}.content ol.is-upper-alpha:not([type]){list-style-type:upper-alpha}.content ol.is-upper-roman:not([type]){list-style-type:upper-roman}.content ul{list-style:disc outside;margin-left:2em;margin-top:1em}.content ul ul{list-style-type:circle;margin-top:0.5em}.content ul ul ul{list-style-type:square}.content dd{margin-left:2em}.content figure{margin-left:2em;margin-right:2em;text-align:center}.content figure:not(:first-child){margin-top:2em}.content figure:not(:last-child){margin-bottom:2em}.content figure img{display:inline-block}.content figure figcaption{font-style:italic}.content pre{-webkit-overflow-scrolling:touch;overflow-x:auto;padding:0;white-space:pre;word-wrap:normal}.content sup,.content sub{font-size:75%}.content table{width:100%}.content table td,.content table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.content table th{color:#222}.content table th:not([align]){text-align:inherit}.content table thead td,.content table thead th{border-width:0 0 2px;color:#222}.content table tfoot td,.content table tfoot th{border-width:2px 0 0;color:#222}.content table tbody tr:last-child td,.content table tbody tr:last-child th{border-bottom-width:0}.content .tabs li+li{margin-top:0}.content.is-small,#documenter .docs-sidebar form.docs-search>input.content{font-size:.75rem}.content.is-normal{font-size:1rem}.content.is-medium{font-size:1.25rem}.content.is-large{font-size:1.5rem}.icon{align-items:center;display:inline-flex;justify-content:center;height:1.5rem;width:1.5rem}.icon.is-small,#documenter .docs-sidebar form.docs-search>input.icon{height:1rem;width:1rem}.icon.is-medium{height:2rem;width:2rem}.icon.is-large{height:3rem;width:3rem}.icon-text{align-items:flex-start;color:inherit;display:inline-flex;flex-wrap:wrap;line-height:1.5rem;vertical-align:top}.icon-text .icon{flex-grow:0;flex-shrink:0}.icon-text .icon:not(:last-child){margin-right:.25em}.icon-text .icon:not(:first-child){margin-left:.25em}div.icon-text{display:flex}.image,#documenter .docs-sidebar .docs-logo>img{display:block;position:relative}.image img,#documenter .docs-sidebar .docs-logo>img img{display:block;height:auto;width:100%}.image img.is-rounded,#documenter .docs-sidebar .docs-logo>img img.is-rounded{border-radius:9999px}.image.is-fullwidth,#documenter .docs-sidebar .docs-logo>img.is-fullwidth{width:100%}.image.is-square img,#documenter .docs-sidebar .docs-logo>img.is-square img,.image.is-square .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-square .has-ratio,.image.is-1by1 img,#documenter .docs-sidebar .docs-logo>img.is-1by1 img,.image.is-1by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by1 .has-ratio,.image.is-5by4 img,#documenter .docs-sidebar .docs-logo>img.is-5by4 img,.image.is-5by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by4 .has-ratio,.image.is-4by3 img,#documenter .docs-sidebar .docs-logo>img.is-4by3 img,.image.is-4by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by3 .has-ratio,.image.is-3by2 img,#documenter .docs-sidebar .docs-logo>img.is-3by2 img,.image.is-3by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by2 .has-ratio,.image.is-5by3 img,#documenter .docs-sidebar .docs-logo>img.is-5by3 img,.image.is-5by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-5by3 .has-ratio,.image.is-16by9 img,#documenter .docs-sidebar .docs-logo>img.is-16by9 img,.image.is-16by9 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-16by9 .has-ratio,.image.is-2by1 img,#documenter .docs-sidebar .docs-logo>img.is-2by1 img,.image.is-2by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by1 .has-ratio,.image.is-3by1 img,#documenter .docs-sidebar .docs-logo>img.is-3by1 img,.image.is-3by1 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by1 .has-ratio,.image.is-4by5 img,#documenter .docs-sidebar .docs-logo>img.is-4by5 img,.image.is-4by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-4by5 .has-ratio,.image.is-3by4 img,#documenter .docs-sidebar .docs-logo>img.is-3by4 img,.image.is-3by4 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by4 .has-ratio,.image.is-2by3 img,#documenter .docs-sidebar .docs-logo>img.is-2by3 img,.image.is-2by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-2by3 .has-ratio,.image.is-3by5 img,#documenter .docs-sidebar .docs-logo>img.is-3by5 img,.image.is-3by5 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-3by5 .has-ratio,.image.is-9by16 img,#documenter .docs-sidebar .docs-logo>img.is-9by16 img,.image.is-9by16 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-9by16 .has-ratio,.image.is-1by2 img,#documenter .docs-sidebar .docs-logo>img.is-1by2 img,.image.is-1by2 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by2 .has-ratio,.image.is-1by3 img,#documenter .docs-sidebar .docs-logo>img.is-1by3 img,.image.is-1by3 .has-ratio,#documenter .docs-sidebar .docs-logo>img.is-1by3 .has-ratio{height:100%;width:100%}.image.is-square,#documenter .docs-sidebar .docs-logo>img.is-square,.image.is-1by1,#documenter .docs-sidebar .docs-logo>img.is-1by1{padding-top:100%}.image.is-5by4,#documenter .docs-sidebar .docs-logo>img.is-5by4{padding-top:80%}.image.is-4by3,#documenter .docs-sidebar .docs-logo>img.is-4by3{padding-top:75%}.image.is-3by2,#documenter .docs-sidebar .docs-logo>img.is-3by2{padding-top:66.6666%}.image.is-5by3,#documenter .docs-sidebar .docs-logo>img.is-5by3{padding-top:60%}.image.is-16by9,#documenter .docs-sidebar .docs-logo>img.is-16by9{padding-top:56.25%}.image.is-2by1,#documenter .docs-sidebar .docs-logo>img.is-2by1{padding-top:50%}.image.is-3by1,#documenter .docs-sidebar .docs-logo>img.is-3by1{padding-top:33.3333%}.image.is-4by5,#documenter .docs-sidebar .docs-logo>img.is-4by5{padding-top:125%}.image.is-3by4,#documenter .docs-sidebar .docs-logo>img.is-3by4{padding-top:133.3333%}.image.is-2by3,#documenter .docs-sidebar .docs-logo>img.is-2by3{padding-top:150%}.image.is-3by5,#documenter .docs-sidebar .docs-logo>img.is-3by5{padding-top:166.6666%}.image.is-9by16,#documenter .docs-sidebar .docs-logo>img.is-9by16{padding-top:177.7777%}.image.is-1by2,#documenter .docs-sidebar .docs-logo>img.is-1by2{padding-top:200%}.image.is-1by3,#documenter .docs-sidebar .docs-logo>img.is-1by3{padding-top:300%}.image.is-16x16,#documenter .docs-sidebar .docs-logo>img.is-16x16{height:16px;width:16px}.image.is-24x24,#documenter .docs-sidebar .docs-logo>img.is-24x24{height:24px;width:24px}.image.is-32x32,#documenter .docs-sidebar .docs-logo>img.is-32x32{height:32px;width:32px}.image.is-48x48,#documenter .docs-sidebar .docs-logo>img.is-48x48{height:48px;width:48px}.image.is-64x64,#documenter .docs-sidebar .docs-logo>img.is-64x64{height:64px;width:64px}.image.is-96x96,#documenter .docs-sidebar .docs-logo>img.is-96x96{height:96px;width:96px}.image.is-128x128,#documenter .docs-sidebar .docs-logo>img.is-128x128{height:128px;width:128px}.notification{background-color:#f5f5f5;border-radius:4px;position:relative;padding:1.25rem 2.5rem 1.25rem 1.5rem}.notification a:not(.button):not(.dropdown-item){color:currentColor;text-decoration:underline}.notification strong{color:currentColor}.notification code,.notification pre{background:#fff}.notification pre code{background:transparent}.notification>.delete{right:.5rem;position:absolute;top:0.5rem}.notification .title,.notification .subtitle,.notification .content{color:currentColor}.notification.is-white{background-color:#fff;color:#0a0a0a}.notification.is-black{background-color:#0a0a0a;color:#fff}.notification.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.notification.is-dark,.content kbd.notification{background-color:#363636;color:#fff}.notification.is-primary,.docstring>section>a.notification.docs-sourcelink{background-color:#4eb5de;color:#fff}.notification.is-primary.is-light,.docstring>section>a.notification.is-light.docs-sourcelink{background-color:#eef8fc;color:#1a6d8e}.notification.is-link{background-color:#2e63b8;color:#fff}.notification.is-link.is-light{background-color:#eff3fb;color:#3169c4}.notification.is-info{background-color:#209cee;color:#fff}.notification.is-info.is-light{background-color:#ecf7fe;color:#0e72b4}.notification.is-success{background-color:#22c35b;color:#fff}.notification.is-success.is-light{background-color:#eefcf3;color:#198f43}.notification.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.notification.is-warning.is-light{background-color:#fffbeb;color:#947600}.notification.is-danger{background-color:#da0b00;color:#fff}.notification.is-danger.is-light{background-color:#ffeceb;color:#f50c00}.progress{-moz-appearance:none;-webkit-appearance:none;border:none;border-radius:9999px;display:block;height:1rem;overflow:hidden;padding:0;width:100%}.progress::-webkit-progress-bar{background-color:#ededed}.progress::-webkit-progress-value{background-color:#222}.progress::-moz-progress-bar{background-color:#222}.progress::-ms-fill{background-color:#222;border:none}.progress.is-white::-webkit-progress-value{background-color:#fff}.progress.is-white::-moz-progress-bar{background-color:#fff}.progress.is-white::-ms-fill{background-color:#fff}.progress.is-white:indeterminate{background-image:linear-gradient(to right, #fff 30%, #ededed 30%)}.progress.is-black::-webkit-progress-value{background-color:#0a0a0a}.progress.is-black::-moz-progress-bar{background-color:#0a0a0a}.progress.is-black::-ms-fill{background-color:#0a0a0a}.progress.is-black:indeterminate{background-image:linear-gradient(to right, #0a0a0a 30%, #ededed 30%)}.progress.is-light::-webkit-progress-value{background-color:#f5f5f5}.progress.is-light::-moz-progress-bar{background-color:#f5f5f5}.progress.is-light::-ms-fill{background-color:#f5f5f5}.progress.is-light:indeterminate{background-image:linear-gradient(to right, #f5f5f5 30%, #ededed 30%)}.progress.is-dark::-webkit-progress-value,.content kbd.progress::-webkit-progress-value{background-color:#363636}.progress.is-dark::-moz-progress-bar,.content kbd.progress::-moz-progress-bar{background-color:#363636}.progress.is-dark::-ms-fill,.content kbd.progress::-ms-fill{background-color:#363636}.progress.is-dark:indeterminate,.content kbd.progress:indeterminate{background-image:linear-gradient(to right, #363636 30%, #ededed 30%)}.progress.is-primary::-webkit-progress-value,.docstring>section>a.progress.docs-sourcelink::-webkit-progress-value{background-color:#4eb5de}.progress.is-primary::-moz-progress-bar,.docstring>section>a.progress.docs-sourcelink::-moz-progress-bar{background-color:#4eb5de}.progress.is-primary::-ms-fill,.docstring>section>a.progress.docs-sourcelink::-ms-fill{background-color:#4eb5de}.progress.is-primary:indeterminate,.docstring>section>a.progress.docs-sourcelink:indeterminate{background-image:linear-gradient(to right, #4eb5de 30%, #ededed 30%)}.progress.is-link::-webkit-progress-value{background-color:#2e63b8}.progress.is-link::-moz-progress-bar{background-color:#2e63b8}.progress.is-link::-ms-fill{background-color:#2e63b8}.progress.is-link:indeterminate{background-image:linear-gradient(to right, #2e63b8 30%, #ededed 30%)}.progress.is-info::-webkit-progress-value{background-color:#209cee}.progress.is-info::-moz-progress-bar{background-color:#209cee}.progress.is-info::-ms-fill{background-color:#209cee}.progress.is-info:indeterminate{background-image:linear-gradient(to right, #209cee 30%, #ededed 30%)}.progress.is-success::-webkit-progress-value{background-color:#22c35b}.progress.is-success::-moz-progress-bar{background-color:#22c35b}.progress.is-success::-ms-fill{background-color:#22c35b}.progress.is-success:indeterminate{background-image:linear-gradient(to right, #22c35b 30%, #ededed 30%)}.progress.is-warning::-webkit-progress-value{background-color:#ffdd57}.progress.is-warning::-moz-progress-bar{background-color:#ffdd57}.progress.is-warning::-ms-fill{background-color:#ffdd57}.progress.is-warning:indeterminate{background-image:linear-gradient(to right, #ffdd57 30%, #ededed 30%)}.progress.is-danger::-webkit-progress-value{background-color:#da0b00}.progress.is-danger::-moz-progress-bar{background-color:#da0b00}.progress.is-danger::-ms-fill{background-color:#da0b00}.progress.is-danger:indeterminate{background-image:linear-gradient(to right, #da0b00 30%, #ededed 30%)}.progress:indeterminate{animation-duration:1.5s;animation-iteration-count:infinite;animation-name:moveIndeterminate;animation-timing-function:linear;background-color:#ededed;background-image:linear-gradient(to right, #222 30%, #ededed 30%);background-position:top left;background-repeat:no-repeat;background-size:150% 150%}.progress:indeterminate::-webkit-progress-bar{background-color:transparent}.progress:indeterminate::-moz-progress-bar{background-color:transparent}.progress:indeterminate::-ms-fill{animation-name:none}.progress.is-small,#documenter .docs-sidebar form.docs-search>input.progress{height:.75rem}.progress.is-medium{height:1.25rem}.progress.is-large{height:1.5rem}@keyframes moveIndeterminate{from{background-position:200% 0}to{background-position:-200% 0}}.table{background-color:#fff;color:#222}.table td,.table th{border:1px solid #dbdbdb;border-width:0 0 1px;padding:0.5em 0.75em;vertical-align:top}.table td.is-white,.table th.is-white{background-color:#fff;border-color:#fff;color:#0a0a0a}.table td.is-black,.table th.is-black{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.table td.is-light,.table th.is-light{background-color:#f5f5f5;border-color:#f5f5f5;color:rgba(0,0,0,0.7)}.table td.is-dark,.table th.is-dark{background-color:#363636;border-color:#363636;color:#fff}.table td.is-primary,.table th.is-primary{background-color:#4eb5de;border-color:#4eb5de;color:#fff}.table td.is-link,.table th.is-link{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.table td.is-info,.table th.is-info{background-color:#209cee;border-color:#209cee;color:#fff}.table td.is-success,.table th.is-success{background-color:#22c35b;border-color:#22c35b;color:#fff}.table td.is-warning,.table th.is-warning{background-color:#ffdd57;border-color:#ffdd57;color:rgba(0,0,0,0.7)}.table td.is-danger,.table th.is-danger{background-color:#da0b00;border-color:#da0b00;color:#fff}.table td.is-narrow,.table th.is-narrow{white-space:nowrap;width:1%}.table td.is-selected,.table th.is-selected{background-color:#4eb5de;color:#fff}.table td.is-selected a,.table td.is-selected strong,.table th.is-selected a,.table th.is-selected strong{color:currentColor}.table td.is-vcentered,.table th.is-vcentered{vertical-align:middle}.table th{color:#222}.table th:not([align]){text-align:left}.table tr.is-selected{background-color:#4eb5de;color:#fff}.table tr.is-selected a,.table tr.is-selected strong{color:currentColor}.table tr.is-selected td,.table tr.is-selected th{border-color:#fff;color:currentColor}.table thead{background-color:rgba(0,0,0,0)}.table thead td,.table thead th{border-width:0 0 2px;color:#222}.table tfoot{background-color:rgba(0,0,0,0)}.table tfoot td,.table tfoot th{border-width:2px 0 0;color:#222}.table tbody{background-color:rgba(0,0,0,0)}.table tbody tr:last-child td,.table tbody tr:last-child th{border-bottom-width:0}.table.is-bordered td,.table.is-bordered th{border-width:1px}.table.is-bordered tr:last-child td,.table.is-bordered tr:last-child th{border-bottom-width:1px}.table.is-fullwidth{width:100%}.table.is-hoverable tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover{background-color:#fafafa}.table.is-hoverable.is-striped tbody tr:not(.is-selected):hover:nth-child(even){background-color:#f5f5f5}.table.is-narrow td,.table.is-narrow th{padding:0.25em 0.5em}.table.is-striped tbody tr:not(.is-selected):nth-child(even){background-color:#fafafa}.table-container{-webkit-overflow-scrolling:touch;overflow:auto;overflow-y:hidden;max-width:100%}.tags{align-items:center;display:flex;flex-wrap:wrap;justify-content:flex-start}.tags .tag,.tags .content kbd,.content .tags kbd,.tags .docstring>section>a.docs-sourcelink{margin-bottom:0.5rem}.tags .tag:not(:last-child),.tags .content kbd:not(:last-child),.content .tags kbd:not(:last-child),.tags .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:.5rem}.tags:last-child{margin-bottom:-0.5rem}.tags:not(:last-child){margin-bottom:1rem}.tags.are-medium .tag:not(.is-normal):not(.is-large),.tags.are-medium .content kbd:not(.is-normal):not(.is-large),.content .tags.are-medium kbd:not(.is-normal):not(.is-large),.tags.are-medium .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-large){font-size:1rem}.tags.are-large .tag:not(.is-normal):not(.is-medium),.tags.are-large .content kbd:not(.is-normal):not(.is-medium),.content .tags.are-large kbd:not(.is-normal):not(.is-medium),.tags.are-large .docstring>section>a.docs-sourcelink:not(.is-normal):not(.is-medium){font-size:1.25rem}.tags.is-centered{justify-content:center}.tags.is-centered .tag,.tags.is-centered .content kbd,.content .tags.is-centered kbd,.tags.is-centered .docstring>section>a.docs-sourcelink{margin-right:0.25rem;margin-left:0.25rem}.tags.is-right{justify-content:flex-end}.tags.is-right .tag:not(:first-child),.tags.is-right .content kbd:not(:first-child),.content .tags.is-right kbd:not(:first-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0.5rem}.tags.is-right .tag:not(:last-child),.tags.is-right .content kbd:not(:last-child),.content .tags.is-right kbd:not(:last-child),.tags.is-right .docstring>section>a.docs-sourcelink:not(:last-child){margin-right:0}.tags.has-addons .tag,.tags.has-addons .content kbd,.content .tags.has-addons kbd,.tags.has-addons .docstring>section>a.docs-sourcelink{margin-right:0}.tags.has-addons .tag:not(:first-child),.tags.has-addons .content kbd:not(:first-child),.content .tags.has-addons kbd:not(:first-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:first-child){margin-left:0;border-top-left-radius:0;border-bottom-left-radius:0}.tags.has-addons .tag:not(:last-child),.tags.has-addons .content kbd:not(:last-child),.content .tags.has-addons kbd:not(:last-child),.tags.has-addons .docstring>section>a.docs-sourcelink:not(:last-child){border-top-right-radius:0;border-bottom-right-radius:0}.tag:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink:not(body){align-items:center;background-color:#f5f5f5;border-radius:4px;color:#222;display:inline-flex;font-size:.75rem;height:2em;justify-content:center;line-height:1.5;padding-left:0.75em;padding-right:0.75em;white-space:nowrap}.tag:not(body) .delete,.content kbd:not(body) .delete,.docstring>section>a.docs-sourcelink:not(body) .delete{margin-left:.25rem;margin-right:-.375rem}.tag.is-white:not(body),.content kbd.is-white:not(body),.docstring>section>a.docs-sourcelink.is-white:not(body){background-color:#fff;color:#0a0a0a}.tag.is-black:not(body),.content kbd.is-black:not(body),.docstring>section>a.docs-sourcelink.is-black:not(body){background-color:#0a0a0a;color:#fff}.tag.is-light:not(body),.content kbd.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.tag.is-dark:not(body),.content kbd:not(body),.docstring>section>a.docs-sourcelink.is-dark:not(body),.content .docstring>section>kbd:not(body){background-color:#363636;color:#fff}.tag.is-primary:not(body),.content kbd.is-primary:not(body),.docstring>section>a.docs-sourcelink:not(body){background-color:#4eb5de;color:#fff}.tag.is-primary.is-light:not(body),.content kbd.is-primary.is-light:not(body),.docstring>section>a.docs-sourcelink.is-light:not(body){background-color:#eef8fc;color:#1a6d8e}.tag.is-link:not(body),.content kbd.is-link:not(body),.docstring>section>a.docs-sourcelink.is-link:not(body){background-color:#2e63b8;color:#fff}.tag.is-link.is-light:not(body),.content kbd.is-link.is-light:not(body),.docstring>section>a.docs-sourcelink.is-link.is-light:not(body){background-color:#eff3fb;color:#3169c4}.tag.is-info:not(body),.content kbd.is-info:not(body),.docstring>section>a.docs-sourcelink.is-info:not(body){background-color:#209cee;color:#fff}.tag.is-info.is-light:not(body),.content kbd.is-info.is-light:not(body),.docstring>section>a.docs-sourcelink.is-info.is-light:not(body){background-color:#ecf7fe;color:#0e72b4}.tag.is-success:not(body),.content kbd.is-success:not(body),.docstring>section>a.docs-sourcelink.is-success:not(body){background-color:#22c35b;color:#fff}.tag.is-success.is-light:not(body),.content kbd.is-success.is-light:not(body),.docstring>section>a.docs-sourcelink.is-success.is-light:not(body){background-color:#eefcf3;color:#198f43}.tag.is-warning:not(body),.content kbd.is-warning:not(body),.docstring>section>a.docs-sourcelink.is-warning:not(body){background-color:#ffdd57;color:rgba(0,0,0,0.7)}.tag.is-warning.is-light:not(body),.content kbd.is-warning.is-light:not(body),.docstring>section>a.docs-sourcelink.is-warning.is-light:not(body){background-color:#fffbeb;color:#947600}.tag.is-danger:not(body),.content kbd.is-danger:not(body),.docstring>section>a.docs-sourcelink.is-danger:not(body){background-color:#da0b00;color:#fff}.tag.is-danger.is-light:not(body),.content kbd.is-danger.is-light:not(body),.docstring>section>a.docs-sourcelink.is-danger.is-light:not(body){background-color:#ffeceb;color:#f50c00}.tag.is-normal:not(body),.content kbd.is-normal:not(body),.docstring>section>a.docs-sourcelink.is-normal:not(body){font-size:.75rem}.tag.is-medium:not(body),.content kbd.is-medium:not(body),.docstring>section>a.docs-sourcelink.is-medium:not(body){font-size:1rem}.tag.is-large:not(body),.content kbd.is-large:not(body),.docstring>section>a.docs-sourcelink.is-large:not(body){font-size:1.25rem}.tag:not(body) .icon:first-child:not(:last-child),.content kbd:not(body) .icon:first-child:not(:last-child),.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:not(:last-child){margin-left:-.375em;margin-right:.1875em}.tag:not(body) .icon:last-child:not(:first-child),.content kbd:not(body) .icon:last-child:not(:first-child),.docstring>section>a.docs-sourcelink:not(body) .icon:last-child:not(:first-child){margin-left:.1875em;margin-right:-.375em}.tag:not(body) .icon:first-child:last-child,.content kbd:not(body) .icon:first-child:last-child,.docstring>section>a.docs-sourcelink:not(body) .icon:first-child:last-child{margin-left:-.375em;margin-right:-.375em}.tag.is-delete:not(body),.content kbd.is-delete:not(body),.docstring>section>a.docs-sourcelink.is-delete:not(body){margin-left:1px;padding:0;position:relative;width:2em}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before,.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{background-color:currentColor;content:"";display:block;left:50%;position:absolute;top:50%;transform:translateX(-50%) translateY(-50%) rotate(45deg);transform-origin:center center}.tag.is-delete:not(body)::before,.content kbd.is-delete:not(body)::before,.docstring>section>a.docs-sourcelink.is-delete:not(body)::before{height:1px;width:50%}.tag.is-delete:not(body)::after,.content kbd.is-delete:not(body)::after,.docstring>section>a.docs-sourcelink.is-delete:not(body)::after{height:50%;width:1px}.tag.is-delete:not(body):hover,.content kbd.is-delete:not(body):hover,.docstring>section>a.docs-sourcelink.is-delete:not(body):hover,.tag.is-delete:not(body):focus,.content kbd.is-delete:not(body):focus,.docstring>section>a.docs-sourcelink.is-delete:not(body):focus{background-color:#e8e8e8}.tag.is-delete:not(body):active,.content kbd.is-delete:not(body):active,.docstring>section>a.docs-sourcelink.is-delete:not(body):active{background-color:#dbdbdb}.tag.is-rounded:not(body),#documenter .docs-sidebar form.docs-search>input:not(body),.content kbd.is-rounded:not(body),#documenter .docs-sidebar .content form.docs-search>input:not(body),.docstring>section>a.docs-sourcelink.is-rounded:not(body){border-radius:9999px}a.tag:hover,.docstring>section>a.docs-sourcelink:hover{text-decoration:underline}.title,.subtitle{word-break:break-word}.title em,.title span,.subtitle em,.subtitle span{font-weight:inherit}.title sub,.subtitle sub{font-size:.75em}.title sup,.subtitle sup{font-size:.75em}.title .tag,.title .content kbd,.content .title kbd,.title .docstring>section>a.docs-sourcelink,.subtitle .tag,.subtitle .content kbd,.content .subtitle kbd,.subtitle .docstring>section>a.docs-sourcelink{vertical-align:middle}.title{color:#222;font-size:2rem;font-weight:600;line-height:1.125}.title strong{color:inherit;font-weight:inherit}.title:not(.is-spaced)+.subtitle{margin-top:-1.25rem}.title.is-1{font-size:3rem}.title.is-2{font-size:2.5rem}.title.is-3{font-size:2rem}.title.is-4{font-size:1.5rem}.title.is-5{font-size:1.25rem}.title.is-6{font-size:1rem}.title.is-7{font-size:.75rem}.subtitle{color:#222;font-size:1.25rem;font-weight:400;line-height:1.25}.subtitle strong{color:#222;font-weight:600}.subtitle:not(.is-spaced)+.title{margin-top:-1.25rem}.subtitle.is-1{font-size:3rem}.subtitle.is-2{font-size:2.5rem}.subtitle.is-3{font-size:2rem}.subtitle.is-4{font-size:1.5rem}.subtitle.is-5{font-size:1.25rem}.subtitle.is-6{font-size:1rem}.subtitle.is-7{font-size:.75rem}.heading{display:block;font-size:11px;letter-spacing:1px;margin-bottom:5px;text-transform:uppercase}.number{align-items:center;background-color:#f5f5f5;border-radius:9999px;display:inline-flex;font-size:1.25rem;height:2em;justify-content:center;margin-right:1.5rem;min-width:2.5em;padding:0.25rem 0.5rem;text-align:center;vertical-align:top}.select select,.textarea,.input,#documenter .docs-sidebar form.docs-search>input{background-color:#fff;border-color:#dbdbdb;border-radius:4px;color:#222}.select select::-moz-placeholder,.textarea::-moz-placeholder,.input::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input::-moz-placeholder{color:#707070}.select select::-webkit-input-placeholder,.textarea::-webkit-input-placeholder,.input::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder{color:#707070}.select select:-moz-placeholder,.textarea:-moz-placeholder,.input:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input:-moz-placeholder{color:#707070}.select select:-ms-input-placeholder,.textarea:-ms-input-placeholder,.input:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder{color:#707070}.select select:hover,.textarea:hover,.input:hover,#documenter .docs-sidebar form.docs-search>input:hover,.select select.is-hovered,.is-hovered.textarea,.is-hovered.input,#documenter .docs-sidebar form.docs-search>input.is-hovered{border-color:#b5b5b5}.select select:focus,.textarea:focus,.input:focus,#documenter .docs-sidebar form.docs-search>input:focus,.select select.is-focused,.is-focused.textarea,.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.select select:active,.textarea:active,.input:active,#documenter .docs-sidebar form.docs-search>input:active,.select select.is-active,.is-active.textarea,.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{border-color:#2e63b8;box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select select[disabled],.textarea[disabled],.input[disabled],#documenter .docs-sidebar form.docs-search>input[disabled],fieldset[disabled] .select select,.select fieldset[disabled] select,fieldset[disabled] .textarea,fieldset[disabled] .input,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input{background-color:#f5f5f5;border-color:#f5f5f5;box-shadow:none;color:#6b6b6b}.select select[disabled]::-moz-placeholder,.textarea[disabled]::-moz-placeholder,.input[disabled]::-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-moz-placeholder,fieldset[disabled] .select select::-moz-placeholder,.select fieldset[disabled] select::-moz-placeholder,fieldset[disabled] .textarea::-moz-placeholder,fieldset[disabled] .input::-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]::-webkit-input-placeholder,.textarea[disabled]::-webkit-input-placeholder,.input[disabled]::-webkit-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]::-webkit-input-placeholder,fieldset[disabled] .select select::-webkit-input-placeholder,.select fieldset[disabled] select::-webkit-input-placeholder,fieldset[disabled] .textarea::-webkit-input-placeholder,fieldset[disabled] .input::-webkit-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input::-webkit-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input::-webkit-input-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-moz-placeholder,.textarea[disabled]:-moz-placeholder,.input[disabled]:-moz-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-moz-placeholder,fieldset[disabled] .select select:-moz-placeholder,.select fieldset[disabled] select:-moz-placeholder,fieldset[disabled] .textarea:-moz-placeholder,fieldset[disabled] .input:-moz-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-moz-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-moz-placeholder{color:rgba(107,107,107,0.3)}.select select[disabled]:-ms-input-placeholder,.textarea[disabled]:-ms-input-placeholder,.input[disabled]:-ms-input-placeholder,#documenter .docs-sidebar form.docs-search>input[disabled]:-ms-input-placeholder,fieldset[disabled] .select select:-ms-input-placeholder,.select fieldset[disabled] select:-ms-input-placeholder,fieldset[disabled] .textarea:-ms-input-placeholder,fieldset[disabled] .input:-ms-input-placeholder,fieldset[disabled] #documenter .docs-sidebar form.docs-search>input:-ms-input-placeholder,#documenter .docs-sidebar fieldset[disabled] form.docs-search>input:-ms-input-placeholder{color:rgba(107,107,107,0.3)}.textarea,.input,#documenter .docs-sidebar form.docs-search>input{box-shadow:inset 0 0.0625em 0.125em rgba(10,10,10,0.05);max-width:100%;width:100%}.textarea[readonly],.input[readonly],#documenter .docs-sidebar form.docs-search>input[readonly]{box-shadow:none}.is-white.textarea,.is-white.input,#documenter .docs-sidebar form.docs-search>input.is-white{border-color:#fff}.is-white.textarea:focus,.is-white.input:focus,#documenter .docs-sidebar form.docs-search>input.is-white:focus,.is-white.is-focused.textarea,.is-white.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-white.textarea:active,.is-white.input:active,#documenter .docs-sidebar form.docs-search>input.is-white:active,.is-white.is-active.textarea,.is-white.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.is-black.textarea,.is-black.input,#documenter .docs-sidebar form.docs-search>input.is-black{border-color:#0a0a0a}.is-black.textarea:focus,.is-black.input:focus,#documenter .docs-sidebar form.docs-search>input.is-black:focus,.is-black.is-focused.textarea,.is-black.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-black.textarea:active,.is-black.input:active,#documenter .docs-sidebar form.docs-search>input.is-black:active,.is-black.is-active.textarea,.is-black.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.is-light.textarea,.is-light.input,#documenter .docs-sidebar form.docs-search>input.is-light{border-color:#f5f5f5}.is-light.textarea:focus,.is-light.input:focus,#documenter .docs-sidebar form.docs-search>input.is-light:focus,.is-light.is-focused.textarea,.is-light.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-light.textarea:active,.is-light.input:active,#documenter .docs-sidebar form.docs-search>input.is-light:active,.is-light.is-active.textarea,.is-light.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.is-dark.textarea,.content kbd.textarea,.is-dark.input,#documenter .docs-sidebar form.docs-search>input.is-dark,.content kbd.input{border-color:#363636}.is-dark.textarea:focus,.content kbd.textarea:focus,.is-dark.input:focus,#documenter .docs-sidebar form.docs-search>input.is-dark:focus,.content kbd.input:focus,.is-dark.is-focused.textarea,.content kbd.is-focused.textarea,.is-dark.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.content kbd.is-focused.input,#documenter .docs-sidebar .content form.docs-search>input.is-focused,.is-dark.textarea:active,.content kbd.textarea:active,.is-dark.input:active,#documenter .docs-sidebar form.docs-search>input.is-dark:active,.content kbd.input:active,.is-dark.is-active.textarea,.content kbd.is-active.textarea,.is-dark.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.content kbd.is-active.input,#documenter .docs-sidebar .content form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.is-primary.textarea,.docstring>section>a.textarea.docs-sourcelink,.is-primary.input,#documenter .docs-sidebar form.docs-search>input.is-primary,.docstring>section>a.input.docs-sourcelink{border-color:#4eb5de}.is-primary.textarea:focus,.docstring>section>a.textarea.docs-sourcelink:focus,.is-primary.input:focus,#documenter .docs-sidebar form.docs-search>input.is-primary:focus,.docstring>section>a.input.docs-sourcelink:focus,.is-primary.is-focused.textarea,.docstring>section>a.is-focused.textarea.docs-sourcelink,.is-primary.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.docstring>section>a.is-focused.input.docs-sourcelink,.is-primary.textarea:active,.docstring>section>a.textarea.docs-sourcelink:active,.is-primary.input:active,#documenter .docs-sidebar form.docs-search>input.is-primary:active,.docstring>section>a.input.docs-sourcelink:active,.is-primary.is-active.textarea,.docstring>section>a.is-active.textarea.docs-sourcelink,.is-primary.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active,.docstring>section>a.is-active.input.docs-sourcelink{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.is-link.textarea,.is-link.input,#documenter .docs-sidebar form.docs-search>input.is-link{border-color:#2e63b8}.is-link.textarea:focus,.is-link.input:focus,#documenter .docs-sidebar form.docs-search>input.is-link:focus,.is-link.is-focused.textarea,.is-link.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-link.textarea:active,.is-link.input:active,#documenter .docs-sidebar form.docs-search>input.is-link:active,.is-link.is-active.textarea,.is-link.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.is-info.textarea,.is-info.input,#documenter .docs-sidebar form.docs-search>input.is-info{border-color:#209cee}.is-info.textarea:focus,.is-info.input:focus,#documenter .docs-sidebar form.docs-search>input.is-info:focus,.is-info.is-focused.textarea,.is-info.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-info.textarea:active,.is-info.input:active,#documenter .docs-sidebar form.docs-search>input.is-info:active,.is-info.is-active.textarea,.is-info.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.is-success.textarea,.is-success.input,#documenter .docs-sidebar form.docs-search>input.is-success{border-color:#22c35b}.is-success.textarea:focus,.is-success.input:focus,#documenter .docs-sidebar form.docs-search>input.is-success:focus,.is-success.is-focused.textarea,.is-success.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-success.textarea:active,.is-success.input:active,#documenter .docs-sidebar form.docs-search>input.is-success:active,.is-success.is-active.textarea,.is-success.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.is-warning.textarea,.is-warning.input,#documenter .docs-sidebar form.docs-search>input.is-warning{border-color:#ffdd57}.is-warning.textarea:focus,.is-warning.input:focus,#documenter .docs-sidebar form.docs-search>input.is-warning:focus,.is-warning.is-focused.textarea,.is-warning.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-warning.textarea:active,.is-warning.input:active,#documenter .docs-sidebar form.docs-search>input.is-warning:active,.is-warning.is-active.textarea,.is-warning.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.is-danger.textarea,.is-danger.input,#documenter .docs-sidebar form.docs-search>input.is-danger{border-color:#da0b00}.is-danger.textarea:focus,.is-danger.input:focus,#documenter .docs-sidebar form.docs-search>input.is-danger:focus,.is-danger.is-focused.textarea,.is-danger.is-focused.input,#documenter .docs-sidebar form.docs-search>input.is-focused,.is-danger.textarea:active,.is-danger.input:active,#documenter .docs-sidebar form.docs-search>input.is-danger:active,.is-danger.is-active.textarea,.is-danger.is-active.input,#documenter .docs-sidebar form.docs-search>input.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.is-small.textarea,.is-small.input,#documenter .docs-sidebar form.docs-search>input{border-radius:2px;font-size:.75rem}.is-medium.textarea,.is-medium.input,#documenter .docs-sidebar form.docs-search>input.is-medium{font-size:1.25rem}.is-large.textarea,.is-large.input,#documenter .docs-sidebar form.docs-search>input.is-large{font-size:1.5rem}.is-fullwidth.textarea,.is-fullwidth.input,#documenter .docs-sidebar form.docs-search>input.is-fullwidth{display:block;width:100%}.is-inline.textarea,.is-inline.input,#documenter .docs-sidebar form.docs-search>input.is-inline{display:inline;width:auto}.input.is-rounded,#documenter .docs-sidebar form.docs-search>input{border-radius:9999px;padding-left:calc(calc(0.75em - 1px) + 0.375em);padding-right:calc(calc(0.75em - 1px) + 0.375em)}.input.is-static,#documenter .docs-sidebar form.docs-search>input.is-static{background-color:transparent;border-color:transparent;box-shadow:none;padding-left:0;padding-right:0}.textarea{display:block;max-width:100%;min-width:100%;padding:calc(0.75em - 1px);resize:vertical}.textarea:not([rows]){max-height:40em;min-height:8em}.textarea[rows]{height:initial}.textarea.has-fixed-size{resize:none}.radio,.checkbox{cursor:pointer;display:inline-block;line-height:1.25;position:relative}.radio input,.checkbox input{cursor:pointer}.radio:hover,.checkbox:hover{color:#222}.radio[disabled],.checkbox[disabled],fieldset[disabled] .radio,fieldset[disabled] .checkbox,.radio input[disabled],.checkbox input[disabled]{color:#6b6b6b;cursor:not-allowed}.radio+.radio{margin-left:.5em}.select{display:inline-block;max-width:100%;position:relative;vertical-align:top}.select:not(.is-multiple){height:2.5em}.select:not(.is-multiple):not(.is-loading)::after{border-color:#2e63b8;right:1.125em;z-index:4}.select.is-rounded select,#documenter .docs-sidebar form.docs-search>input.select select{border-radius:9999px;padding-left:1em}.select select{cursor:pointer;display:block;font-size:1em;max-width:100%;outline:none}.select select::-ms-expand{display:none}.select select[disabled]:hover,fieldset[disabled] .select select:hover{border-color:#f5f5f5}.select select:not([multiple]){padding-right:2.5em}.select select[multiple]{height:auto;padding:0}.select select[multiple] option{padding:0.5em 1em}.select:not(.is-multiple):not(.is-loading):hover::after{border-color:#222}.select.is-white:not(:hover)::after{border-color:#fff}.select.is-white select{border-color:#fff}.select.is-white select:hover,.select.is-white select.is-hovered{border-color:#f2f2f2}.select.is-white select:focus,.select.is-white select.is-focused,.select.is-white select:active,.select.is-white select.is-active{box-shadow:0 0 0 0.125em rgba(255,255,255,0.25)}.select.is-black:not(:hover)::after{border-color:#0a0a0a}.select.is-black select{border-color:#0a0a0a}.select.is-black select:hover,.select.is-black select.is-hovered{border-color:#000}.select.is-black select:focus,.select.is-black select.is-focused,.select.is-black select:active,.select.is-black select.is-active{box-shadow:0 0 0 0.125em rgba(10,10,10,0.25)}.select.is-light:not(:hover)::after{border-color:#f5f5f5}.select.is-light select{border-color:#f5f5f5}.select.is-light select:hover,.select.is-light select.is-hovered{border-color:#e8e8e8}.select.is-light select:focus,.select.is-light select.is-focused,.select.is-light select:active,.select.is-light select.is-active{box-shadow:0 0 0 0.125em rgba(245,245,245,0.25)}.select.is-dark:not(:hover)::after,.content kbd.select:not(:hover)::after{border-color:#363636}.select.is-dark select,.content kbd.select select{border-color:#363636}.select.is-dark select:hover,.content kbd.select select:hover,.select.is-dark select.is-hovered,.content kbd.select select.is-hovered{border-color:#292929}.select.is-dark select:focus,.content kbd.select select:focus,.select.is-dark select.is-focused,.content kbd.select select.is-focused,.select.is-dark select:active,.content kbd.select select:active,.select.is-dark select.is-active,.content kbd.select select.is-active{box-shadow:0 0 0 0.125em rgba(54,54,54,0.25)}.select.is-primary:not(:hover)::after,.docstring>section>a.select.docs-sourcelink:not(:hover)::after{border-color:#4eb5de}.select.is-primary select,.docstring>section>a.select.docs-sourcelink select{border-color:#4eb5de}.select.is-primary select:hover,.docstring>section>a.select.docs-sourcelink select:hover,.select.is-primary select.is-hovered,.docstring>section>a.select.docs-sourcelink select.is-hovered{border-color:#39acda}.select.is-primary select:focus,.docstring>section>a.select.docs-sourcelink select:focus,.select.is-primary select.is-focused,.docstring>section>a.select.docs-sourcelink select.is-focused,.select.is-primary select:active,.docstring>section>a.select.docs-sourcelink select:active,.select.is-primary select.is-active,.docstring>section>a.select.docs-sourcelink select.is-active{box-shadow:0 0 0 0.125em rgba(78,181,222,0.25)}.select.is-link:not(:hover)::after{border-color:#2e63b8}.select.is-link select{border-color:#2e63b8}.select.is-link select:hover,.select.is-link select.is-hovered{border-color:#2958a4}.select.is-link select:focus,.select.is-link select.is-focused,.select.is-link select:active,.select.is-link select.is-active{box-shadow:0 0 0 0.125em rgba(46,99,184,0.25)}.select.is-info:not(:hover)::after{border-color:#209cee}.select.is-info select{border-color:#209cee}.select.is-info select:hover,.select.is-info select.is-hovered{border-color:#1190e3}.select.is-info select:focus,.select.is-info select.is-focused,.select.is-info select:active,.select.is-info select.is-active{box-shadow:0 0 0 0.125em rgba(32,156,238,0.25)}.select.is-success:not(:hover)::after{border-color:#22c35b}.select.is-success select{border-color:#22c35b}.select.is-success select:hover,.select.is-success select.is-hovered{border-color:#1ead51}.select.is-success select:focus,.select.is-success select.is-focused,.select.is-success select:active,.select.is-success select.is-active{box-shadow:0 0 0 0.125em rgba(34,195,91,0.25)}.select.is-warning:not(:hover)::after{border-color:#ffdd57}.select.is-warning select{border-color:#ffdd57}.select.is-warning select:hover,.select.is-warning select.is-hovered{border-color:#ffd83e}.select.is-warning select:focus,.select.is-warning select.is-focused,.select.is-warning select:active,.select.is-warning select.is-active{box-shadow:0 0 0 0.125em rgba(255,221,87,0.25)}.select.is-danger:not(:hover)::after{border-color:#da0b00}.select.is-danger select{border-color:#da0b00}.select.is-danger select:hover,.select.is-danger select.is-hovered{border-color:#c10a00}.select.is-danger select:focus,.select.is-danger select.is-focused,.select.is-danger select:active,.select.is-danger select.is-active{box-shadow:0 0 0 0.125em rgba(218,11,0,0.25)}.select.is-small,#documenter .docs-sidebar form.docs-search>input.select{border-radius:2px;font-size:.75rem}.select.is-medium{font-size:1.25rem}.select.is-large{font-size:1.5rem}.select.is-disabled::after{border-color:#6b6b6b !important;opacity:0.5}.select.is-fullwidth{width:100%}.select.is-fullwidth select{width:100%}.select.is-loading::after{margin-top:0;position:absolute;right:.625em;top:0.625em;transform:none}.select.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.select.is-loading.is-medium:after{font-size:1.25rem}.select.is-loading.is-large:after{font-size:1.5rem}.file{align-items:stretch;display:flex;justify-content:flex-start;position:relative}.file.is-white .file-cta{background-color:#fff;border-color:transparent;color:#0a0a0a}.file.is-white:hover .file-cta,.file.is-white.is-hovered .file-cta{background-color:#f9f9f9;border-color:transparent;color:#0a0a0a}.file.is-white:focus .file-cta,.file.is-white.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,255,255,0.25);color:#0a0a0a}.file.is-white:active .file-cta,.file.is-white.is-active .file-cta{background-color:#f2f2f2;border-color:transparent;color:#0a0a0a}.file.is-black .file-cta{background-color:#0a0a0a;border-color:transparent;color:#fff}.file.is-black:hover .file-cta,.file.is-black.is-hovered .file-cta{background-color:#040404;border-color:transparent;color:#fff}.file.is-black:focus .file-cta,.file.is-black.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(10,10,10,0.25);color:#fff}.file.is-black:active .file-cta,.file.is-black.is-active .file-cta{background-color:#000;border-color:transparent;color:#fff}.file.is-light .file-cta{background-color:#f5f5f5;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:hover .file-cta,.file.is-light.is-hovered .file-cta{background-color:#eee;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-light:focus .file-cta,.file.is-light.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(245,245,245,0.25);color:rgba(0,0,0,0.7)}.file.is-light:active .file-cta,.file.is-light.is-active .file-cta{background-color:#e8e8e8;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-dark .file-cta,.content kbd.file .file-cta{background-color:#363636;border-color:transparent;color:#fff}.file.is-dark:hover .file-cta,.content kbd.file:hover .file-cta,.file.is-dark.is-hovered .file-cta,.content kbd.file.is-hovered .file-cta{background-color:#2f2f2f;border-color:transparent;color:#fff}.file.is-dark:focus .file-cta,.content kbd.file:focus .file-cta,.file.is-dark.is-focused .file-cta,.content kbd.file.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(54,54,54,0.25);color:#fff}.file.is-dark:active .file-cta,.content kbd.file:active .file-cta,.file.is-dark.is-active .file-cta,.content kbd.file.is-active .file-cta{background-color:#292929;border-color:transparent;color:#fff}.file.is-primary .file-cta,.docstring>section>a.file.docs-sourcelink .file-cta{background-color:#4eb5de;border-color:transparent;color:#fff}.file.is-primary:hover .file-cta,.docstring>section>a.file.docs-sourcelink:hover .file-cta,.file.is-primary.is-hovered .file-cta,.docstring>section>a.file.is-hovered.docs-sourcelink .file-cta{background-color:#43b1dc;border-color:transparent;color:#fff}.file.is-primary:focus .file-cta,.docstring>section>a.file.docs-sourcelink:focus .file-cta,.file.is-primary.is-focused .file-cta,.docstring>section>a.file.is-focused.docs-sourcelink .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(78,181,222,0.25);color:#fff}.file.is-primary:active .file-cta,.docstring>section>a.file.docs-sourcelink:active .file-cta,.file.is-primary.is-active .file-cta,.docstring>section>a.file.is-active.docs-sourcelink .file-cta{background-color:#39acda;border-color:transparent;color:#fff}.file.is-link .file-cta{background-color:#2e63b8;border-color:transparent;color:#fff}.file.is-link:hover .file-cta,.file.is-link.is-hovered .file-cta{background-color:#2b5eae;border-color:transparent;color:#fff}.file.is-link:focus .file-cta,.file.is-link.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(46,99,184,0.25);color:#fff}.file.is-link:active .file-cta,.file.is-link.is-active .file-cta{background-color:#2958a4;border-color:transparent;color:#fff}.file.is-info .file-cta{background-color:#209cee;border-color:transparent;color:#fff}.file.is-info:hover .file-cta,.file.is-info.is-hovered .file-cta{background-color:#1497ed;border-color:transparent;color:#fff}.file.is-info:focus .file-cta,.file.is-info.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(32,156,238,0.25);color:#fff}.file.is-info:active .file-cta,.file.is-info.is-active .file-cta{background-color:#1190e3;border-color:transparent;color:#fff}.file.is-success .file-cta{background-color:#22c35b;border-color:transparent;color:#fff}.file.is-success:hover .file-cta,.file.is-success.is-hovered .file-cta{background-color:#20b856;border-color:transparent;color:#fff}.file.is-success:focus .file-cta,.file.is-success.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(34,195,91,0.25);color:#fff}.file.is-success:active .file-cta,.file.is-success.is-active .file-cta{background-color:#1ead51;border-color:transparent;color:#fff}.file.is-warning .file-cta{background-color:#ffdd57;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:hover .file-cta,.file.is-warning.is-hovered .file-cta{background-color:#ffda4a;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-warning:focus .file-cta,.file.is-warning.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(255,221,87,0.25);color:rgba(0,0,0,0.7)}.file.is-warning:active .file-cta,.file.is-warning.is-active .file-cta{background-color:#ffd83e;border-color:transparent;color:rgba(0,0,0,0.7)}.file.is-danger .file-cta{background-color:#da0b00;border-color:transparent;color:#fff}.file.is-danger:hover .file-cta,.file.is-danger.is-hovered .file-cta{background-color:#cd0a00;border-color:transparent;color:#fff}.file.is-danger:focus .file-cta,.file.is-danger.is-focused .file-cta{border-color:transparent;box-shadow:0 0 0.5em rgba(218,11,0,0.25);color:#fff}.file.is-danger:active .file-cta,.file.is-danger.is-active .file-cta{background-color:#c10a00;border-color:transparent;color:#fff}.file.is-small,#documenter .docs-sidebar form.docs-search>input.file{font-size:.75rem}.file.is-normal{font-size:1rem}.file.is-medium{font-size:1.25rem}.file.is-medium .file-icon .fa{font-size:21px}.file.is-large{font-size:1.5rem}.file.is-large .file-icon .fa{font-size:28px}.file.has-name .file-cta{border-bottom-right-radius:0;border-top-right-radius:0}.file.has-name .file-name{border-bottom-left-radius:0;border-top-left-radius:0}.file.has-name.is-empty .file-cta{border-radius:4px}.file.has-name.is-empty .file-name{display:none}.file.is-boxed .file-label{flex-direction:column}.file.is-boxed .file-cta{flex-direction:column;height:auto;padding:1em 3em}.file.is-boxed .file-name{border-width:0 1px 1px}.file.is-boxed .file-icon{height:1.5em;width:1.5em}.file.is-boxed .file-icon .fa{font-size:21px}.file.is-boxed.is-small .file-icon .fa,#documenter .docs-sidebar form.docs-search>input.is-boxed .file-icon .fa{font-size:14px}.file.is-boxed.is-medium .file-icon .fa{font-size:28px}.file.is-boxed.is-large .file-icon .fa{font-size:35px}.file.is-boxed.has-name .file-cta{border-radius:4px 4px 0 0}.file.is-boxed.has-name .file-name{border-radius:0 0 4px 4px;border-width:0 1px 1px}.file.is-centered{justify-content:center}.file.is-fullwidth .file-label{width:100%}.file.is-fullwidth .file-name{flex-grow:1;max-width:none}.file.is-right{justify-content:flex-end}.file.is-right .file-cta{border-radius:0 4px 4px 0}.file.is-right .file-name{border-radius:4px 0 0 4px;border-width:1px 0 1px 1px;order:-1}.file-label{align-items:stretch;display:flex;cursor:pointer;justify-content:flex-start;overflow:hidden;position:relative}.file-label:hover .file-cta{background-color:#eee;color:#222}.file-label:hover .file-name{border-color:#d5d5d5}.file-label:active .file-cta{background-color:#e8e8e8;color:#222}.file-label:active .file-name{border-color:#cfcfcf}.file-input{height:100%;left:0;opacity:0;outline:none;position:absolute;top:0;width:100%}.file-cta,.file-name{border-color:#dbdbdb;border-radius:4px;font-size:1em;padding-left:1em;padding-right:1em;white-space:nowrap}.file-cta{background-color:#f5f5f5;color:#222}.file-name{border-color:#dbdbdb;border-style:solid;border-width:1px 1px 1px 0;display:block;max-width:16em;overflow:hidden;text-align:inherit;text-overflow:ellipsis}.file-icon{align-items:center;display:flex;height:1em;justify-content:center;margin-right:.5em;width:1em}.file-icon .fa{font-size:14px}.label{color:#222;display:block;font-size:1rem;font-weight:700}.label:not(:last-child){margin-bottom:0.5em}.label.is-small,#documenter .docs-sidebar form.docs-search>input.label{font-size:.75rem}.label.is-medium{font-size:1.25rem}.label.is-large{font-size:1.5rem}.help{display:block;font-size:.75rem;margin-top:0.25rem}.help.is-white{color:#fff}.help.is-black{color:#0a0a0a}.help.is-light{color:#f5f5f5}.help.is-dark,.content kbd.help{color:#363636}.help.is-primary,.docstring>section>a.help.docs-sourcelink{color:#4eb5de}.help.is-link{color:#2e63b8}.help.is-info{color:#209cee}.help.is-success{color:#22c35b}.help.is-warning{color:#ffdd57}.help.is-danger{color:#da0b00}.field:not(:last-child){margin-bottom:0.75rem}.field.has-addons{display:flex;justify-content:flex-start}.field.has-addons .control:not(:last-child){margin-right:-1px}.field.has-addons .control:not(:first-child):not(:last-child) .button,.field.has-addons .control:not(:first-child):not(:last-child) .input,.field.has-addons .control:not(:first-child):not(:last-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:not(:first-child):not(:last-child) form.docs-search>input,.field.has-addons .control:not(:first-child):not(:last-child) .select select{border-radius:0}.field.has-addons .control:first-child:not(:only-child) .button,.field.has-addons .control:first-child:not(:only-child) .input,.field.has-addons .control:first-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:first-child:not(:only-child) form.docs-search>input,.field.has-addons .control:first-child:not(:only-child) .select select{border-bottom-right-radius:0;border-top-right-radius:0}.field.has-addons .control:last-child:not(:only-child) .button,.field.has-addons .control:last-child:not(:only-child) .input,.field.has-addons .control:last-child:not(:only-child) #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .field.has-addons .control:last-child:not(:only-child) form.docs-search>input,.field.has-addons .control:last-child:not(:only-child) .select select{border-bottom-left-radius:0;border-top-left-radius:0}.field.has-addons .control .button:not([disabled]):hover,.field.has-addons .control .button.is-hovered:not([disabled]),.field.has-addons .control .input:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):hover,.field.has-addons .control .input.is-hovered:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-hovered:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-hovered:not([disabled]),.field.has-addons .control .select select:not([disabled]):hover,.field.has-addons .control .select select.is-hovered:not([disabled]){z-index:2}.field.has-addons .control .button:not([disabled]):focus,.field.has-addons .control .button.is-focused:not([disabled]),.field.has-addons .control .button:not([disabled]):active,.field.has-addons .control .button.is-active:not([disabled]),.field.has-addons .control .input:not([disabled]):focus,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus,.field.has-addons .control .input.is-focused:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]),.field.has-addons .control .input:not([disabled]):active,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active,.field.has-addons .control .input.is-active:not([disabled]),.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]),#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]),.field.has-addons .control .select select:not([disabled]):focus,.field.has-addons .control .select select.is-focused:not([disabled]),.field.has-addons .control .select select:not([disabled]):active,.field.has-addons .control .select select.is-active:not([disabled]){z-index:3}.field.has-addons .control .button:not([disabled]):focus:hover,.field.has-addons .control .button.is-focused:not([disabled]):hover,.field.has-addons .control .button:not([disabled]):active:hover,.field.has-addons .control .button.is-active:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):focus:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):focus:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):focus:hover,.field.has-addons .control .input.is-focused:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-focused:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-focused:not([disabled]):hover,.field.has-addons .control .input:not([disabled]):active:hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input:not([disabled]):active:hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input:not([disabled]):active:hover,.field.has-addons .control .input.is-active:not([disabled]):hover,.field.has-addons .control #documenter .docs-sidebar form.docs-search>input.is-active:not([disabled]):hover,#documenter .docs-sidebar .field.has-addons .control form.docs-search>input.is-active:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):focus:hover,.field.has-addons .control .select select.is-focused:not([disabled]):hover,.field.has-addons .control .select select:not([disabled]):active:hover,.field.has-addons .control .select select.is-active:not([disabled]):hover{z-index:4}.field.has-addons .control.is-expanded{flex-grow:1;flex-shrink:1}.field.has-addons.has-addons-centered{justify-content:center}.field.has-addons.has-addons-right{justify-content:flex-end}.field.has-addons.has-addons-fullwidth .control{flex-grow:1;flex-shrink:0}.field.is-grouped{display:flex;justify-content:flex-start}.field.is-grouped>.control{flex-shrink:0}.field.is-grouped>.control:not(:last-child){margin-bottom:0;margin-right:.75rem}.field.is-grouped>.control.is-expanded{flex-grow:1;flex-shrink:1}.field.is-grouped.is-grouped-centered{justify-content:center}.field.is-grouped.is-grouped-right{justify-content:flex-end}.field.is-grouped.is-grouped-multiline{flex-wrap:wrap}.field.is-grouped.is-grouped-multiline>.control:last-child,.field.is-grouped.is-grouped-multiline>.control:not(:last-child){margin-bottom:0.75rem}.field.is-grouped.is-grouped-multiline:last-child{margin-bottom:-0.75rem}.field.is-grouped.is-grouped-multiline:not(:last-child){margin-bottom:0}@media screen and (min-width: 769px),print{.field.is-horizontal{display:flex}}.field-label .label{font-size:inherit}@media screen and (max-width: 768px){.field-label{margin-bottom:0.5rem}}@media screen and (min-width: 769px),print{.field-label{flex-basis:0;flex-grow:1;flex-shrink:0;margin-right:1.5rem;text-align:right}.field-label.is-small,#documenter .docs-sidebar form.docs-search>input.field-label{font-size:.75rem;padding-top:0.375em}.field-label.is-normal{padding-top:0.375em}.field-label.is-medium{font-size:1.25rem;padding-top:0.375em}.field-label.is-large{font-size:1.5rem;padding-top:0.375em}}.field-body .field .field{margin-bottom:0}@media screen and (min-width: 769px),print{.field-body{display:flex;flex-basis:0;flex-grow:5;flex-shrink:1}.field-body .field{margin-bottom:0}.field-body>.field{flex-shrink:1}.field-body>.field:not(.is-narrow){flex-grow:1}.field-body>.field:not(:last-child){margin-right:.75rem}}.control{box-sizing:border-box;clear:both;font-size:1rem;position:relative;text-align:inherit}.control.has-icons-left .input:focus~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input:focus~.icon,.control.has-icons-left .select:focus~.icon,.control.has-icons-right .input:focus~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input:focus~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input:focus~.icon,.control.has-icons-right .select:focus~.icon{color:#222}.control.has-icons-left .input.is-small~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input~.icon,.control.has-icons-left .select.is-small~.icon,.control.has-icons-right .input.is-small~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input~.icon,.control.has-icons-right .select.is-small~.icon{font-size:.75rem}.control.has-icons-left .input.is-medium~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-medium~.icon,.control.has-icons-left .select.is-medium~.icon,.control.has-icons-right .input.is-medium~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-medium~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-medium~.icon,.control.has-icons-right .select.is-medium~.icon{font-size:1.25rem}.control.has-icons-left .input.is-large~.icon,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input.is-large~.icon,.control.has-icons-left .select.is-large~.icon,.control.has-icons-right .input.is-large~.icon,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input.is-large~.icon,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input.is-large~.icon,.control.has-icons-right .select.is-large~.icon{font-size:1.5rem}.control.has-icons-left .icon,.control.has-icons-right .icon{color:#dbdbdb;height:2.5em;pointer-events:none;position:absolute;top:0;width:2.5em;z-index:4}.control.has-icons-left .input,.control.has-icons-left #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-left form.docs-search>input,.control.has-icons-left .select select{padding-left:2.5em}.control.has-icons-left .icon.is-left{left:0}.control.has-icons-right .input,.control.has-icons-right #documenter .docs-sidebar form.docs-search>input,#documenter .docs-sidebar .control.has-icons-right form.docs-search>input,.control.has-icons-right .select select{padding-right:2.5em}.control.has-icons-right .icon.is-right{right:0}.control.is-loading::after{position:absolute !important;right:.625em;top:0.625em;z-index:4}.control.is-loading.is-small:after,#documenter .docs-sidebar form.docs-search>input.is-loading:after{font-size:.75rem}.control.is-loading.is-medium:after{font-size:1.25rem}.control.is-loading.is-large:after{font-size:1.5rem}.breadcrumb{font-size:1rem;white-space:nowrap}.breadcrumb a{align-items:center;color:#2e63b8;display:flex;justify-content:center;padding:0 .75em}.breadcrumb a:hover{color:#363636}.breadcrumb li{align-items:center;display:flex}.breadcrumb li:first-child a{padding-left:0}.breadcrumb li.is-active a{color:#222;cursor:default;pointer-events:none}.breadcrumb li+li::before{color:#b5b5b5;content:"\0002f"}.breadcrumb ul,.breadcrumb ol{align-items:flex-start;display:flex;flex-wrap:wrap;justify-content:flex-start}.breadcrumb .icon:first-child{margin-right:.5em}.breadcrumb .icon:last-child{margin-left:.5em}.breadcrumb.is-centered ol,.breadcrumb.is-centered ul{justify-content:center}.breadcrumb.is-right ol,.breadcrumb.is-right ul{justify-content:flex-end}.breadcrumb.is-small,#documenter .docs-sidebar form.docs-search>input.breadcrumb{font-size:.75rem}.breadcrumb.is-medium{font-size:1.25rem}.breadcrumb.is-large{font-size:1.5rem}.breadcrumb.has-arrow-separator li+li::before{content:"\02192"}.breadcrumb.has-bullet-separator li+li::before{content:"\02022"}.breadcrumb.has-dot-separator li+li::before{content:"\000b7"}.breadcrumb.has-succeeds-separator li+li::before{content:"\0227B"}.card{background-color:#fff;border-radius:.25rem;box-shadow:#bbb;color:#222;max-width:100%;position:relative}.card-footer:first-child,.card-content:first-child,.card-header:first-child{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-footer:last-child,.card-content:last-child,.card-header:last-child{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-header{background-color:rgba(0,0,0,0);align-items:stretch;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);display:flex}.card-header-title{align-items:center;color:#222;display:flex;flex-grow:1;font-weight:700;padding:0.75rem 1rem}.card-header-title.is-centered{justify-content:center}.card-header-icon{-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;color:currentColor;font-family:inherit;font-size:1em;margin:0;padding:0;align-items:center;cursor:pointer;display:flex;justify-content:center;padding:0.75rem 1rem}.card-image{display:block;position:relative}.card-image:first-child img{border-top-left-radius:.25rem;border-top-right-radius:.25rem}.card-image:last-child img{border-bottom-left-radius:.25rem;border-bottom-right-radius:.25rem}.card-content{background-color:rgba(0,0,0,0);padding:1.5rem}.card-footer{background-color:rgba(0,0,0,0);border-top:1px solid #ededed;align-items:stretch;display:flex}.card-footer-item{align-items:center;display:flex;flex-basis:0;flex-grow:1;flex-shrink:0;justify-content:center;padding:.75rem}.card-footer-item:not(:last-child){border-right:1px solid #ededed}.card .media:not(:last-child){margin-bottom:1.5rem}.dropdown{display:inline-flex;position:relative;vertical-align:top}.dropdown.is-active .dropdown-menu,.dropdown.is-hoverable:hover .dropdown-menu{display:block}.dropdown.is-right .dropdown-menu{left:auto;right:0}.dropdown.is-up .dropdown-menu{bottom:100%;padding-bottom:4px;padding-top:initial;top:auto}.dropdown-menu{display:none;left:0;min-width:12rem;padding-top:4px;position:absolute;top:100%;z-index:20}.dropdown-content{background-color:#fff;border-radius:4px;box-shadow:#bbb;padding-bottom:.5rem;padding-top:.5rem}.dropdown-item{color:#222;display:block;font-size:0.875rem;line-height:1.5;padding:0.375rem 1rem;position:relative}a.dropdown-item,button.dropdown-item{padding-right:3rem;text-align:inherit;white-space:nowrap;width:100%}a.dropdown-item:hover,button.dropdown-item:hover{background-color:#f5f5f5;color:#0a0a0a}a.dropdown-item.is-active,button.dropdown-item.is-active{background-color:#2e63b8;color:#fff}.dropdown-divider{background-color:#ededed;border:none;display:block;height:1px;margin:0.5rem 0}.level{align-items:center;justify-content:space-between}.level code{border-radius:4px}.level img{display:inline-block;vertical-align:top}.level.is-mobile{display:flex}.level.is-mobile .level-left,.level.is-mobile .level-right{display:flex}.level.is-mobile .level-left+.level-right{margin-top:0}.level.is-mobile .level-item:not(:last-child){margin-bottom:0;margin-right:.75rem}.level.is-mobile .level-item:not(.is-narrow){flex-grow:1}@media screen and (min-width: 769px),print{.level{display:flex}.level>.level-item:not(.is-narrow){flex-grow:1}}.level-item{align-items:center;display:flex;flex-basis:auto;flex-grow:0;flex-shrink:0;justify-content:center}.level-item .title,.level-item .subtitle{margin-bottom:0}@media screen and (max-width: 768px){.level-item:not(:last-child){margin-bottom:.75rem}}.level-left,.level-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.level-left .level-item.is-flexible,.level-right .level-item.is-flexible{flex-grow:1}@media screen and (min-width: 769px),print{.level-left .level-item:not(:last-child),.level-right .level-item:not(:last-child){margin-right:.75rem}}.level-left{align-items:center;justify-content:flex-start}@media screen and (max-width: 768px){.level-left+.level-right{margin-top:1.5rem}}@media screen and (min-width: 769px),print{.level-left{display:flex}}.level-right{align-items:center;justify-content:flex-end}@media screen and (min-width: 769px),print{.level-right{display:flex}}.media{align-items:flex-start;display:flex;text-align:inherit}.media .content:not(:last-child){margin-bottom:.75rem}.media .media{border-top:1px solid rgba(219,219,219,0.5);display:flex;padding-top:.75rem}.media .media .content:not(:last-child),.media .media .control:not(:last-child){margin-bottom:.5rem}.media .media .media{padding-top:.5rem}.media .media .media+.media{margin-top:.5rem}.media+.media{border-top:1px solid rgba(219,219,219,0.5);margin-top:1rem;padding-top:1rem}.media.is-large+.media{margin-top:1.5rem;padding-top:1.5rem}.media-left,.media-right{flex-basis:auto;flex-grow:0;flex-shrink:0}.media-left{margin-right:1rem}.media-right{margin-left:1rem}.media-content{flex-basis:auto;flex-grow:1;flex-shrink:1;text-align:inherit}@media screen and (max-width: 768px){.media-content{overflow-x:auto}}.menu{font-size:1rem}.menu.is-small,#documenter .docs-sidebar form.docs-search>input.menu{font-size:.75rem}.menu.is-medium{font-size:1.25rem}.menu.is-large{font-size:1.5rem}.menu-list{line-height:1.25}.menu-list a{border-radius:2px;color:#222;display:block;padding:0.5em 0.75em}.menu-list a:hover{background-color:#f5f5f5;color:#222}.menu-list a.is-active{background-color:#2e63b8;color:#fff}.menu-list li ul{border-left:1px solid #dbdbdb;margin:.75em;padding-left:.75em}.menu-label{color:#6b6b6b;font-size:.75em;letter-spacing:.1em;text-transform:uppercase}.menu-label:not(:first-child){margin-top:1em}.menu-label:not(:last-child){margin-bottom:1em}.message{background-color:#f5f5f5;border-radius:4px;font-size:1rem}.message strong{color:currentColor}.message a:not(.button):not(.tag):not(.dropdown-item){color:currentColor;text-decoration:underline}.message.is-small,#documenter .docs-sidebar form.docs-search>input.message{font-size:.75rem}.message.is-medium{font-size:1.25rem}.message.is-large{font-size:1.5rem}.message.is-white{background-color:#fff}.message.is-white .message-header{background-color:#fff;color:#0a0a0a}.message.is-white .message-body{border-color:#fff}.message.is-black{background-color:#fafafa}.message.is-black .message-header{background-color:#0a0a0a;color:#fff}.message.is-black .message-body{border-color:#0a0a0a}.message.is-light{background-color:#fafafa}.message.is-light .message-header{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.message.is-light .message-body{border-color:#f5f5f5}.message.is-dark,.content kbd.message{background-color:#fafafa}.message.is-dark .message-header,.content kbd.message .message-header{background-color:#363636;color:#fff}.message.is-dark .message-body,.content kbd.message .message-body{border-color:#363636}.message.is-primary,.docstring>section>a.message.docs-sourcelink{background-color:#eef8fc}.message.is-primary .message-header,.docstring>section>a.message.docs-sourcelink .message-header{background-color:#4eb5de;color:#fff}.message.is-primary .message-body,.docstring>section>a.message.docs-sourcelink .message-body{border-color:#4eb5de;color:#1a6d8e}.message.is-link{background-color:#eff3fb}.message.is-link .message-header{background-color:#2e63b8;color:#fff}.message.is-link .message-body{border-color:#2e63b8;color:#3169c4}.message.is-info{background-color:#ecf7fe}.message.is-info .message-header{background-color:#209cee;color:#fff}.message.is-info .message-body{border-color:#209cee;color:#0e72b4}.message.is-success{background-color:#eefcf3}.message.is-success .message-header{background-color:#22c35b;color:#fff}.message.is-success .message-body{border-color:#22c35b;color:#198f43}.message.is-warning{background-color:#fffbeb}.message.is-warning .message-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.message.is-warning .message-body{border-color:#ffdd57;color:#947600}.message.is-danger{background-color:#ffeceb}.message.is-danger .message-header{background-color:#da0b00;color:#fff}.message.is-danger .message-body{border-color:#da0b00;color:#f50c00}.message-header{align-items:center;background-color:#222;border-radius:4px 4px 0 0;color:#fff;display:flex;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.75em 1em;position:relative}.message-header .delete{flex-grow:0;flex-shrink:0;margin-left:.75em}.message-header+.message-body{border-width:0;border-top-left-radius:0;border-top-right-radius:0}.message-body{border-color:#dbdbdb;border-radius:4px;border-style:solid;border-width:0 0 0 4px;color:#222;padding:1.25em 1.5em}.message-body code,.message-body pre{background-color:#fff}.message-body pre code{background-color:rgba(0,0,0,0)}.modal{align-items:center;display:none;flex-direction:column;justify-content:center;overflow:hidden;position:fixed;z-index:40}.modal.is-active{display:flex}.modal-background{background-color:rgba(10,10,10,0.86)}.modal-content,.modal-card{margin:0 20px;max-height:calc(100vh - 160px);overflow:auto;position:relative;width:100%}@media screen and (min-width: 769px){.modal-content,.modal-card{margin:0 auto;max-height:calc(100vh - 40px);width:640px}}.modal-close{background:none;height:40px;position:fixed;right:20px;top:20px;width:40px}.modal-card{display:flex;flex-direction:column;max-height:calc(100vh - 40px);overflow:hidden;-ms-overflow-y:visible}.modal-card-head,.modal-card-foot{align-items:center;background-color:#f5f5f5;display:flex;flex-shrink:0;justify-content:flex-start;padding:20px;position:relative}.modal-card-head{border-bottom:1px solid #dbdbdb;border-top-left-radius:6px;border-top-right-radius:6px}.modal-card-title{color:#222;flex-grow:1;flex-shrink:0;font-size:1.5rem;line-height:1}.modal-card-foot{border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:1px solid #dbdbdb}.modal-card-foot .button:not(:last-child){margin-right:.5em}.modal-card-body{-webkit-overflow-scrolling:touch;background-color:#fff;flex-grow:1;flex-shrink:1;overflow:auto;padding:20px}.navbar{background-color:#fff;min-height:3.25rem;position:relative;z-index:30}.navbar.is-white{background-color:#fff;color:#0a0a0a}.navbar.is-white .navbar-brand>.navbar-item,.navbar.is-white .navbar-brand .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-brand>a.navbar-item:focus,.navbar.is-white .navbar-brand>a.navbar-item:hover,.navbar.is-white .navbar-brand>a.navbar-item.is-active,.navbar.is-white .navbar-brand .navbar-link:focus,.navbar.is-white .navbar-brand .navbar-link:hover,.navbar.is-white .navbar-brand .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-brand .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-burger{color:#0a0a0a}@media screen and (min-width: 1056px){.navbar.is-white .navbar-start>.navbar-item,.navbar.is-white .navbar-start .navbar-link,.navbar.is-white .navbar-end>.navbar-item,.navbar.is-white .navbar-end .navbar-link{color:#0a0a0a}.navbar.is-white .navbar-start>a.navbar-item:focus,.navbar.is-white .navbar-start>a.navbar-item:hover,.navbar.is-white .navbar-start>a.navbar-item.is-active,.navbar.is-white .navbar-start .navbar-link:focus,.navbar.is-white .navbar-start .navbar-link:hover,.navbar.is-white .navbar-start .navbar-link.is-active,.navbar.is-white .navbar-end>a.navbar-item:focus,.navbar.is-white .navbar-end>a.navbar-item:hover,.navbar.is-white .navbar-end>a.navbar-item.is-active,.navbar.is-white .navbar-end .navbar-link:focus,.navbar.is-white .navbar-end .navbar-link:hover,.navbar.is-white .navbar-end .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-start .navbar-link::after,.navbar.is-white .navbar-end .navbar-link::after{border-color:#0a0a0a}.navbar.is-white .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-white .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-white .navbar-item.has-dropdown.is-active .navbar-link{background-color:#f2f2f2;color:#0a0a0a}.navbar.is-white .navbar-dropdown a.navbar-item.is-active{background-color:#fff;color:#0a0a0a}}.navbar.is-black{background-color:#0a0a0a;color:#fff}.navbar.is-black .navbar-brand>.navbar-item,.navbar.is-black .navbar-brand .navbar-link{color:#fff}.navbar.is-black .navbar-brand>a.navbar-item:focus,.navbar.is-black .navbar-brand>a.navbar-item:hover,.navbar.is-black .navbar-brand>a.navbar-item.is-active,.navbar.is-black .navbar-brand .navbar-link:focus,.navbar.is-black .navbar-brand .navbar-link:hover,.navbar.is-black .navbar-brand .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-black .navbar-start>.navbar-item,.navbar.is-black .navbar-start .navbar-link,.navbar.is-black .navbar-end>.navbar-item,.navbar.is-black .navbar-end .navbar-link{color:#fff}.navbar.is-black .navbar-start>a.navbar-item:focus,.navbar.is-black .navbar-start>a.navbar-item:hover,.navbar.is-black .navbar-start>a.navbar-item.is-active,.navbar.is-black .navbar-start .navbar-link:focus,.navbar.is-black .navbar-start .navbar-link:hover,.navbar.is-black .navbar-start .navbar-link.is-active,.navbar.is-black .navbar-end>a.navbar-item:focus,.navbar.is-black .navbar-end>a.navbar-item:hover,.navbar.is-black .navbar-end>a.navbar-item.is-active,.navbar.is-black .navbar-end .navbar-link:focus,.navbar.is-black .navbar-end .navbar-link:hover,.navbar.is-black .navbar-end .navbar-link.is-active{background-color:#000;color:#fff}.navbar.is-black .navbar-start .navbar-link::after,.navbar.is-black .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-black .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-black .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-black .navbar-item.has-dropdown.is-active .navbar-link{background-color:#000;color:#fff}.navbar.is-black .navbar-dropdown a.navbar-item.is-active{background-color:#0a0a0a;color:#fff}}.navbar.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>.navbar-item,.navbar.is-light .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand>a.navbar-item:focus,.navbar.is-light .navbar-brand>a.navbar-item:hover,.navbar.is-light .navbar-brand>a.navbar-item.is-active,.navbar.is-light .navbar-brand .navbar-link:focus,.navbar.is-light .navbar-brand .navbar-link:hover,.navbar.is-light .navbar-brand .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-light .navbar-start>.navbar-item,.navbar.is-light .navbar-start .navbar-link,.navbar.is-light .navbar-end>.navbar-item,.navbar.is-light .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start>a.navbar-item:focus,.navbar.is-light .navbar-start>a.navbar-item:hover,.navbar.is-light .navbar-start>a.navbar-item.is-active,.navbar.is-light .navbar-start .navbar-link:focus,.navbar.is-light .navbar-start .navbar-link:hover,.navbar.is-light .navbar-start .navbar-link.is-active,.navbar.is-light .navbar-end>a.navbar-item:focus,.navbar.is-light .navbar-end>a.navbar-item:hover,.navbar.is-light .navbar-end>a.navbar-item.is-active,.navbar.is-light .navbar-end .navbar-link:focus,.navbar.is-light .navbar-end .navbar-link:hover,.navbar.is-light .navbar-end .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-start .navbar-link::after,.navbar.is-light .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-light .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-light .navbar-item.has-dropdown.is-active .navbar-link{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.navbar.is-light .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}}.navbar.is-dark,.content kbd.navbar{background-color:#363636;color:#fff}.navbar.is-dark .navbar-brand>.navbar-item,.content kbd.navbar .navbar-brand>.navbar-item,.navbar.is-dark .navbar-brand .navbar-link,.content kbd.navbar .navbar-brand .navbar-link{color:#fff}.navbar.is-dark .navbar-brand>a.navbar-item:focus,.content kbd.navbar .navbar-brand>a.navbar-item:focus,.navbar.is-dark .navbar-brand>a.navbar-item:hover,.content kbd.navbar .navbar-brand>a.navbar-item:hover,.navbar.is-dark .navbar-brand>a.navbar-item.is-active,.content kbd.navbar .navbar-brand>a.navbar-item.is-active,.navbar.is-dark .navbar-brand .navbar-link:focus,.content kbd.navbar .navbar-brand .navbar-link:focus,.navbar.is-dark .navbar-brand .navbar-link:hover,.content kbd.navbar .navbar-brand .navbar-link:hover,.navbar.is-dark .navbar-brand .navbar-link.is-active,.content kbd.navbar .navbar-brand .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-brand .navbar-link::after,.content kbd.navbar .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-burger,.content kbd.navbar .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-dark .navbar-start>.navbar-item,.content kbd.navbar .navbar-start>.navbar-item,.navbar.is-dark .navbar-start .navbar-link,.content kbd.navbar .navbar-start .navbar-link,.navbar.is-dark .navbar-end>.navbar-item,.content kbd.navbar .navbar-end>.navbar-item,.navbar.is-dark .navbar-end .navbar-link,.content kbd.navbar .navbar-end .navbar-link{color:#fff}.navbar.is-dark .navbar-start>a.navbar-item:focus,.content kbd.navbar .navbar-start>a.navbar-item:focus,.navbar.is-dark .navbar-start>a.navbar-item:hover,.content kbd.navbar .navbar-start>a.navbar-item:hover,.navbar.is-dark .navbar-start>a.navbar-item.is-active,.content kbd.navbar .navbar-start>a.navbar-item.is-active,.navbar.is-dark .navbar-start .navbar-link:focus,.content kbd.navbar .navbar-start .navbar-link:focus,.navbar.is-dark .navbar-start .navbar-link:hover,.content kbd.navbar .navbar-start .navbar-link:hover,.navbar.is-dark .navbar-start .navbar-link.is-active,.content kbd.navbar .navbar-start .navbar-link.is-active,.navbar.is-dark .navbar-end>a.navbar-item:focus,.content kbd.navbar .navbar-end>a.navbar-item:focus,.navbar.is-dark .navbar-end>a.navbar-item:hover,.content kbd.navbar .navbar-end>a.navbar-item:hover,.navbar.is-dark .navbar-end>a.navbar-item.is-active,.content kbd.navbar .navbar-end>a.navbar-item.is-active,.navbar.is-dark .navbar-end .navbar-link:focus,.content kbd.navbar .navbar-end .navbar-link:focus,.navbar.is-dark .navbar-end .navbar-link:hover,.content kbd.navbar .navbar-end .navbar-link:hover,.navbar.is-dark .navbar-end .navbar-link.is-active,.content kbd.navbar .navbar-end .navbar-link.is-active{background-color:#292929;color:#fff}.navbar.is-dark .navbar-start .navbar-link::after,.content kbd.navbar .navbar-start .navbar-link::after,.navbar.is-dark .navbar-end .navbar-link::after,.content kbd.navbar .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-dark .navbar-item.has-dropdown:focus .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-dark .navbar-item.has-dropdown:hover .navbar-link,.content kbd.navbar .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-dark .navbar-item.has-dropdown.is-active .navbar-link,.content kbd.navbar .navbar-item.has-dropdown.is-active .navbar-link{background-color:#292929;color:#fff}.navbar.is-dark .navbar-dropdown a.navbar-item.is-active,.content kbd.navbar .navbar-dropdown a.navbar-item.is-active{background-color:#363636;color:#fff}}.navbar.is-primary,.docstring>section>a.navbar.docs-sourcelink{background-color:#4eb5de;color:#fff}.navbar.is-primary .navbar-brand>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>.navbar-item,.navbar.is-primary .navbar-brand .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link{color:#fff}.navbar.is-primary .navbar-brand>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:focus,.navbar.is-primary .navbar-brand>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item:hover,.navbar.is-primary .navbar-brand>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand>a.navbar-item.is-active,.navbar.is-primary .navbar-brand .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:focus,.navbar.is-primary .navbar-brand .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link:hover,.navbar.is-primary .navbar-brand .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-brand .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-burger,.docstring>section>a.navbar.docs-sourcelink .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-primary .navbar-start>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-start>.navbar-item,.navbar.is-primary .navbar-start .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link,.navbar.is-primary .navbar-end>.navbar-item,.docstring>section>a.navbar.docs-sourcelink .navbar-end>.navbar-item,.navbar.is-primary .navbar-end .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link{color:#fff}.navbar.is-primary .navbar-start>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:focus,.navbar.is-primary .navbar-start>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item:hover,.navbar.is-primary .navbar-start>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start>a.navbar-item.is-active,.navbar.is-primary .navbar-start .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:focus,.navbar.is-primary .navbar-start .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link:hover,.navbar.is-primary .navbar-start .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link.is-active,.navbar.is-primary .navbar-end>a.navbar-item:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:focus,.navbar.is-primary .navbar-end>a.navbar-item:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item:hover,.navbar.is-primary .navbar-end>a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end>a.navbar-item.is-active,.navbar.is-primary .navbar-end .navbar-link:focus,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:focus,.navbar.is-primary .navbar-end .navbar-link:hover,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link:hover,.navbar.is-primary .navbar-end .navbar-link.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link.is-active{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-start .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-start .navbar-link::after,.navbar.is-primary .navbar-end .navbar-link::after,.docstring>section>a.navbar.docs-sourcelink .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-primary .navbar-item.has-dropdown:focus .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-primary .navbar-item.has-dropdown:hover .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-primary .navbar-item.has-dropdown.is-active .navbar-link,.docstring>section>a.navbar.docs-sourcelink .navbar-item.has-dropdown.is-active .navbar-link{background-color:#39acda;color:#fff}.navbar.is-primary .navbar-dropdown a.navbar-item.is-active,.docstring>section>a.navbar.docs-sourcelink .navbar-dropdown a.navbar-item.is-active{background-color:#4eb5de;color:#fff}}.navbar.is-link{background-color:#2e63b8;color:#fff}.navbar.is-link .navbar-brand>.navbar-item,.navbar.is-link .navbar-brand .navbar-link{color:#fff}.navbar.is-link .navbar-brand>a.navbar-item:focus,.navbar.is-link .navbar-brand>a.navbar-item:hover,.navbar.is-link .navbar-brand>a.navbar-item.is-active,.navbar.is-link .navbar-brand .navbar-link:focus,.navbar.is-link .navbar-brand .navbar-link:hover,.navbar.is-link .navbar-brand .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-link .navbar-start>.navbar-item,.navbar.is-link .navbar-start .navbar-link,.navbar.is-link .navbar-end>.navbar-item,.navbar.is-link .navbar-end .navbar-link{color:#fff}.navbar.is-link .navbar-start>a.navbar-item:focus,.navbar.is-link .navbar-start>a.navbar-item:hover,.navbar.is-link .navbar-start>a.navbar-item.is-active,.navbar.is-link .navbar-start .navbar-link:focus,.navbar.is-link .navbar-start .navbar-link:hover,.navbar.is-link .navbar-start .navbar-link.is-active,.navbar.is-link .navbar-end>a.navbar-item:focus,.navbar.is-link .navbar-end>a.navbar-item:hover,.navbar.is-link .navbar-end>a.navbar-item.is-active,.navbar.is-link .navbar-end .navbar-link:focus,.navbar.is-link .navbar-end .navbar-link:hover,.navbar.is-link .navbar-end .navbar-link.is-active{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-start .navbar-link::after,.navbar.is-link .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-link .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-link .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-link .navbar-item.has-dropdown.is-active .navbar-link{background-color:#2958a4;color:#fff}.navbar.is-link .navbar-dropdown a.navbar-item.is-active{background-color:#2e63b8;color:#fff}}.navbar.is-info{background-color:#209cee;color:#fff}.navbar.is-info .navbar-brand>.navbar-item,.navbar.is-info .navbar-brand .navbar-link{color:#fff}.navbar.is-info .navbar-brand>a.navbar-item:focus,.navbar.is-info .navbar-brand>a.navbar-item:hover,.navbar.is-info .navbar-brand>a.navbar-item.is-active,.navbar.is-info .navbar-brand .navbar-link:focus,.navbar.is-info .navbar-brand .navbar-link:hover,.navbar.is-info .navbar-brand .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-info .navbar-start>.navbar-item,.navbar.is-info .navbar-start .navbar-link,.navbar.is-info .navbar-end>.navbar-item,.navbar.is-info .navbar-end .navbar-link{color:#fff}.navbar.is-info .navbar-start>a.navbar-item:focus,.navbar.is-info .navbar-start>a.navbar-item:hover,.navbar.is-info .navbar-start>a.navbar-item.is-active,.navbar.is-info .navbar-start .navbar-link:focus,.navbar.is-info .navbar-start .navbar-link:hover,.navbar.is-info .navbar-start .navbar-link.is-active,.navbar.is-info .navbar-end>a.navbar-item:focus,.navbar.is-info .navbar-end>a.navbar-item:hover,.navbar.is-info .navbar-end>a.navbar-item.is-active,.navbar.is-info .navbar-end .navbar-link:focus,.navbar.is-info .navbar-end .navbar-link:hover,.navbar.is-info .navbar-end .navbar-link.is-active{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-start .navbar-link::after,.navbar.is-info .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-info .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-info .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-info .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1190e3;color:#fff}.navbar.is-info .navbar-dropdown a.navbar-item.is-active{background-color:#209cee;color:#fff}}.navbar.is-success{background-color:#22c35b;color:#fff}.navbar.is-success .navbar-brand>.navbar-item,.navbar.is-success .navbar-brand .navbar-link{color:#fff}.navbar.is-success .navbar-brand>a.navbar-item:focus,.navbar.is-success .navbar-brand>a.navbar-item:hover,.navbar.is-success .navbar-brand>a.navbar-item.is-active,.navbar.is-success .navbar-brand .navbar-link:focus,.navbar.is-success .navbar-brand .navbar-link:hover,.navbar.is-success .navbar-brand .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-success .navbar-start>.navbar-item,.navbar.is-success .navbar-start .navbar-link,.navbar.is-success .navbar-end>.navbar-item,.navbar.is-success .navbar-end .navbar-link{color:#fff}.navbar.is-success .navbar-start>a.navbar-item:focus,.navbar.is-success .navbar-start>a.navbar-item:hover,.navbar.is-success .navbar-start>a.navbar-item.is-active,.navbar.is-success .navbar-start .navbar-link:focus,.navbar.is-success .navbar-start .navbar-link:hover,.navbar.is-success .navbar-start .navbar-link.is-active,.navbar.is-success .navbar-end>a.navbar-item:focus,.navbar.is-success .navbar-end>a.navbar-item:hover,.navbar.is-success .navbar-end>a.navbar-item.is-active,.navbar.is-success .navbar-end .navbar-link:focus,.navbar.is-success .navbar-end .navbar-link:hover,.navbar.is-success .navbar-end .navbar-link.is-active{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-start .navbar-link::after,.navbar.is-success .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-success .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-success .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-success .navbar-item.has-dropdown.is-active .navbar-link{background-color:#1ead51;color:#fff}.navbar.is-success .navbar-dropdown a.navbar-item.is-active{background-color:#22c35b;color:#fff}}.navbar.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>.navbar-item,.navbar.is-warning .navbar-brand .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand>a.navbar-item:focus,.navbar.is-warning .navbar-brand>a.navbar-item:hover,.navbar.is-warning .navbar-brand>a.navbar-item.is-active,.navbar.is-warning .navbar-brand .navbar-link:focus,.navbar.is-warning .navbar-brand .navbar-link:hover,.navbar.is-warning .navbar-brand .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-brand .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-burger{color:rgba(0,0,0,0.7)}@media screen and (min-width: 1056px){.navbar.is-warning .navbar-start>.navbar-item,.navbar.is-warning .navbar-start .navbar-link,.navbar.is-warning .navbar-end>.navbar-item,.navbar.is-warning .navbar-end .navbar-link{color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start>a.navbar-item:focus,.navbar.is-warning .navbar-start>a.navbar-item:hover,.navbar.is-warning .navbar-start>a.navbar-item.is-active,.navbar.is-warning .navbar-start .navbar-link:focus,.navbar.is-warning .navbar-start .navbar-link:hover,.navbar.is-warning .navbar-start .navbar-link.is-active,.navbar.is-warning .navbar-end>a.navbar-item:focus,.navbar.is-warning .navbar-end>a.navbar-item:hover,.navbar.is-warning .navbar-end>a.navbar-item.is-active,.navbar.is-warning .navbar-end .navbar-link:focus,.navbar.is-warning .navbar-end .navbar-link:hover,.navbar.is-warning .navbar-end .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-start .navbar-link::after,.navbar.is-warning .navbar-end .navbar-link::after{border-color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-warning .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-warning .navbar-item.has-dropdown.is-active .navbar-link{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.navbar.is-warning .navbar-dropdown a.navbar-item.is-active{background-color:#ffdd57;color:rgba(0,0,0,0.7)}}.navbar.is-danger{background-color:#da0b00;color:#fff}.navbar.is-danger .navbar-brand>.navbar-item,.navbar.is-danger .navbar-brand .navbar-link{color:#fff}.navbar.is-danger .navbar-brand>a.navbar-item:focus,.navbar.is-danger .navbar-brand>a.navbar-item:hover,.navbar.is-danger .navbar-brand>a.navbar-item.is-active,.navbar.is-danger .navbar-brand .navbar-link:focus,.navbar.is-danger .navbar-brand .navbar-link:hover,.navbar.is-danger .navbar-brand .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-brand .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-burger{color:#fff}@media screen and (min-width: 1056px){.navbar.is-danger .navbar-start>.navbar-item,.navbar.is-danger .navbar-start .navbar-link,.navbar.is-danger .navbar-end>.navbar-item,.navbar.is-danger .navbar-end .navbar-link{color:#fff}.navbar.is-danger .navbar-start>a.navbar-item:focus,.navbar.is-danger .navbar-start>a.navbar-item:hover,.navbar.is-danger .navbar-start>a.navbar-item.is-active,.navbar.is-danger .navbar-start .navbar-link:focus,.navbar.is-danger .navbar-start .navbar-link:hover,.navbar.is-danger .navbar-start .navbar-link.is-active,.navbar.is-danger .navbar-end>a.navbar-item:focus,.navbar.is-danger .navbar-end>a.navbar-item:hover,.navbar.is-danger .navbar-end>a.navbar-item.is-active,.navbar.is-danger .navbar-end .navbar-link:focus,.navbar.is-danger .navbar-end .navbar-link:hover,.navbar.is-danger .navbar-end .navbar-link.is-active{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-start .navbar-link::after,.navbar.is-danger .navbar-end .navbar-link::after{border-color:#fff}.navbar.is-danger .navbar-item.has-dropdown:focus .navbar-link,.navbar.is-danger .navbar-item.has-dropdown:hover .navbar-link,.navbar.is-danger .navbar-item.has-dropdown.is-active .navbar-link{background-color:#c10a00;color:#fff}.navbar.is-danger .navbar-dropdown a.navbar-item.is-active{background-color:#da0b00;color:#fff}}.navbar>.container{align-items:stretch;display:flex;min-height:3.25rem;width:100%}.navbar.has-shadow{box-shadow:0 2px 0 0 #f5f5f5}.navbar.is-fixed-bottom,.navbar.is-fixed-top{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom{bottom:0}.navbar.is-fixed-bottom.has-shadow{box-shadow:0 -2px 0 0 #f5f5f5}.navbar.is-fixed-top{top:0}html.has-navbar-fixed-top,body.has-navbar-fixed-top{padding-top:3.25rem}html.has-navbar-fixed-bottom,body.has-navbar-fixed-bottom{padding-bottom:3.25rem}.navbar-brand,.navbar-tabs{align-items:stretch;display:flex;flex-shrink:0;min-height:3.25rem}.navbar-brand a.navbar-item:focus,.navbar-brand a.navbar-item:hover{background-color:transparent}.navbar-tabs{-webkit-overflow-scrolling:touch;max-width:100vw;overflow-x:auto;overflow-y:hidden}.navbar-burger{color:#222;-moz-appearance:none;-webkit-appearance:none;appearance:none;background:none;border:none;cursor:pointer;display:block;height:3.25rem;position:relative;width:3.25rem;margin-left:auto}.navbar-burger span{background-color:currentColor;display:block;height:1px;left:calc(50% - 8px);position:absolute;transform-origin:center;transition-duration:86ms;transition-property:background-color, opacity, transform;transition-timing-function:ease-out;width:16px}.navbar-burger span:nth-child(1){top:calc(50% - 6px)}.navbar-burger span:nth-child(2){top:calc(50% - 1px)}.navbar-burger span:nth-child(3){top:calc(50% + 4px)}.navbar-burger:hover{background-color:rgba(0,0,0,0.05)}.navbar-burger.is-active span:nth-child(1){transform:translateY(5px) rotate(45deg)}.navbar-burger.is-active span:nth-child(2){opacity:0}.navbar-burger.is-active span:nth-child(3){transform:translateY(-5px) rotate(-45deg)}.navbar-menu{display:none}.navbar-item,.navbar-link{color:#222;display:block;line-height:1.5;padding:0.5rem 0.75rem;position:relative}.navbar-item .icon:only-child,.navbar-link .icon:only-child{margin-left:-0.25rem;margin-right:-0.25rem}a.navbar-item,.navbar-link{cursor:pointer}a.navbar-item:focus,a.navbar-item:focus-within,a.navbar-item:hover,a.navbar-item.is-active,.navbar-link:focus,.navbar-link:focus-within,.navbar-link:hover,.navbar-link.is-active{background-color:#fafafa;color:#2e63b8}.navbar-item{flex-grow:0;flex-shrink:0}.navbar-item img{max-height:1.75rem}.navbar-item.has-dropdown{padding:0}.navbar-item.is-expanded{flex-grow:1;flex-shrink:1}.navbar-item.is-tab{border-bottom:1px solid transparent;min-height:3.25rem;padding-bottom:calc(0.5rem - 1px)}.navbar-item.is-tab:focus,.navbar-item.is-tab:hover{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8}.navbar-item.is-tab.is-active{background-color:rgba(0,0,0,0);border-bottom-color:#2e63b8;border-bottom-style:solid;border-bottom-width:3px;color:#2e63b8;padding-bottom:calc(0.5rem - 3px)}.navbar-content{flex-grow:1;flex-shrink:1}.navbar-link:not(.is-arrowless){padding-right:2.5em}.navbar-link:not(.is-arrowless)::after{border-color:#2e63b8;margin-top:-0.375em;right:1.125em}.navbar-dropdown{font-size:0.875rem;padding-bottom:0.5rem;padding-top:0.5rem}.navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}.navbar-divider{background-color:#f5f5f5;border:none;display:none;height:2px;margin:0.5rem 0}@media screen and (max-width: 1055px){.navbar>.container{display:block}.navbar-brand .navbar-item,.navbar-tabs .navbar-item{align-items:center;display:flex}.navbar-link::after{display:none}.navbar-menu{background-color:#fff;box-shadow:0 8px 16px rgba(10,10,10,0.1);padding:0.5rem 0}.navbar-menu.is-active{display:block}.navbar.is-fixed-bottom-touch,.navbar.is-fixed-top-touch{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-touch{bottom:0}.navbar.is-fixed-bottom-touch.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-touch{top:0}.navbar.is-fixed-top .navbar-menu,.navbar.is-fixed-top-touch .navbar-menu{-webkit-overflow-scrolling:touch;max-height:calc(100vh - 3.25rem);overflow:auto}html.has-navbar-fixed-top-touch,body.has-navbar-fixed-top-touch{padding-top:3.25rem}html.has-navbar-fixed-bottom-touch,body.has-navbar-fixed-bottom-touch{padding-bottom:3.25rem}}@media screen and (min-width: 1056px){.navbar,.navbar-menu,.navbar-start,.navbar-end{align-items:stretch;display:flex}.navbar{min-height:3.25rem}.navbar.is-spaced{padding:1rem 2rem}.navbar.is-spaced .navbar-start,.navbar.is-spaced .navbar-end{align-items:center}.navbar.is-spaced a.navbar-item,.navbar.is-spaced .navbar-link{border-radius:4px}.navbar.is-transparent a.navbar-item:focus,.navbar.is-transparent a.navbar-item:hover,.navbar.is-transparent a.navbar-item.is-active,.navbar.is-transparent .navbar-link:focus,.navbar.is-transparent .navbar-link:hover,.navbar.is-transparent .navbar-link.is-active{background-color:transparent !important}.navbar.is-transparent .navbar-item.has-dropdown.is-active .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:focus-within .navbar-link,.navbar.is-transparent .navbar-item.has-dropdown.is-hoverable:hover .navbar-link{background-color:transparent !important}.navbar.is-transparent .navbar-dropdown a.navbar-item:focus,.navbar.is-transparent .navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar.is-transparent .navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar-burger{display:none}.navbar-item,.navbar-link{align-items:center;display:flex}.navbar-item.has-dropdown{align-items:stretch}.navbar-item.has-dropdown-up .navbar-link::after{transform:rotate(135deg) translate(0.25em, -0.25em)}.navbar-item.has-dropdown-up .navbar-dropdown{border-bottom:2px solid #dbdbdb;border-radius:6px 6px 0 0;border-top:none;bottom:100%;box-shadow:0 -8px 8px rgba(10,10,10,0.1);top:auto}.navbar-item.is-active .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar.is-spaced .navbar-item.is-active .navbar-dropdown,.navbar-item.is-active .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus .navbar-dropdown,.navbar-item.is-hoverable:focus .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:focus-within .navbar-dropdown,.navbar-item.is-hoverable:focus-within .navbar-dropdown.is-boxed,.navbar.is-spaced .navbar-item.is-hoverable:hover .navbar-dropdown,.navbar-item.is-hoverable:hover .navbar-dropdown.is-boxed{opacity:1;pointer-events:auto;transform:translateY(0)}.navbar-menu{flex-grow:1;flex-shrink:0}.navbar-start{justify-content:flex-start;margin-right:auto}.navbar-end{justify-content:flex-end;margin-left:auto}.navbar-dropdown{background-color:#fff;border-bottom-left-radius:6px;border-bottom-right-radius:6px;border-top:2px solid #dbdbdb;box-shadow:0 8px 8px rgba(10,10,10,0.1);display:none;font-size:0.875rem;left:0;min-width:100%;position:absolute;top:100%;z-index:20}.navbar-dropdown .navbar-item{padding:0.375rem 1rem;white-space:nowrap}.navbar-dropdown a.navbar-item{padding-right:3rem}.navbar-dropdown a.navbar-item:focus,.navbar-dropdown a.navbar-item:hover{background-color:#f5f5f5;color:#0a0a0a}.navbar-dropdown a.navbar-item.is-active{background-color:#f5f5f5;color:#2e63b8}.navbar.is-spaced .navbar-dropdown,.navbar-dropdown.is-boxed{border-radius:6px;border-top:none;box-shadow:0 8px 8px rgba(10,10,10,0.1), 0 0 0 1px rgba(10,10,10,0.1);display:block;opacity:0;pointer-events:none;top:calc(100% + (-4px));transform:translateY(-5px);transition-duration:86ms;transition-property:opacity, transform}.navbar-dropdown.is-right{left:auto;right:0}.navbar-divider{display:block}.navbar>.container .navbar-brand,.container>.navbar .navbar-brand{margin-left:-.75rem}.navbar>.container .navbar-menu,.container>.navbar .navbar-menu{margin-right:-.75rem}.navbar.is-fixed-bottom-desktop,.navbar.is-fixed-top-desktop{left:0;position:fixed;right:0;z-index:30}.navbar.is-fixed-bottom-desktop{bottom:0}.navbar.is-fixed-bottom-desktop.has-shadow{box-shadow:0 -2px 3px rgba(10,10,10,0.1)}.navbar.is-fixed-top-desktop{top:0}html.has-navbar-fixed-top-desktop,body.has-navbar-fixed-top-desktop{padding-top:3.25rem}html.has-navbar-fixed-bottom-desktop,body.has-navbar-fixed-bottom-desktop{padding-bottom:3.25rem}html.has-spaced-navbar-fixed-top,body.has-spaced-navbar-fixed-top{padding-top:5.25rem}html.has-spaced-navbar-fixed-bottom,body.has-spaced-navbar-fixed-bottom{padding-bottom:5.25rem}a.navbar-item.is-active,.navbar-link.is-active{color:#0a0a0a}a.navbar-item.is-active:not(:focus):not(:hover),.navbar-link.is-active:not(:focus):not(:hover){background-color:rgba(0,0,0,0)}.navbar-item.has-dropdown:focus .navbar-link,.navbar-item.has-dropdown:hover .navbar-link,.navbar-item.has-dropdown.is-active .navbar-link{background-color:#fafafa}}.hero.is-fullheight-with-navbar{min-height:calc(100vh - 3.25rem)}.pagination{font-size:1rem;margin:-.25rem}.pagination.is-small,#documenter .docs-sidebar form.docs-search>input.pagination{font-size:.75rem}.pagination.is-medium{font-size:1.25rem}.pagination.is-large{font-size:1.5rem}.pagination.is-rounded .pagination-previous,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-previous,.pagination.is-rounded .pagination-next,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-next{padding-left:1em;padding-right:1em;border-radius:9999px}.pagination.is-rounded .pagination-link,#documenter .docs-sidebar form.docs-search>input.pagination .pagination-link{border-radius:9999px}.pagination,.pagination-list{align-items:center;display:flex;justify-content:center;text-align:center}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{font-size:1em;justify-content:center;margin:.25rem;padding-left:.5em;padding-right:.5em;text-align:center}.pagination-previous,.pagination-next,.pagination-link{border-color:#dbdbdb;color:#222;min-width:2.5em}.pagination-previous:hover,.pagination-next:hover,.pagination-link:hover{border-color:#b5b5b5;color:#363636}.pagination-previous:focus,.pagination-next:focus,.pagination-link:focus{border-color:#3c5dcd}.pagination-previous:active,.pagination-next:active,.pagination-link:active{box-shadow:inset 0 1px 2px rgba(10,10,10,0.2)}.pagination-previous[disabled],.pagination-previous.is-disabled,.pagination-next[disabled],.pagination-next.is-disabled,.pagination-link[disabled],.pagination-link.is-disabled{background-color:#dbdbdb;border-color:#dbdbdb;box-shadow:none;color:#6b6b6b;opacity:0.5}.pagination-previous,.pagination-next{padding-left:.75em;padding-right:.75em;white-space:nowrap}.pagination-link.is-current{background-color:#2e63b8;border-color:#2e63b8;color:#fff}.pagination-ellipsis{color:#b5b5b5;pointer-events:none}.pagination-list{flex-wrap:wrap}.pagination-list li{list-style:none}@media screen and (max-width: 768px){.pagination{flex-wrap:wrap}.pagination-previous,.pagination-next{flex-grow:1;flex-shrink:1}.pagination-list li{flex-grow:1;flex-shrink:1}}@media screen and (min-width: 769px),print{.pagination-list{flex-grow:1;flex-shrink:1;justify-content:flex-start;order:1}.pagination-previous,.pagination-next,.pagination-link,.pagination-ellipsis{margin-bottom:0;margin-top:0}.pagination-previous{order:2}.pagination-next{order:3}.pagination{justify-content:space-between;margin-bottom:0;margin-top:0}.pagination.is-centered .pagination-previous{order:1}.pagination.is-centered .pagination-list{justify-content:center;order:2}.pagination.is-centered .pagination-next{order:3}.pagination.is-right .pagination-previous{order:1}.pagination.is-right .pagination-next{order:2}.pagination.is-right .pagination-list{justify-content:flex-end;order:3}}.panel{border-radius:6px;box-shadow:#bbb;font-size:1rem}.panel:not(:last-child){margin-bottom:1.5rem}.panel.is-white .panel-heading{background-color:#fff;color:#0a0a0a}.panel.is-white .panel-tabs a.is-active{border-bottom-color:#fff}.panel.is-white .panel-block.is-active .panel-icon{color:#fff}.panel.is-black .panel-heading{background-color:#0a0a0a;color:#fff}.panel.is-black .panel-tabs a.is-active{border-bottom-color:#0a0a0a}.panel.is-black .panel-block.is-active .panel-icon{color:#0a0a0a}.panel.is-light .panel-heading{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.panel.is-light .panel-tabs a.is-active{border-bottom-color:#f5f5f5}.panel.is-light .panel-block.is-active .panel-icon{color:#f5f5f5}.panel.is-dark .panel-heading,.content kbd.panel .panel-heading{background-color:#363636;color:#fff}.panel.is-dark .panel-tabs a.is-active,.content kbd.panel .panel-tabs a.is-active{border-bottom-color:#363636}.panel.is-dark .panel-block.is-active .panel-icon,.content kbd.panel .panel-block.is-active .panel-icon{color:#363636}.panel.is-primary .panel-heading,.docstring>section>a.panel.docs-sourcelink .panel-heading{background-color:#4eb5de;color:#fff}.panel.is-primary .panel-tabs a.is-active,.docstring>section>a.panel.docs-sourcelink .panel-tabs a.is-active{border-bottom-color:#4eb5de}.panel.is-primary .panel-block.is-active .panel-icon,.docstring>section>a.panel.docs-sourcelink .panel-block.is-active .panel-icon{color:#4eb5de}.panel.is-link .panel-heading{background-color:#2e63b8;color:#fff}.panel.is-link .panel-tabs a.is-active{border-bottom-color:#2e63b8}.panel.is-link .panel-block.is-active .panel-icon{color:#2e63b8}.panel.is-info .panel-heading{background-color:#209cee;color:#fff}.panel.is-info .panel-tabs a.is-active{border-bottom-color:#209cee}.panel.is-info .panel-block.is-active .panel-icon{color:#209cee}.panel.is-success .panel-heading{background-color:#22c35b;color:#fff}.panel.is-success .panel-tabs a.is-active{border-bottom-color:#22c35b}.panel.is-success .panel-block.is-active .panel-icon{color:#22c35b}.panel.is-warning .panel-heading{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.panel.is-warning .panel-tabs a.is-active{border-bottom-color:#ffdd57}.panel.is-warning .panel-block.is-active .panel-icon{color:#ffdd57}.panel.is-danger .panel-heading{background-color:#da0b00;color:#fff}.panel.is-danger .panel-tabs a.is-active{border-bottom-color:#da0b00}.panel.is-danger .panel-block.is-active .panel-icon{color:#da0b00}.panel-tabs:not(:last-child),.panel-block:not(:last-child){border-bottom:1px solid #ededed}.panel-heading{background-color:#ededed;border-radius:6px 6px 0 0;color:#222;font-size:1.25em;font-weight:700;line-height:1.25;padding:0.75em 1em}.panel-tabs{align-items:flex-end;display:flex;font-size:.875em;justify-content:center}.panel-tabs a{border-bottom:1px solid #dbdbdb;margin-bottom:-1px;padding:0.5em}.panel-tabs a.is-active{border-bottom-color:#4a4a4a;color:#363636}.panel-list a{color:#222}.panel-list a:hover{color:#2e63b8}.panel-block{align-items:center;color:#222;display:flex;justify-content:flex-start;padding:0.5em 0.75em}.panel-block input[type="checkbox"]{margin-right:.75em}.panel-block>.control{flex-grow:1;flex-shrink:1;width:100%}.panel-block.is-wrapped{flex-wrap:wrap}.panel-block.is-active{border-left-color:#2e63b8;color:#363636}.panel-block.is-active .panel-icon{color:#2e63b8}.panel-block:last-child{border-bottom-left-radius:6px;border-bottom-right-radius:6px}a.panel-block,label.panel-block{cursor:pointer}a.panel-block:hover,label.panel-block:hover{background-color:#f5f5f5}.panel-icon{display:inline-block;font-size:14px;height:1em;line-height:1em;text-align:center;vertical-align:top;width:1em;color:#6b6b6b;margin-right:.75em}.panel-icon .fa{font-size:inherit;line-height:inherit}.tabs{-webkit-overflow-scrolling:touch;align-items:stretch;display:flex;font-size:1rem;justify-content:space-between;overflow:hidden;overflow-x:auto;white-space:nowrap}.tabs a{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;color:#222;display:flex;justify-content:center;margin-bottom:-1px;padding:0.5em 1em;vertical-align:top}.tabs a:hover{border-bottom-color:#222;color:#222}.tabs li{display:block}.tabs li.is-active a{border-bottom-color:#2e63b8;color:#2e63b8}.tabs ul{align-items:center;border-bottom-color:#dbdbdb;border-bottom-style:solid;border-bottom-width:1px;display:flex;flex-grow:1;flex-shrink:0;justify-content:flex-start}.tabs ul.is-left{padding-right:0.75em}.tabs ul.is-center{flex:none;justify-content:center;padding-left:0.75em;padding-right:0.75em}.tabs ul.is-right{justify-content:flex-end;padding-left:0.75em}.tabs .icon:first-child{margin-right:.5em}.tabs .icon:last-child{margin-left:.5em}.tabs.is-centered ul{justify-content:center}.tabs.is-right ul{justify-content:flex-end}.tabs.is-boxed a{border:1px solid transparent;border-radius:4px 4px 0 0}.tabs.is-boxed a:hover{background-color:#f5f5f5;border-bottom-color:#dbdbdb}.tabs.is-boxed li.is-active a{background-color:#fff;border-color:#dbdbdb;border-bottom-color:rgba(0,0,0,0) !important}.tabs.is-fullwidth li{flex-grow:1;flex-shrink:0}.tabs.is-toggle a{border-color:#dbdbdb;border-style:solid;border-width:1px;margin-bottom:0;position:relative}.tabs.is-toggle a:hover{background-color:#f5f5f5;border-color:#b5b5b5;z-index:2}.tabs.is-toggle li+li{margin-left:-1px}.tabs.is-toggle li:first-child a{border-top-left-radius:4px;border-bottom-left-radius:4px}.tabs.is-toggle li:last-child a{border-top-right-radius:4px;border-bottom-right-radius:4px}.tabs.is-toggle li.is-active a{background-color:#2e63b8;border-color:#2e63b8;color:#fff;z-index:1}.tabs.is-toggle ul{border-bottom:none}.tabs.is-toggle.is-toggle-rounded li:first-child a{border-bottom-left-radius:9999px;border-top-left-radius:9999px;padding-left:1.25em}.tabs.is-toggle.is-toggle-rounded li:last-child a{border-bottom-right-radius:9999px;border-top-right-radius:9999px;padding-right:1.25em}.tabs.is-small,#documenter .docs-sidebar form.docs-search>input.tabs{font-size:.75rem}.tabs.is-medium{font-size:1.25rem}.tabs.is-large{font-size:1.5rem}.column{display:block;flex-basis:0;flex-grow:1;flex-shrink:1;padding:.75rem}.columns.is-mobile>.column.is-narrow{flex:none;width:unset}.columns.is-mobile>.column.is-full{flex:none;width:100%}.columns.is-mobile>.column.is-three-quarters{flex:none;width:75%}.columns.is-mobile>.column.is-two-thirds{flex:none;width:66.6666%}.columns.is-mobile>.column.is-half{flex:none;width:50%}.columns.is-mobile>.column.is-one-third{flex:none;width:33.3333%}.columns.is-mobile>.column.is-one-quarter{flex:none;width:25%}.columns.is-mobile>.column.is-one-fifth{flex:none;width:20%}.columns.is-mobile>.column.is-two-fifths{flex:none;width:40%}.columns.is-mobile>.column.is-three-fifths{flex:none;width:60%}.columns.is-mobile>.column.is-four-fifths{flex:none;width:80%}.columns.is-mobile>.column.is-offset-three-quarters{margin-left:75%}.columns.is-mobile>.column.is-offset-two-thirds{margin-left:66.6666%}.columns.is-mobile>.column.is-offset-half{margin-left:50%}.columns.is-mobile>.column.is-offset-one-third{margin-left:33.3333%}.columns.is-mobile>.column.is-offset-one-quarter{margin-left:25%}.columns.is-mobile>.column.is-offset-one-fifth{margin-left:20%}.columns.is-mobile>.column.is-offset-two-fifths{margin-left:40%}.columns.is-mobile>.column.is-offset-three-fifths{margin-left:60%}.columns.is-mobile>.column.is-offset-four-fifths{margin-left:80%}.columns.is-mobile>.column.is-0{flex:none;width:0%}.columns.is-mobile>.column.is-offset-0{margin-left:0%}.columns.is-mobile>.column.is-1{flex:none;width:8.33333337%}.columns.is-mobile>.column.is-offset-1{margin-left:8.33333337%}.columns.is-mobile>.column.is-2{flex:none;width:16.66666674%}.columns.is-mobile>.column.is-offset-2{margin-left:16.66666674%}.columns.is-mobile>.column.is-3{flex:none;width:25%}.columns.is-mobile>.column.is-offset-3{margin-left:25%}.columns.is-mobile>.column.is-4{flex:none;width:33.33333337%}.columns.is-mobile>.column.is-offset-4{margin-left:33.33333337%}.columns.is-mobile>.column.is-5{flex:none;width:41.66666674%}.columns.is-mobile>.column.is-offset-5{margin-left:41.66666674%}.columns.is-mobile>.column.is-6{flex:none;width:50%}.columns.is-mobile>.column.is-offset-6{margin-left:50%}.columns.is-mobile>.column.is-7{flex:none;width:58.33333337%}.columns.is-mobile>.column.is-offset-7{margin-left:58.33333337%}.columns.is-mobile>.column.is-8{flex:none;width:66.66666674%}.columns.is-mobile>.column.is-offset-8{margin-left:66.66666674%}.columns.is-mobile>.column.is-9{flex:none;width:75%}.columns.is-mobile>.column.is-offset-9{margin-left:75%}.columns.is-mobile>.column.is-10{flex:none;width:83.33333337%}.columns.is-mobile>.column.is-offset-10{margin-left:83.33333337%}.columns.is-mobile>.column.is-11{flex:none;width:91.66666674%}.columns.is-mobile>.column.is-offset-11{margin-left:91.66666674%}.columns.is-mobile>.column.is-12{flex:none;width:100%}.columns.is-mobile>.column.is-offset-12{margin-left:100%}@media screen and (max-width: 768px){.column.is-narrow-mobile{flex:none;width:unset}.column.is-full-mobile{flex:none;width:100%}.column.is-three-quarters-mobile{flex:none;width:75%}.column.is-two-thirds-mobile{flex:none;width:66.6666%}.column.is-half-mobile{flex:none;width:50%}.column.is-one-third-mobile{flex:none;width:33.3333%}.column.is-one-quarter-mobile{flex:none;width:25%}.column.is-one-fifth-mobile{flex:none;width:20%}.column.is-two-fifths-mobile{flex:none;width:40%}.column.is-three-fifths-mobile{flex:none;width:60%}.column.is-four-fifths-mobile{flex:none;width:80%}.column.is-offset-three-quarters-mobile{margin-left:75%}.column.is-offset-two-thirds-mobile{margin-left:66.6666%}.column.is-offset-half-mobile{margin-left:50%}.column.is-offset-one-third-mobile{margin-left:33.3333%}.column.is-offset-one-quarter-mobile{margin-left:25%}.column.is-offset-one-fifth-mobile{margin-left:20%}.column.is-offset-two-fifths-mobile{margin-left:40%}.column.is-offset-three-fifths-mobile{margin-left:60%}.column.is-offset-four-fifths-mobile{margin-left:80%}.column.is-0-mobile{flex:none;width:0%}.column.is-offset-0-mobile{margin-left:0%}.column.is-1-mobile{flex:none;width:8.33333337%}.column.is-offset-1-mobile{margin-left:8.33333337%}.column.is-2-mobile{flex:none;width:16.66666674%}.column.is-offset-2-mobile{margin-left:16.66666674%}.column.is-3-mobile{flex:none;width:25%}.column.is-offset-3-mobile{margin-left:25%}.column.is-4-mobile{flex:none;width:33.33333337%}.column.is-offset-4-mobile{margin-left:33.33333337%}.column.is-5-mobile{flex:none;width:41.66666674%}.column.is-offset-5-mobile{margin-left:41.66666674%}.column.is-6-mobile{flex:none;width:50%}.column.is-offset-6-mobile{margin-left:50%}.column.is-7-mobile{flex:none;width:58.33333337%}.column.is-offset-7-mobile{margin-left:58.33333337%}.column.is-8-mobile{flex:none;width:66.66666674%}.column.is-offset-8-mobile{margin-left:66.66666674%}.column.is-9-mobile{flex:none;width:75%}.column.is-offset-9-mobile{margin-left:75%}.column.is-10-mobile{flex:none;width:83.33333337%}.column.is-offset-10-mobile{margin-left:83.33333337%}.column.is-11-mobile{flex:none;width:91.66666674%}.column.is-offset-11-mobile{margin-left:91.66666674%}.column.is-12-mobile{flex:none;width:100%}.column.is-offset-12-mobile{margin-left:100%}}@media screen and (min-width: 769px),print{.column.is-narrow,.column.is-narrow-tablet{flex:none;width:unset}.column.is-full,.column.is-full-tablet{flex:none;width:100%}.column.is-three-quarters,.column.is-three-quarters-tablet{flex:none;width:75%}.column.is-two-thirds,.column.is-two-thirds-tablet{flex:none;width:66.6666%}.column.is-half,.column.is-half-tablet{flex:none;width:50%}.column.is-one-third,.column.is-one-third-tablet{flex:none;width:33.3333%}.column.is-one-quarter,.column.is-one-quarter-tablet{flex:none;width:25%}.column.is-one-fifth,.column.is-one-fifth-tablet{flex:none;width:20%}.column.is-two-fifths,.column.is-two-fifths-tablet{flex:none;width:40%}.column.is-three-fifths,.column.is-three-fifths-tablet{flex:none;width:60%}.column.is-four-fifths,.column.is-four-fifths-tablet{flex:none;width:80%}.column.is-offset-three-quarters,.column.is-offset-three-quarters-tablet{margin-left:75%}.column.is-offset-two-thirds,.column.is-offset-two-thirds-tablet{margin-left:66.6666%}.column.is-offset-half,.column.is-offset-half-tablet{margin-left:50%}.column.is-offset-one-third,.column.is-offset-one-third-tablet{margin-left:33.3333%}.column.is-offset-one-quarter,.column.is-offset-one-quarter-tablet{margin-left:25%}.column.is-offset-one-fifth,.column.is-offset-one-fifth-tablet{margin-left:20%}.column.is-offset-two-fifths,.column.is-offset-two-fifths-tablet{margin-left:40%}.column.is-offset-three-fifths,.column.is-offset-three-fifths-tablet{margin-left:60%}.column.is-offset-four-fifths,.column.is-offset-four-fifths-tablet{margin-left:80%}.column.is-0,.column.is-0-tablet{flex:none;width:0%}.column.is-offset-0,.column.is-offset-0-tablet{margin-left:0%}.column.is-1,.column.is-1-tablet{flex:none;width:8.33333337%}.column.is-offset-1,.column.is-offset-1-tablet{margin-left:8.33333337%}.column.is-2,.column.is-2-tablet{flex:none;width:16.66666674%}.column.is-offset-2,.column.is-offset-2-tablet{margin-left:16.66666674%}.column.is-3,.column.is-3-tablet{flex:none;width:25%}.column.is-offset-3,.column.is-offset-3-tablet{margin-left:25%}.column.is-4,.column.is-4-tablet{flex:none;width:33.33333337%}.column.is-offset-4,.column.is-offset-4-tablet{margin-left:33.33333337%}.column.is-5,.column.is-5-tablet{flex:none;width:41.66666674%}.column.is-offset-5,.column.is-offset-5-tablet{margin-left:41.66666674%}.column.is-6,.column.is-6-tablet{flex:none;width:50%}.column.is-offset-6,.column.is-offset-6-tablet{margin-left:50%}.column.is-7,.column.is-7-tablet{flex:none;width:58.33333337%}.column.is-offset-7,.column.is-offset-7-tablet{margin-left:58.33333337%}.column.is-8,.column.is-8-tablet{flex:none;width:66.66666674%}.column.is-offset-8,.column.is-offset-8-tablet{margin-left:66.66666674%}.column.is-9,.column.is-9-tablet{flex:none;width:75%}.column.is-offset-9,.column.is-offset-9-tablet{margin-left:75%}.column.is-10,.column.is-10-tablet{flex:none;width:83.33333337%}.column.is-offset-10,.column.is-offset-10-tablet{margin-left:83.33333337%}.column.is-11,.column.is-11-tablet{flex:none;width:91.66666674%}.column.is-offset-11,.column.is-offset-11-tablet{margin-left:91.66666674%}.column.is-12,.column.is-12-tablet{flex:none;width:100%}.column.is-offset-12,.column.is-offset-12-tablet{margin-left:100%}}@media screen and (max-width: 1055px){.column.is-narrow-touch{flex:none;width:unset}.column.is-full-touch{flex:none;width:100%}.column.is-three-quarters-touch{flex:none;width:75%}.column.is-two-thirds-touch{flex:none;width:66.6666%}.column.is-half-touch{flex:none;width:50%}.column.is-one-third-touch{flex:none;width:33.3333%}.column.is-one-quarter-touch{flex:none;width:25%}.column.is-one-fifth-touch{flex:none;width:20%}.column.is-two-fifths-touch{flex:none;width:40%}.column.is-three-fifths-touch{flex:none;width:60%}.column.is-four-fifths-touch{flex:none;width:80%}.column.is-offset-three-quarters-touch{margin-left:75%}.column.is-offset-two-thirds-touch{margin-left:66.6666%}.column.is-offset-half-touch{margin-left:50%}.column.is-offset-one-third-touch{margin-left:33.3333%}.column.is-offset-one-quarter-touch{margin-left:25%}.column.is-offset-one-fifth-touch{margin-left:20%}.column.is-offset-two-fifths-touch{margin-left:40%}.column.is-offset-three-fifths-touch{margin-left:60%}.column.is-offset-four-fifths-touch{margin-left:80%}.column.is-0-touch{flex:none;width:0%}.column.is-offset-0-touch{margin-left:0%}.column.is-1-touch{flex:none;width:8.33333337%}.column.is-offset-1-touch{margin-left:8.33333337%}.column.is-2-touch{flex:none;width:16.66666674%}.column.is-offset-2-touch{margin-left:16.66666674%}.column.is-3-touch{flex:none;width:25%}.column.is-offset-3-touch{margin-left:25%}.column.is-4-touch{flex:none;width:33.33333337%}.column.is-offset-4-touch{margin-left:33.33333337%}.column.is-5-touch{flex:none;width:41.66666674%}.column.is-offset-5-touch{margin-left:41.66666674%}.column.is-6-touch{flex:none;width:50%}.column.is-offset-6-touch{margin-left:50%}.column.is-7-touch{flex:none;width:58.33333337%}.column.is-offset-7-touch{margin-left:58.33333337%}.column.is-8-touch{flex:none;width:66.66666674%}.column.is-offset-8-touch{margin-left:66.66666674%}.column.is-9-touch{flex:none;width:75%}.column.is-offset-9-touch{margin-left:75%}.column.is-10-touch{flex:none;width:83.33333337%}.column.is-offset-10-touch{margin-left:83.33333337%}.column.is-11-touch{flex:none;width:91.66666674%}.column.is-offset-11-touch{margin-left:91.66666674%}.column.is-12-touch{flex:none;width:100%}.column.is-offset-12-touch{margin-left:100%}}@media screen and (min-width: 1056px){.column.is-narrow-desktop{flex:none;width:unset}.column.is-full-desktop{flex:none;width:100%}.column.is-three-quarters-desktop{flex:none;width:75%}.column.is-two-thirds-desktop{flex:none;width:66.6666%}.column.is-half-desktop{flex:none;width:50%}.column.is-one-third-desktop{flex:none;width:33.3333%}.column.is-one-quarter-desktop{flex:none;width:25%}.column.is-one-fifth-desktop{flex:none;width:20%}.column.is-two-fifths-desktop{flex:none;width:40%}.column.is-three-fifths-desktop{flex:none;width:60%}.column.is-four-fifths-desktop{flex:none;width:80%}.column.is-offset-three-quarters-desktop{margin-left:75%}.column.is-offset-two-thirds-desktop{margin-left:66.6666%}.column.is-offset-half-desktop{margin-left:50%}.column.is-offset-one-third-desktop{margin-left:33.3333%}.column.is-offset-one-quarter-desktop{margin-left:25%}.column.is-offset-one-fifth-desktop{margin-left:20%}.column.is-offset-two-fifths-desktop{margin-left:40%}.column.is-offset-three-fifths-desktop{margin-left:60%}.column.is-offset-four-fifths-desktop{margin-left:80%}.column.is-0-desktop{flex:none;width:0%}.column.is-offset-0-desktop{margin-left:0%}.column.is-1-desktop{flex:none;width:8.33333337%}.column.is-offset-1-desktop{margin-left:8.33333337%}.column.is-2-desktop{flex:none;width:16.66666674%}.column.is-offset-2-desktop{margin-left:16.66666674%}.column.is-3-desktop{flex:none;width:25%}.column.is-offset-3-desktop{margin-left:25%}.column.is-4-desktop{flex:none;width:33.33333337%}.column.is-offset-4-desktop{margin-left:33.33333337%}.column.is-5-desktop{flex:none;width:41.66666674%}.column.is-offset-5-desktop{margin-left:41.66666674%}.column.is-6-desktop{flex:none;width:50%}.column.is-offset-6-desktop{margin-left:50%}.column.is-7-desktop{flex:none;width:58.33333337%}.column.is-offset-7-desktop{margin-left:58.33333337%}.column.is-8-desktop{flex:none;width:66.66666674%}.column.is-offset-8-desktop{margin-left:66.66666674%}.column.is-9-desktop{flex:none;width:75%}.column.is-offset-9-desktop{margin-left:75%}.column.is-10-desktop{flex:none;width:83.33333337%}.column.is-offset-10-desktop{margin-left:83.33333337%}.column.is-11-desktop{flex:none;width:91.66666674%}.column.is-offset-11-desktop{margin-left:91.66666674%}.column.is-12-desktop{flex:none;width:100%}.column.is-offset-12-desktop{margin-left:100%}}@media screen and (min-width: 1216px){.column.is-narrow-widescreen{flex:none;width:unset}.column.is-full-widescreen{flex:none;width:100%}.column.is-three-quarters-widescreen{flex:none;width:75%}.column.is-two-thirds-widescreen{flex:none;width:66.6666%}.column.is-half-widescreen{flex:none;width:50%}.column.is-one-third-widescreen{flex:none;width:33.3333%}.column.is-one-quarter-widescreen{flex:none;width:25%}.column.is-one-fifth-widescreen{flex:none;width:20%}.column.is-two-fifths-widescreen{flex:none;width:40%}.column.is-three-fifths-widescreen{flex:none;width:60%}.column.is-four-fifths-widescreen{flex:none;width:80%}.column.is-offset-three-quarters-widescreen{margin-left:75%}.column.is-offset-two-thirds-widescreen{margin-left:66.6666%}.column.is-offset-half-widescreen{margin-left:50%}.column.is-offset-one-third-widescreen{margin-left:33.3333%}.column.is-offset-one-quarter-widescreen{margin-left:25%}.column.is-offset-one-fifth-widescreen{margin-left:20%}.column.is-offset-two-fifths-widescreen{margin-left:40%}.column.is-offset-three-fifths-widescreen{margin-left:60%}.column.is-offset-four-fifths-widescreen{margin-left:80%}.column.is-0-widescreen{flex:none;width:0%}.column.is-offset-0-widescreen{margin-left:0%}.column.is-1-widescreen{flex:none;width:8.33333337%}.column.is-offset-1-widescreen{margin-left:8.33333337%}.column.is-2-widescreen{flex:none;width:16.66666674%}.column.is-offset-2-widescreen{margin-left:16.66666674%}.column.is-3-widescreen{flex:none;width:25%}.column.is-offset-3-widescreen{margin-left:25%}.column.is-4-widescreen{flex:none;width:33.33333337%}.column.is-offset-4-widescreen{margin-left:33.33333337%}.column.is-5-widescreen{flex:none;width:41.66666674%}.column.is-offset-5-widescreen{margin-left:41.66666674%}.column.is-6-widescreen{flex:none;width:50%}.column.is-offset-6-widescreen{margin-left:50%}.column.is-7-widescreen{flex:none;width:58.33333337%}.column.is-offset-7-widescreen{margin-left:58.33333337%}.column.is-8-widescreen{flex:none;width:66.66666674%}.column.is-offset-8-widescreen{margin-left:66.66666674%}.column.is-9-widescreen{flex:none;width:75%}.column.is-offset-9-widescreen{margin-left:75%}.column.is-10-widescreen{flex:none;width:83.33333337%}.column.is-offset-10-widescreen{margin-left:83.33333337%}.column.is-11-widescreen{flex:none;width:91.66666674%}.column.is-offset-11-widescreen{margin-left:91.66666674%}.column.is-12-widescreen{flex:none;width:100%}.column.is-offset-12-widescreen{margin-left:100%}}@media screen and (min-width: 1408px){.column.is-narrow-fullhd{flex:none;width:unset}.column.is-full-fullhd{flex:none;width:100%}.column.is-three-quarters-fullhd{flex:none;width:75%}.column.is-two-thirds-fullhd{flex:none;width:66.6666%}.column.is-half-fullhd{flex:none;width:50%}.column.is-one-third-fullhd{flex:none;width:33.3333%}.column.is-one-quarter-fullhd{flex:none;width:25%}.column.is-one-fifth-fullhd{flex:none;width:20%}.column.is-two-fifths-fullhd{flex:none;width:40%}.column.is-three-fifths-fullhd{flex:none;width:60%}.column.is-four-fifths-fullhd{flex:none;width:80%}.column.is-offset-three-quarters-fullhd{margin-left:75%}.column.is-offset-two-thirds-fullhd{margin-left:66.6666%}.column.is-offset-half-fullhd{margin-left:50%}.column.is-offset-one-third-fullhd{margin-left:33.3333%}.column.is-offset-one-quarter-fullhd{margin-left:25%}.column.is-offset-one-fifth-fullhd{margin-left:20%}.column.is-offset-two-fifths-fullhd{margin-left:40%}.column.is-offset-three-fifths-fullhd{margin-left:60%}.column.is-offset-four-fifths-fullhd{margin-left:80%}.column.is-0-fullhd{flex:none;width:0%}.column.is-offset-0-fullhd{margin-left:0%}.column.is-1-fullhd{flex:none;width:8.33333337%}.column.is-offset-1-fullhd{margin-left:8.33333337%}.column.is-2-fullhd{flex:none;width:16.66666674%}.column.is-offset-2-fullhd{margin-left:16.66666674%}.column.is-3-fullhd{flex:none;width:25%}.column.is-offset-3-fullhd{margin-left:25%}.column.is-4-fullhd{flex:none;width:33.33333337%}.column.is-offset-4-fullhd{margin-left:33.33333337%}.column.is-5-fullhd{flex:none;width:41.66666674%}.column.is-offset-5-fullhd{margin-left:41.66666674%}.column.is-6-fullhd{flex:none;width:50%}.column.is-offset-6-fullhd{margin-left:50%}.column.is-7-fullhd{flex:none;width:58.33333337%}.column.is-offset-7-fullhd{margin-left:58.33333337%}.column.is-8-fullhd{flex:none;width:66.66666674%}.column.is-offset-8-fullhd{margin-left:66.66666674%}.column.is-9-fullhd{flex:none;width:75%}.column.is-offset-9-fullhd{margin-left:75%}.column.is-10-fullhd{flex:none;width:83.33333337%}.column.is-offset-10-fullhd{margin-left:83.33333337%}.column.is-11-fullhd{flex:none;width:91.66666674%}.column.is-offset-11-fullhd{margin-left:91.66666674%}.column.is-12-fullhd{flex:none;width:100%}.column.is-offset-12-fullhd{margin-left:100%}}.columns{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.columns:last-child{margin-bottom:-.75rem}.columns:not(:last-child){margin-bottom:calc(1.5rem - .75rem)}.columns.is-centered{justify-content:center}.columns.is-gapless{margin-left:0;margin-right:0;margin-top:0}.columns.is-gapless>.column{margin:0;padding:0 !important}.columns.is-gapless:not(:last-child){margin-bottom:1.5rem}.columns.is-gapless:last-child{margin-bottom:0}.columns.is-mobile{display:flex}.columns.is-multiline{flex-wrap:wrap}.columns.is-vcentered{align-items:center}@media screen and (min-width: 769px),print{.columns:not(.is-desktop){display:flex}}@media screen and (min-width: 1056px){.columns.is-desktop{display:flex}}.columns.is-variable{--columnGap: 0.75rem;margin-left:calc(-1 * var(--columnGap));margin-right:calc(-1 * var(--columnGap))}.columns.is-variable>.column{padding-left:var(--columnGap);padding-right:var(--columnGap)}.columns.is-variable.is-0{--columnGap: 0rem}@media screen and (max-width: 768px){.columns.is-variable.is-0-mobile{--columnGap: 0rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-0-tablet{--columnGap: 0rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-0-tablet-only{--columnGap: 0rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-0-touch{--columnGap: 0rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-0-desktop{--columnGap: 0rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-0-desktop-only{--columnGap: 0rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-0-widescreen{--columnGap: 0rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-0-widescreen-only{--columnGap: 0rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-0-fullhd{--columnGap: 0rem}}.columns.is-variable.is-1{--columnGap: .25rem}@media screen and (max-width: 768px){.columns.is-variable.is-1-mobile{--columnGap: .25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-1-tablet{--columnGap: .25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-1-tablet-only{--columnGap: .25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-1-touch{--columnGap: .25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-1-desktop{--columnGap: .25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-1-desktop-only{--columnGap: .25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-1-widescreen{--columnGap: .25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-1-widescreen-only{--columnGap: .25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-1-fullhd{--columnGap: .25rem}}.columns.is-variable.is-2{--columnGap: .5rem}@media screen and (max-width: 768px){.columns.is-variable.is-2-mobile{--columnGap: .5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-2-tablet{--columnGap: .5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-2-tablet-only{--columnGap: .5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-2-touch{--columnGap: .5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-2-desktop{--columnGap: .5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-2-desktop-only{--columnGap: .5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-2-widescreen{--columnGap: .5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-2-widescreen-only{--columnGap: .5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-2-fullhd{--columnGap: .5rem}}.columns.is-variable.is-3{--columnGap: .75rem}@media screen and (max-width: 768px){.columns.is-variable.is-3-mobile{--columnGap: .75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-3-tablet{--columnGap: .75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-3-tablet-only{--columnGap: .75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-3-touch{--columnGap: .75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-3-desktop{--columnGap: .75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-3-desktop-only{--columnGap: .75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-3-widescreen{--columnGap: .75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-3-widescreen-only{--columnGap: .75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-3-fullhd{--columnGap: .75rem}}.columns.is-variable.is-4{--columnGap: 1rem}@media screen and (max-width: 768px){.columns.is-variable.is-4-mobile{--columnGap: 1rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-4-tablet{--columnGap: 1rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-4-tablet-only{--columnGap: 1rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-4-touch{--columnGap: 1rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-4-desktop{--columnGap: 1rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-4-desktop-only{--columnGap: 1rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-4-widescreen{--columnGap: 1rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-4-widescreen-only{--columnGap: 1rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-4-fullhd{--columnGap: 1rem}}.columns.is-variable.is-5{--columnGap: 1.25rem}@media screen and (max-width: 768px){.columns.is-variable.is-5-mobile{--columnGap: 1.25rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-5-tablet{--columnGap: 1.25rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-5-tablet-only{--columnGap: 1.25rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-5-touch{--columnGap: 1.25rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-5-desktop{--columnGap: 1.25rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-5-desktop-only{--columnGap: 1.25rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-5-widescreen{--columnGap: 1.25rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-5-widescreen-only{--columnGap: 1.25rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-5-fullhd{--columnGap: 1.25rem}}.columns.is-variable.is-6{--columnGap: 1.5rem}@media screen and (max-width: 768px){.columns.is-variable.is-6-mobile{--columnGap: 1.5rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-6-tablet{--columnGap: 1.5rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-6-tablet-only{--columnGap: 1.5rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-6-touch{--columnGap: 1.5rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-6-desktop{--columnGap: 1.5rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-6-desktop-only{--columnGap: 1.5rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-6-widescreen{--columnGap: 1.5rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-6-widescreen-only{--columnGap: 1.5rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-6-fullhd{--columnGap: 1.5rem}}.columns.is-variable.is-7{--columnGap: 1.75rem}@media screen and (max-width: 768px){.columns.is-variable.is-7-mobile{--columnGap: 1.75rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-7-tablet{--columnGap: 1.75rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-7-tablet-only{--columnGap: 1.75rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-7-touch{--columnGap: 1.75rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-7-desktop{--columnGap: 1.75rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-7-desktop-only{--columnGap: 1.75rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-7-widescreen{--columnGap: 1.75rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-7-widescreen-only{--columnGap: 1.75rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-7-fullhd{--columnGap: 1.75rem}}.columns.is-variable.is-8{--columnGap: 2rem}@media screen and (max-width: 768px){.columns.is-variable.is-8-mobile{--columnGap: 2rem}}@media screen and (min-width: 769px),print{.columns.is-variable.is-8-tablet{--columnGap: 2rem}}@media screen and (min-width: 769px) and (max-width: 1055px){.columns.is-variable.is-8-tablet-only{--columnGap: 2rem}}@media screen and (max-width: 1055px){.columns.is-variable.is-8-touch{--columnGap: 2rem}}@media screen and (min-width: 1056px){.columns.is-variable.is-8-desktop{--columnGap: 2rem}}@media screen and (min-width: 1056px) and (max-width: 1215px){.columns.is-variable.is-8-desktop-only{--columnGap: 2rem}}@media screen and (min-width: 1216px){.columns.is-variable.is-8-widescreen{--columnGap: 2rem}}@media screen and (min-width: 1216px) and (max-width: 1407px){.columns.is-variable.is-8-widescreen-only{--columnGap: 2rem}}@media screen and (min-width: 1408px){.columns.is-variable.is-8-fullhd{--columnGap: 2rem}}.tile{align-items:stretch;display:block;flex-basis:0;flex-grow:1;flex-shrink:1;min-height:min-content}.tile.is-ancestor{margin-left:-.75rem;margin-right:-.75rem;margin-top:-.75rem}.tile.is-ancestor:last-child{margin-bottom:-.75rem}.tile.is-ancestor:not(:last-child){margin-bottom:.75rem}.tile.is-child{margin:0 !important}.tile.is-parent{padding:.75rem}.tile.is-vertical{flex-direction:column}.tile.is-vertical>.tile.is-child:not(:last-child){margin-bottom:1.5rem !important}@media screen and (min-width: 769px),print{.tile:not(.is-child){display:flex}.tile.is-1{flex:none;width:8.33333337%}.tile.is-2{flex:none;width:16.66666674%}.tile.is-3{flex:none;width:25%}.tile.is-4{flex:none;width:33.33333337%}.tile.is-5{flex:none;width:41.66666674%}.tile.is-6{flex:none;width:50%}.tile.is-7{flex:none;width:58.33333337%}.tile.is-8{flex:none;width:66.66666674%}.tile.is-9{flex:none;width:75%}.tile.is-10{flex:none;width:83.33333337%}.tile.is-11{flex:none;width:91.66666674%}.tile.is-12{flex:none;width:100%}}.hero{align-items:stretch;display:flex;flex-direction:column;justify-content:space-between}.hero .navbar{background:none}.hero .tabs ul{border-bottom:none}.hero.is-white{background-color:#fff;color:#0a0a0a}.hero.is-white a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-white strong{color:inherit}.hero.is-white .title{color:#0a0a0a}.hero.is-white .subtitle{color:rgba(10,10,10,0.9)}.hero.is-white .subtitle a:not(.button),.hero.is-white .subtitle strong{color:#0a0a0a}@media screen and (max-width: 1055px){.hero.is-white .navbar-menu{background-color:#fff}}.hero.is-white .navbar-item,.hero.is-white .navbar-link{color:rgba(10,10,10,0.7)}.hero.is-white a.navbar-item:hover,.hero.is-white a.navbar-item.is-active,.hero.is-white .navbar-link:hover,.hero.is-white .navbar-link.is-active{background-color:#f2f2f2;color:#0a0a0a}.hero.is-white .tabs a{color:#0a0a0a;opacity:0.9}.hero.is-white .tabs a:hover{opacity:1}.hero.is-white .tabs li.is-active a{color:#fff !important;opacity:1}.hero.is-white .tabs.is-boxed a,.hero.is-white .tabs.is-toggle a{color:#0a0a0a}.hero.is-white .tabs.is-boxed a:hover,.hero.is-white .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-white .tabs.is-boxed li.is-active a,.hero.is-white .tabs.is-boxed li.is-active a:hover,.hero.is-white .tabs.is-toggle li.is-active a,.hero.is-white .tabs.is-toggle li.is-active a:hover{background-color:#0a0a0a;border-color:#0a0a0a;color:#fff}.hero.is-white.is-bold{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-white.is-bold .navbar-menu{background-image:linear-gradient(141deg, #e8e3e4 0%, #fff 71%, #fff 100%)}}.hero.is-black{background-color:#0a0a0a;color:#fff}.hero.is-black a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-black strong{color:inherit}.hero.is-black .title{color:#fff}.hero.is-black .subtitle{color:rgba(255,255,255,0.9)}.hero.is-black .subtitle a:not(.button),.hero.is-black .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-black .navbar-menu{background-color:#0a0a0a}}.hero.is-black .navbar-item,.hero.is-black .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-black a.navbar-item:hover,.hero.is-black a.navbar-item.is-active,.hero.is-black .navbar-link:hover,.hero.is-black .navbar-link.is-active{background-color:#000;color:#fff}.hero.is-black .tabs a{color:#fff;opacity:0.9}.hero.is-black .tabs a:hover{opacity:1}.hero.is-black .tabs li.is-active a{color:#0a0a0a !important;opacity:1}.hero.is-black .tabs.is-boxed a,.hero.is-black .tabs.is-toggle a{color:#fff}.hero.is-black .tabs.is-boxed a:hover,.hero.is-black .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-black .tabs.is-boxed li.is-active a,.hero.is-black .tabs.is-boxed li.is-active a:hover,.hero.is-black .tabs.is-toggle li.is-active a,.hero.is-black .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#0a0a0a}.hero.is-black.is-bold{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}@media screen and (max-width: 768px){.hero.is-black.is-bold .navbar-menu{background-image:linear-gradient(141deg, #000 0%, #0a0a0a 71%, #181616 100%)}}.hero.is-light{background-color:#f5f5f5;color:rgba(0,0,0,0.7)}.hero.is-light a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-light strong{color:inherit}.hero.is-light .title{color:rgba(0,0,0,0.7)}.hero.is-light .subtitle{color:rgba(0,0,0,0.9)}.hero.is-light .subtitle a:not(.button),.hero.is-light .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-light .navbar-menu{background-color:#f5f5f5}}.hero.is-light .navbar-item,.hero.is-light .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-light a.navbar-item:hover,.hero.is-light a.navbar-item.is-active,.hero.is-light .navbar-link:hover,.hero.is-light .navbar-link.is-active{background-color:#e8e8e8;color:rgba(0,0,0,0.7)}.hero.is-light .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-light .tabs a:hover{opacity:1}.hero.is-light .tabs li.is-active a{color:#f5f5f5 !important;opacity:1}.hero.is-light .tabs.is-boxed a,.hero.is-light .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-light .tabs.is-boxed a:hover,.hero.is-light .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-light .tabs.is-boxed li.is-active a,.hero.is-light .tabs.is-boxed li.is-active a:hover,.hero.is-light .tabs.is-toggle li.is-active a,.hero.is-light .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#f5f5f5}.hero.is-light.is-bold{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}@media screen and (max-width: 768px){.hero.is-light.is-bold .navbar-menu{background-image:linear-gradient(141deg, #dfd8d9 0%, #f5f5f5 71%, #fff 100%)}}.hero.is-dark,.content kbd.hero{background-color:#363636;color:#fff}.hero.is-dark a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.content kbd.hero a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-dark strong,.content kbd.hero strong{color:inherit}.hero.is-dark .title,.content kbd.hero .title{color:#fff}.hero.is-dark .subtitle,.content kbd.hero .subtitle{color:rgba(255,255,255,0.9)}.hero.is-dark .subtitle a:not(.button),.content kbd.hero .subtitle a:not(.button),.hero.is-dark .subtitle strong,.content kbd.hero .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-dark .navbar-menu,.content kbd.hero .navbar-menu{background-color:#363636}}.hero.is-dark .navbar-item,.content kbd.hero .navbar-item,.hero.is-dark .navbar-link,.content kbd.hero .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-dark a.navbar-item:hover,.content kbd.hero a.navbar-item:hover,.hero.is-dark a.navbar-item.is-active,.content kbd.hero a.navbar-item.is-active,.hero.is-dark .navbar-link:hover,.content kbd.hero .navbar-link:hover,.hero.is-dark .navbar-link.is-active,.content kbd.hero .navbar-link.is-active{background-color:#292929;color:#fff}.hero.is-dark .tabs a,.content kbd.hero .tabs a{color:#fff;opacity:0.9}.hero.is-dark .tabs a:hover,.content kbd.hero .tabs a:hover{opacity:1}.hero.is-dark .tabs li.is-active a,.content kbd.hero .tabs li.is-active a{color:#363636 !important;opacity:1}.hero.is-dark .tabs.is-boxed a,.content kbd.hero .tabs.is-boxed a,.hero.is-dark .tabs.is-toggle a,.content kbd.hero .tabs.is-toggle a{color:#fff}.hero.is-dark .tabs.is-boxed a:hover,.content kbd.hero .tabs.is-boxed a:hover,.hero.is-dark .tabs.is-toggle a:hover,.content kbd.hero .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-dark .tabs.is-boxed li.is-active a,.content kbd.hero .tabs.is-boxed li.is-active a,.hero.is-dark .tabs.is-boxed li.is-active a:hover,.hero.is-dark .tabs.is-toggle li.is-active a,.content kbd.hero .tabs.is-toggle li.is-active a,.hero.is-dark .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#363636}.hero.is-dark.is-bold,.content kbd.hero.is-bold{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}@media screen and (max-width: 768px){.hero.is-dark.is-bold .navbar-menu,.content kbd.hero.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1f191a 0%, #363636 71%, #46403f 100%)}}.hero.is-primary,.docstring>section>a.hero.docs-sourcelink{background-color:#4eb5de;color:#fff}.hero.is-primary a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.docstring>section>a.hero.docs-sourcelink a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-primary strong,.docstring>section>a.hero.docs-sourcelink strong{color:inherit}.hero.is-primary .title,.docstring>section>a.hero.docs-sourcelink .title{color:#fff}.hero.is-primary .subtitle,.docstring>section>a.hero.docs-sourcelink .subtitle{color:rgba(255,255,255,0.9)}.hero.is-primary .subtitle a:not(.button),.docstring>section>a.hero.docs-sourcelink .subtitle a:not(.button),.hero.is-primary .subtitle strong,.docstring>section>a.hero.docs-sourcelink .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-primary .navbar-menu,.docstring>section>a.hero.docs-sourcelink .navbar-menu{background-color:#4eb5de}}.hero.is-primary .navbar-item,.docstring>section>a.hero.docs-sourcelink .navbar-item,.hero.is-primary .navbar-link,.docstring>section>a.hero.docs-sourcelink .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-primary a.navbar-item:hover,.docstring>section>a.hero.docs-sourcelink a.navbar-item:hover,.hero.is-primary a.navbar-item.is-active,.docstring>section>a.hero.docs-sourcelink a.navbar-item.is-active,.hero.is-primary .navbar-link:hover,.docstring>section>a.hero.docs-sourcelink .navbar-link:hover,.hero.is-primary .navbar-link.is-active,.docstring>section>a.hero.docs-sourcelink .navbar-link.is-active{background-color:#39acda;color:#fff}.hero.is-primary .tabs a,.docstring>section>a.hero.docs-sourcelink .tabs a{color:#fff;opacity:0.9}.hero.is-primary .tabs a:hover,.docstring>section>a.hero.docs-sourcelink .tabs a:hover{opacity:1}.hero.is-primary .tabs li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs li.is-active a{color:#4eb5de !important;opacity:1}.hero.is-primary .tabs.is-boxed a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a,.hero.is-primary .tabs.is-toggle a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a{color:#fff}.hero.is-primary .tabs.is-boxed a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed a:hover,.hero.is-primary .tabs.is-toggle a:hover,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-primary .tabs.is-boxed li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-boxed li.is-active a,.hero.is-primary .tabs.is-boxed li.is-active a:hover,.hero.is-primary .tabs.is-toggle li.is-active a,.docstring>section>a.hero.docs-sourcelink .tabs.is-toggle li.is-active a,.hero.is-primary .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#4eb5de}.hero.is-primary.is-bold,.docstring>section>a.hero.is-bold.docs-sourcelink{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}@media screen and (max-width: 768px){.hero.is-primary.is-bold .navbar-menu,.docstring>section>a.hero.is-bold.docs-sourcelink .navbar-menu{background-image:linear-gradient(141deg, #1bc7de 0%, #4eb5de 71%, #5fa9e7 100%)}}.hero.is-link{background-color:#2e63b8;color:#fff}.hero.is-link a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-link strong{color:inherit}.hero.is-link .title{color:#fff}.hero.is-link .subtitle{color:rgba(255,255,255,0.9)}.hero.is-link .subtitle a:not(.button),.hero.is-link .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-link .navbar-menu{background-color:#2e63b8}}.hero.is-link .navbar-item,.hero.is-link .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-link a.navbar-item:hover,.hero.is-link a.navbar-item.is-active,.hero.is-link .navbar-link:hover,.hero.is-link .navbar-link.is-active{background-color:#2958a4;color:#fff}.hero.is-link .tabs a{color:#fff;opacity:0.9}.hero.is-link .tabs a:hover{opacity:1}.hero.is-link .tabs li.is-active a{color:#2e63b8 !important;opacity:1}.hero.is-link .tabs.is-boxed a,.hero.is-link .tabs.is-toggle a{color:#fff}.hero.is-link .tabs.is-boxed a:hover,.hero.is-link .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-link .tabs.is-boxed li.is-active a,.hero.is-link .tabs.is-boxed li.is-active a:hover,.hero.is-link .tabs.is-toggle li.is-active a,.hero.is-link .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#2e63b8}.hero.is-link.is-bold{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}@media screen and (max-width: 768px){.hero.is-link.is-bold .navbar-menu{background-image:linear-gradient(141deg, #1b6098 0%, #2e63b8 71%, #2d51d2 100%)}}.hero.is-info{background-color:#209cee;color:#fff}.hero.is-info a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-info strong{color:inherit}.hero.is-info .title{color:#fff}.hero.is-info .subtitle{color:rgba(255,255,255,0.9)}.hero.is-info .subtitle a:not(.button),.hero.is-info .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-info .navbar-menu{background-color:#209cee}}.hero.is-info .navbar-item,.hero.is-info .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-info a.navbar-item:hover,.hero.is-info a.navbar-item.is-active,.hero.is-info .navbar-link:hover,.hero.is-info .navbar-link.is-active{background-color:#1190e3;color:#fff}.hero.is-info .tabs a{color:#fff;opacity:0.9}.hero.is-info .tabs a:hover{opacity:1}.hero.is-info .tabs li.is-active a{color:#209cee !important;opacity:1}.hero.is-info .tabs.is-boxed a,.hero.is-info .tabs.is-toggle a{color:#fff}.hero.is-info .tabs.is-boxed a:hover,.hero.is-info .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-info .tabs.is-boxed li.is-active a,.hero.is-info .tabs.is-boxed li.is-active a:hover,.hero.is-info .tabs.is-toggle li.is-active a,.hero.is-info .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#209cee}.hero.is-info.is-bold{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}@media screen and (max-width: 768px){.hero.is-info.is-bold .navbar-menu{background-image:linear-gradient(141deg, #05a6d6 0%, #209cee 71%, #3287f5 100%)}}.hero.is-success{background-color:#22c35b;color:#fff}.hero.is-success a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-success strong{color:inherit}.hero.is-success .title{color:#fff}.hero.is-success .subtitle{color:rgba(255,255,255,0.9)}.hero.is-success .subtitle a:not(.button),.hero.is-success .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-success .navbar-menu{background-color:#22c35b}}.hero.is-success .navbar-item,.hero.is-success .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-success a.navbar-item:hover,.hero.is-success a.navbar-item.is-active,.hero.is-success .navbar-link:hover,.hero.is-success .navbar-link.is-active{background-color:#1ead51;color:#fff}.hero.is-success .tabs a{color:#fff;opacity:0.9}.hero.is-success .tabs a:hover{opacity:1}.hero.is-success .tabs li.is-active a{color:#22c35b !important;opacity:1}.hero.is-success .tabs.is-boxed a,.hero.is-success .tabs.is-toggle a{color:#fff}.hero.is-success .tabs.is-boxed a:hover,.hero.is-success .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-success .tabs.is-boxed li.is-active a,.hero.is-success .tabs.is-boxed li.is-active a:hover,.hero.is-success .tabs.is-toggle li.is-active a,.hero.is-success .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#22c35b}.hero.is-success.is-bold{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}@media screen and (max-width: 768px){.hero.is-success.is-bold .navbar-menu{background-image:linear-gradient(141deg, #12a02c 0%, #22c35b 71%, #1fdf83 100%)}}.hero.is-warning{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.hero.is-warning a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-warning strong{color:inherit}.hero.is-warning .title{color:rgba(0,0,0,0.7)}.hero.is-warning .subtitle{color:rgba(0,0,0,0.9)}.hero.is-warning .subtitle a:not(.button),.hero.is-warning .subtitle strong{color:rgba(0,0,0,0.7)}@media screen and (max-width: 1055px){.hero.is-warning .navbar-menu{background-color:#ffdd57}}.hero.is-warning .navbar-item,.hero.is-warning .navbar-link{color:rgba(0,0,0,0.7)}.hero.is-warning a.navbar-item:hover,.hero.is-warning a.navbar-item.is-active,.hero.is-warning .navbar-link:hover,.hero.is-warning .navbar-link.is-active{background-color:#ffd83e;color:rgba(0,0,0,0.7)}.hero.is-warning .tabs a{color:rgba(0,0,0,0.7);opacity:0.9}.hero.is-warning .tabs a:hover{opacity:1}.hero.is-warning .tabs li.is-active a{color:#ffdd57 !important;opacity:1}.hero.is-warning .tabs.is-boxed a,.hero.is-warning .tabs.is-toggle a{color:rgba(0,0,0,0.7)}.hero.is-warning .tabs.is-boxed a:hover,.hero.is-warning .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-warning .tabs.is-boxed li.is-active a,.hero.is-warning .tabs.is-boxed li.is-active a:hover,.hero.is-warning .tabs.is-toggle li.is-active a,.hero.is-warning .tabs.is-toggle li.is-active a:hover{background-color:rgba(0,0,0,0.7);border-color:rgba(0,0,0,0.7);color:#ffdd57}.hero.is-warning.is-bold{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}@media screen and (max-width: 768px){.hero.is-warning.is-bold .navbar-menu{background-image:linear-gradient(141deg, #ffae24 0%, #ffdd57 71%, #fffa71 100%)}}.hero.is-danger{background-color:#da0b00;color:#fff}.hero.is-danger a:not(.button):not(.dropdown-item):not(.tag):not(.pagination-link.is-current),.hero.is-danger strong{color:inherit}.hero.is-danger .title{color:#fff}.hero.is-danger .subtitle{color:rgba(255,255,255,0.9)}.hero.is-danger .subtitle a:not(.button),.hero.is-danger .subtitle strong{color:#fff}@media screen and (max-width: 1055px){.hero.is-danger .navbar-menu{background-color:#da0b00}}.hero.is-danger .navbar-item,.hero.is-danger .navbar-link{color:rgba(255,255,255,0.7)}.hero.is-danger a.navbar-item:hover,.hero.is-danger a.navbar-item.is-active,.hero.is-danger .navbar-link:hover,.hero.is-danger .navbar-link.is-active{background-color:#c10a00;color:#fff}.hero.is-danger .tabs a{color:#fff;opacity:0.9}.hero.is-danger .tabs a:hover{opacity:1}.hero.is-danger .tabs li.is-active a{color:#da0b00 !important;opacity:1}.hero.is-danger .tabs.is-boxed a,.hero.is-danger .tabs.is-toggle a{color:#fff}.hero.is-danger .tabs.is-boxed a:hover,.hero.is-danger .tabs.is-toggle a:hover{background-color:rgba(10,10,10,0.1)}.hero.is-danger .tabs.is-boxed li.is-active a,.hero.is-danger .tabs.is-boxed li.is-active a:hover,.hero.is-danger .tabs.is-toggle li.is-active a,.hero.is-danger .tabs.is-toggle li.is-active a:hover{background-color:#fff;border-color:#fff;color:#da0b00}.hero.is-danger.is-bold{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}@media screen and (max-width: 768px){.hero.is-danger.is-bold .navbar-menu{background-image:linear-gradient(141deg, #a70013 0%, #da0b00 71%, #f43500 100%)}}.hero.is-small .hero-body,#documenter .docs-sidebar form.docs-search>input.hero .hero-body{padding:1.5rem}@media screen and (min-width: 769px),print{.hero.is-medium .hero-body{padding:9rem 4.5rem}}@media screen and (min-width: 769px),print{.hero.is-large .hero-body{padding:18rem 6rem}}.hero.is-halfheight .hero-body,.hero.is-fullheight .hero-body,.hero.is-fullheight-with-navbar .hero-body{align-items:center;display:flex}.hero.is-halfheight .hero-body>.container,.hero.is-fullheight .hero-body>.container,.hero.is-fullheight-with-navbar .hero-body>.container{flex-grow:1;flex-shrink:1}.hero.is-halfheight{min-height:50vh}.hero.is-fullheight{min-height:100vh}.hero-video{overflow:hidden}.hero-video video{left:50%;min-height:100%;min-width:100%;position:absolute;top:50%;transform:translate3d(-50%, -50%, 0)}.hero-video.is-transparent{opacity:0.3}@media screen and (max-width: 768px){.hero-video{display:none}}.hero-buttons{margin-top:1.5rem}@media screen and (max-width: 768px){.hero-buttons .button{display:flex}.hero-buttons .button:not(:last-child){margin-bottom:0.75rem}}@media screen and (min-width: 769px),print{.hero-buttons{display:flex;justify-content:center}.hero-buttons .button:not(:last-child){margin-right:1.5rem}}.hero-head,.hero-foot{flex-grow:0;flex-shrink:0}.hero-body{flex-grow:1;flex-shrink:0;padding:3rem 1.5rem}@media screen and (min-width: 769px),print{.hero-body{padding:3rem 3rem}}.section{padding:3rem 1.5rem}@media screen and (min-width: 1056px){.section{padding:3rem 3rem}.section.is-medium{padding:9rem 4.5rem}.section.is-large{padding:18rem 6rem}}.footer{background-color:#fafafa;padding:3rem 1.5rem 6rem}h1 .docs-heading-anchor,h1 .docs-heading-anchor:hover,h1 .docs-heading-anchor:visited,h2 .docs-heading-anchor,h2 .docs-heading-anchor:hover,h2 .docs-heading-anchor:visited,h3 .docs-heading-anchor,h3 .docs-heading-anchor:hover,h3 .docs-heading-anchor:visited,h4 .docs-heading-anchor,h4 .docs-heading-anchor:hover,h4 .docs-heading-anchor:visited,h5 .docs-heading-anchor,h5 .docs-heading-anchor:hover,h5 .docs-heading-anchor:visited,h6 .docs-heading-anchor,h6 .docs-heading-anchor:hover,h6 .docs-heading-anchor:visited{color:#222}h1 .docs-heading-anchor-permalink,h2 .docs-heading-anchor-permalink,h3 .docs-heading-anchor-permalink,h4 .docs-heading-anchor-permalink,h5 .docs-heading-anchor-permalink,h6 .docs-heading-anchor-permalink{visibility:hidden;vertical-align:middle;margin-left:0.5em;font-size:0.7rem}h1 .docs-heading-anchor-permalink::before,h2 .docs-heading-anchor-permalink::before,h3 .docs-heading-anchor-permalink::before,h4 .docs-heading-anchor-permalink::before,h5 .docs-heading-anchor-permalink::before,h6 .docs-heading-anchor-permalink::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f0c1"}h1:hover .docs-heading-anchor-permalink,h2:hover .docs-heading-anchor-permalink,h3:hover .docs-heading-anchor-permalink,h4:hover .docs-heading-anchor-permalink,h5:hover .docs-heading-anchor-permalink,h6:hover .docs-heading-anchor-permalink{visibility:visible}.docs-dark-only{display:none !important}pre{position:relative;overflow:hidden}pre code,pre code.hljs{padding:0 .75rem !important;overflow:auto;display:block}pre code:first-of-type,pre code.hljs:first-of-type{padding-top:0.5rem !important}pre code:last-of-type,pre code.hljs:last-of-type{padding-bottom:0.5rem !important}pre .copy-button{opacity:0.2;transition:opacity 0.2s;position:absolute;right:0em;top:0em;padding:0.5em;width:2.5em;height:2.5em;background:transparent;border:none;font-family:"Font Awesome 6 Free";color:#222;cursor:pointer;text-align:center}pre .copy-button:focus,pre .copy-button:hover{opacity:1;background:rgba(34,34,34,0.1);color:#2e63b8}pre .copy-button.success{color:#259a12;opacity:1}pre .copy-button.error{color:#cb3c33;opacity:1}pre:hover .copy-button{opacity:1}.admonition{background-color:#b5b5b5;border-style:solid;border-width:1px;border-color:#363636;border-radius:4px;font-size:1rem}.admonition strong{color:currentColor}.admonition.is-small,#documenter .docs-sidebar form.docs-search>input.admonition{font-size:.75rem}.admonition.is-medium{font-size:1.25rem}.admonition.is-large{font-size:1.5rem}.admonition.is-default{background-color:#b5b5b5;border-color:#363636}.admonition.is-default>.admonition-header{background-color:#363636;color:#fff}.admonition.is-default>.admonition-body{color:#fff}.admonition.is-info{background-color:#def0fc;border-color:#209cee}.admonition.is-info>.admonition-header{background-color:#209cee;color:#fff}.admonition.is-info>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-success{background-color:#bdf4d1;border-color:#22c35b}.admonition.is-success>.admonition-header{background-color:#22c35b;color:#fff}.admonition.is-success>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-warning{background-color:#fff3c5;border-color:#ffdd57}.admonition.is-warning>.admonition-header{background-color:#ffdd57;color:rgba(0,0,0,0.7)}.admonition.is-warning>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-danger{background-color:#ffaba7;border-color:#da0b00}.admonition.is-danger>.admonition-header{background-color:#da0b00;color:#fff}.admonition.is-danger>.admonition-body{color:rgba(0,0,0,0.7)}.admonition.is-compat{background-color:#bdeff5;border-color:#1db5c9}.admonition.is-compat>.admonition-header{background-color:#1db5c9;color:#fff}.admonition.is-compat>.admonition-body{color:rgba(0,0,0,0.7)}.admonition-header{color:#fff;background-color:#363636;align-items:center;font-weight:700;justify-content:space-between;line-height:1.25;padding:0.5rem .75rem;position:relative}.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;margin-right:.75rem;content:"\f06a"}details.admonition.is-details>.admonition-header{list-style:none}details.admonition.is-details>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f055"}details.admonition.is-details[open]>.admonition-header:before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f056"}.admonition-body{color:#222;padding:0.5rem .75rem}.admonition-body pre{background-color:#f5f5f5}.admonition-body code{background-color:rgba(0,0,0,0.05)}.docstring{margin-bottom:1em;background-color:rgba(0,0,0,0);border:1px solid #dbdbdb;box-shadow:2px 2px 3px rgba(10,10,10,0.1);max-width:100%}.docstring>header{cursor:pointer;display:flex;flex-grow:1;align-items:stretch;padding:0.5rem .75rem;background-color:#f5f5f5;box-shadow:0 0.125em 0.25em rgba(10,10,10,0.1);box-shadow:none;border-bottom:1px solid #dbdbdb;overflow:auto}.docstring>header code{background-color:transparent}.docstring>header .docstring-article-toggle-button{min-width:1.1rem;padding:0.2rem 0.2rem 0.2rem 0}.docstring>header .docstring-binding{margin-right:0.3em}.docstring>header .docstring-category{margin-left:0.3em}.docstring>section{position:relative;padding:.75rem .75rem;border-bottom:1px solid #dbdbdb}.docstring>section:last-child{border-bottom:none}.docstring>section>a.docs-sourcelink{transition:opacity 0.3s;opacity:0;position:absolute;right:.375rem;bottom:.375rem}.docstring>section>a.docs-sourcelink:focus{opacity:1 !important}.docstring:hover>section>a.docs-sourcelink{opacity:0.2}.docstring:focus-within>section>a.docs-sourcelink{opacity:0.2}.docstring>section:hover a.docs-sourcelink{opacity:1}.documenter-example-output{background-color:#fff}.outdated-warning-overlay{position:fixed;top:0;left:0;right:0;box-shadow:0 0 10px rgba(0,0,0,0.3);z-index:999;background-color:#ffaba7;color:rgba(0,0,0,0.7);border-bottom:3px solid #da0b00;padding:10px 35px;text-align:center;font-size:15px}.outdated-warning-overlay .outdated-warning-closer{position:absolute;top:calc(50% - 10px);right:18px;cursor:pointer;width:12px}.outdated-warning-overlay a{color:#2e63b8}.outdated-warning-overlay a:hover{color:#363636}.content pre{border:1px solid #dbdbdb}.content code{font-weight:inherit}.content a code{color:#2e63b8}.content h1 code,.content h2 code,.content h3 code,.content h4 code,.content h5 code,.content h6 code{color:#222}.content table{display:block;width:initial;max-width:100%;overflow-x:auto}.content blockquote>ul:first-child,.content blockquote>ol:first-child,.content .admonition-body>ul:first-child,.content .admonition-body>ol:first-child{margin-top:0}pre,code{font-variant-ligatures:no-contextual}.breadcrumb a.is-disabled{cursor:default;pointer-events:none}.breadcrumb a.is-disabled,.breadcrumb a.is-disabled:hover{color:#222}.hljs{background:initial !important}.katex .katex-mathml{top:0;right:0}.katex-display,mjx-container,.MathJax_Display{margin:0.5em 0 !important}html{-moz-osx-font-smoothing:auto;-webkit-font-smoothing:auto}li.no-marker{list-style:none}#documenter .docs-main>article{overflow-wrap:break-word}#documenter .docs-main>article .math-container{overflow-x:auto;overflow-y:hidden}@media screen and (min-width: 1056px){#documenter .docs-main{max-width:52rem;margin-left:20rem;padding-right:1rem}}@media screen and (max-width: 1055px){#documenter .docs-main{width:100%}#documenter .docs-main>article{max-width:52rem;margin-left:auto;margin-right:auto;margin-bottom:1rem;padding:0 1rem}#documenter .docs-main>header,#documenter .docs-main>nav{max-width:100%;width:100%;margin:0}}#documenter .docs-main header.docs-navbar{background-color:#fff;border-bottom:1px solid #dbdbdb;z-index:2;min-height:4rem;margin-bottom:1rem;display:flex}#documenter .docs-main header.docs-navbar .breadcrumb{flex-grow:1;overflow-x:hidden}#documenter .docs-main header.docs-navbar .docs-sidebar-button{display:block;font-size:1.5rem;padding-bottom:0.1rem;margin-right:1rem}#documenter .docs-main header.docs-navbar .docs-right{display:flex;white-space:nowrap;gap:1rem;align-items:center}#documenter .docs-main header.docs-navbar .docs-right .docs-icon,#documenter .docs-main header.docs-navbar .docs-right .docs-label{display:inline-block}#documenter .docs-main header.docs-navbar .docs-right .docs-label{padding:0;margin-left:0.3em}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar .docs-right .docs-navbar-link{margin-left:0.4rem;margin-right:0.4rem}}#documenter .docs-main header.docs-navbar>*{margin:auto 0}@media screen and (max-width: 1055px){#documenter .docs-main header.docs-navbar{position:sticky;top:0;padding:0 1rem;transition-property:top, box-shadow;-webkit-transition-property:top, box-shadow;transition-duration:0.3s;-webkit-transition-duration:0.3s}#documenter .docs-main header.docs-navbar.headroom--not-top{box-shadow:.2rem 0rem .4rem #bbb;transition-duration:0.7s;-webkit-transition-duration:0.7s}#documenter .docs-main header.docs-navbar.headroom--unpinned.headroom--not-top.headroom--not-bottom{top:-4.5rem;transition-duration:0.7s;-webkit-transition-duration:0.7s}}#documenter .docs-main section.footnotes{border-top:1px solid #dbdbdb}#documenter .docs-main section.footnotes li .tag:first-child,#documenter .docs-main section.footnotes li .docstring>section>a.docs-sourcelink:first-child,#documenter .docs-main section.footnotes li .content kbd:first-child,.content #documenter .docs-main section.footnotes li kbd:first-child{margin-right:1em;margin-bottom:0.4em}#documenter .docs-main .docs-footer{display:flex;flex-wrap:wrap;margin-left:0;margin-right:0;border-top:1px solid #dbdbdb;padding-top:1rem;padding-bottom:1rem}@media screen and (max-width: 1055px){#documenter .docs-main .docs-footer{padding-left:1rem;padding-right:1rem}}#documenter .docs-main .docs-footer .docs-footer-nextpage,#documenter .docs-main .docs-footer .docs-footer-prevpage{flex-grow:1}#documenter .docs-main .docs-footer .docs-footer-nextpage{text-align:right}#documenter .docs-main .docs-footer .flexbox-break{flex-basis:100%;height:0}#documenter .docs-main .docs-footer .footer-message{font-size:0.8em;margin:0.5em auto 0 auto;text-align:center}#documenter .docs-sidebar{display:flex;flex-direction:column;color:#0a0a0a;background-color:#f5f5f5;border-right:1px solid #dbdbdb;padding:0;flex:0 0 18rem;z-index:5;font-size:1rem;position:fixed;left:-18rem;width:18rem;height:100%;transition:left 0.3s}#documenter .docs-sidebar.visible{left:0;box-shadow:.4rem 0rem .8rem #bbb}@media screen and (min-width: 1056px){#documenter .docs-sidebar.visible{box-shadow:none}}@media screen and (min-width: 1056px){#documenter .docs-sidebar{left:0;top:0}}#documenter .docs-sidebar .docs-logo{margin-top:1rem;padding:0 1rem}#documenter .docs-sidebar .docs-logo>img{max-height:6rem;margin:auto}#documenter .docs-sidebar .docs-package-name{flex-shrink:0;font-size:1.5rem;font-weight:700;text-align:center;white-space:nowrap;overflow:hidden;padding:0.5rem 0}#documenter .docs-sidebar .docs-package-name .docs-autofit{max-width:16.2rem}#documenter .docs-sidebar .docs-package-name a,#documenter .docs-sidebar .docs-package-name a:hover{color:#0a0a0a}#documenter .docs-sidebar .docs-version-selector{border-top:1px solid #dbdbdb;display:none;padding:0.5rem}#documenter .docs-sidebar .docs-version-selector.visible{display:flex}#documenter .docs-sidebar ul.docs-menu{flex-grow:1;user-select:none;border-top:1px solid #dbdbdb;padding-bottom:1.5rem}#documenter .docs-sidebar ul.docs-menu>li>.tocitem{font-weight:bold}#documenter .docs-sidebar ul.docs-menu>li li{font-size:.95rem;margin-left:1em;border-left:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu input.collapse-toggle{display:none}#documenter .docs-sidebar ul.docs-menu ul.collapsed{display:none}#documenter .docs-sidebar ul.docs-menu input:checked~ul.collapsed{display:block}#documenter .docs-sidebar ul.docs-menu label.tocitem{display:flex}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-label{flex-grow:2}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron{display:inline-block;font-style:normal;font-variant:normal;text-rendering:auto;line-height:1;font-size:.75rem;margin-left:1rem;margin-top:auto;margin-bottom:auto}#documenter .docs-sidebar ul.docs-menu label.tocitem .docs-chevron::before{font-family:"Font Awesome 6 Free";font-weight:900;content:"\f054"}#documenter .docs-sidebar ul.docs-menu input:checked~label.tocitem .docs-chevron::before{content:"\f078"}#documenter .docs-sidebar ul.docs-menu .tocitem{display:block;padding:0.5rem 0.5rem}#documenter .docs-sidebar ul.docs-menu .tocitem,#documenter .docs-sidebar ul.docs-menu .tocitem:hover{color:#0a0a0a;background:#f5f5f5}#documenter .docs-sidebar ul.docs-menu a.tocitem:hover,#documenter .docs-sidebar ul.docs-menu label.tocitem:hover{color:#0a0a0a;background-color:#ebebeb}#documenter .docs-sidebar ul.docs-menu li.is-active{border-top:1px solid #dbdbdb;border-bottom:1px solid #dbdbdb;background-color:#fff}#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem,#documenter .docs-sidebar ul.docs-menu li.is-active .tocitem:hover{background-color:#fff;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu li.is-active ul.internal .tocitem:hover{background-color:#ebebeb;color:#0a0a0a}#documenter .docs-sidebar ul.docs-menu>li.is-active:first-child{border-top:none}#documenter .docs-sidebar ul.docs-menu ul.internal{margin:0 0.5rem 0.5rem;border-top:1px solid #dbdbdb}#documenter .docs-sidebar ul.docs-menu ul.internal li{font-size:.85rem;border-left:none;margin-left:0;margin-top:0.5rem}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem{width:100%;padding:0}#documenter .docs-sidebar ul.docs-menu ul.internal .tocitem::before{content:"⚬";margin-right:0.4em}#documenter .docs-sidebar form.docs-search{margin:auto;margin-top:0.5rem;margin-bottom:0.5rem}#documenter .docs-sidebar form.docs-search>input{width:14.4rem}#documenter .docs-sidebar #documenter-search-query{color:#707070;width:14.4rem;box-shadow:inset 0 1px 2px rgba(10,10,10,0.1)}@media screen and (min-width: 1056px){#documenter .docs-sidebar ul.docs-menu{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar ul.docs-menu::-webkit-scrollbar-thumb:hover{background:#ccc}}@media screen and (max-width: 1055px){#documenter .docs-sidebar{overflow-y:auto;-webkit-overflow-scroll:touch}#documenter .docs-sidebar::-webkit-scrollbar{width:.3rem;background:none}#documenter .docs-sidebar::-webkit-scrollbar-thumb{border-radius:5px 0px 0px 5px;background:#e0e0e0}#documenter .docs-sidebar::-webkit-scrollbar-thumb:hover{background:#ccc}}kbd.search-modal-key-hints{border-radius:0.25rem;border:1px solid rgba(0,0,0,0.6);box-shadow:0 2px 0 1px rgba(0,0,0,0.6);cursor:default;font-size:0.9rem;line-height:1.5;min-width:0.75rem;text-align:center;padding:0.1rem 0.3rem;position:relative;top:-1px}.search-min-width-50{min-width:50%}.search-min-height-100{min-height:100%}.search-modal-card-body{max-height:calc(100vh - 15rem)}.search-result-link{border-radius:0.7em;transition:all 300ms}.search-result-link:hover,.search-result-link:focus{background-color:rgba(0,128,128,0.1)}.search-result-link .property-search-result-badge,.search-result-link .search-filter{transition:all 300ms}.property-search-result-badge,.search-filter{padding:0.15em 0.5em;font-size:0.8em;font-style:italic;text-transform:none !important;line-height:1.5;color:#f5f5f5;background-color:rgba(51,65,85,0.501961);border-radius:0.6rem}.search-result-link:hover .property-search-result-badge,.search-result-link:hover .search-filter,.search-result-link:focus .property-search-result-badge,.search-result-link:focus .search-filter{color:#f1f5f9;background-color:#333}.search-filter{color:#333;background-color:#f5f5f5;transition:all 300ms}.search-filter:hover,.search-filter:focus{color:#333}.search-filter-selected{color:#f5f5f5;background-color:rgba(139,0,139,0.5)}.search-filter-selected:hover,.search-filter-selected:focus{color:#f5f5f5}.search-result-highlight{background-color:#ffdd57;color:black}.search-divider{border-bottom:1px solid #dbdbdb}.search-result-title{width:85%;color:#333}.search-result-code-title{font-size:0.875rem;font-family:"JuliaMono","SFMono-Regular","Menlo","Consolas","Liberation Mono","DejaVu Sans Mono",monospace}#search-modal .modal-card-body::-webkit-scrollbar,#search-modal .filter-tabs::-webkit-scrollbar{height:10px;width:10px;background-color:transparent}#search-modal .modal-card-body::-webkit-scrollbar-thumb,#search-modal .filter-tabs::-webkit-scrollbar-thumb{background-color:gray;border-radius:1rem}#search-modal .modal-card-body::-webkit-scrollbar-track,#search-modal .filter-tabs::-webkit-scrollbar-track{-webkit-box-shadow:inset 0 0 6px rgba(0,0,0,0.6);background-color:transparent}.w-100{width:100%}.gap-2{gap:0.5rem}.gap-4{gap:1rem}.gap-8{gap:2rem}.ansi span.sgr1{font-weight:bolder}.ansi span.sgr2{font-weight:lighter}.ansi span.sgr3{font-style:italic}.ansi span.sgr4{text-decoration:underline}.ansi span.sgr7{color:#fff;background-color:#222}.ansi span.sgr8{color:transparent}.ansi span.sgr8 span{color:transparent}.ansi span.sgr9{text-decoration:line-through}.ansi span.sgr30{color:#242424}.ansi span.sgr31{color:#a7201f}.ansi span.sgr32{color:#066f00}.ansi span.sgr33{color:#856b00}.ansi span.sgr34{color:#2149b0}.ansi span.sgr35{color:#7d4498}.ansi span.sgr36{color:#007989}.ansi span.sgr37{color:gray}.ansi span.sgr40{background-color:#242424}.ansi span.sgr41{background-color:#a7201f}.ansi span.sgr42{background-color:#066f00}.ansi span.sgr43{background-color:#856b00}.ansi span.sgr44{background-color:#2149b0}.ansi span.sgr45{background-color:#7d4498}.ansi span.sgr46{background-color:#007989}.ansi span.sgr47{background-color:gray}.ansi span.sgr90{color:#616161}.ansi span.sgr91{color:#cb3c33}.ansi span.sgr92{color:#0e8300}.ansi span.sgr93{color:#a98800}.ansi span.sgr94{color:#3c5dcd}.ansi span.sgr95{color:#9256af}.ansi span.sgr96{color:#008fa3}.ansi span.sgr97{color:#f5f5f5}.ansi span.sgr100{background-color:#616161}.ansi span.sgr101{background-color:#cb3c33}.ansi span.sgr102{background-color:#0e8300}.ansi span.sgr103{background-color:#a98800}.ansi span.sgr104{background-color:#3c5dcd}.ansi span.sgr105{background-color:#9256af}.ansi span.sgr106{background-color:#008fa3}.ansi span.sgr107{background-color:#f5f5f5}code.language-julia-repl>span.hljs-meta{color:#066f00;font-weight:bolder}/*! + Theme: Default + Description: Original highlight.js style + Author: (c) Ivan Sagalaev + Maintainer: @highlightjs/core-team + Website: https://highlightjs.org/ + License: see project LICENSE + Touched: 2021 +*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{background:#F3F3F3;color:#444}.hljs-comment{color:#697070}.hljs-tag,.hljs-punctuation{color:#444a}.hljs-tag .hljs-name,.hljs-tag .hljs-attr{color:#444}.hljs-keyword,.hljs-attribute,.hljs-selector-tag,.hljs-meta .hljs-keyword,.hljs-doctag,.hljs-name{font-weight:bold}.hljs-type,.hljs-string,.hljs-number,.hljs-selector-id,.hljs-selector-class,.hljs-quote,.hljs-template-tag,.hljs-deletion{color:#880000}.hljs-title,.hljs-section{color:#880000;font-weight:bold}.hljs-regexp,.hljs-symbol,.hljs-variable,.hljs-template-variable,.hljs-link,.hljs-selector-attr,.hljs-operator,.hljs-selector-pseudo{color:#ab5656}.hljs-literal{color:#695}.hljs-built_in,.hljs-bullet,.hljs-code,.hljs-addition{color:#397300}.hljs-meta{color:#1f7199}.hljs-meta .hljs-string{color:#38a}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:bold}.gap-4{gap:1rem} diff --git a/v2.16.2/assets/themeswap.js b/v2.16.2/assets/themeswap.js new file mode 100644 index 000000000..9f5eebe6a --- /dev/null +++ b/v2.16.2/assets/themeswap.js @@ -0,0 +1,84 @@ +// Small function to quickly swap out themes. Gets put into the tag.. +function set_theme_from_local_storage() { + // Initialize the theme to null, which means default + var theme = null; + // If the browser supports the localstorage and is not disabled then try to get the + // documenter theme + if (window.localStorage != null) { + // Get the user-picked theme from localStorage. May be `null`, which means the default + // theme. + theme = window.localStorage.getItem("documenter-theme"); + } + // Check if the users preference is for dark color scheme + var darkPreference = + window.matchMedia("(prefers-color-scheme: dark)").matches === true; + // Initialize a few variables for the loop: + // + // - active: will contain the index of the theme that should be active. Note that there + // is no guarantee that localStorage contains sane values. If `active` stays `null` + // we either could not find the theme or it is the default (primary) theme anyway. + // Either way, we then need to stick to the primary theme. + // + // - disabled: style sheets that should be disabled (i.e. all the theme style sheets + // that are not the currently active theme) + var active = null; + var disabled = []; + var primaryLightTheme = null; + var primaryDarkTheme = null; + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // To distinguish the default (primary) theme, it needs to have the data-theme-primary + // attribute set. + if (ss.ownerNode.getAttribute("data-theme-primary") !== null) { + primaryLightTheme = themename; + } + // Check if the theme is primary dark theme so that we could store its name in darkTheme + if (ss.ownerNode.getAttribute("data-theme-primary-dark") !== null) { + primaryDarkTheme = themename; + } + // If we find a matching theme (and it's not the default), we'll set active to non-null + if (themename === theme) active = i; + // Store the style sheets of inactive themes so that we could disable them + if (themename !== theme) disabled.push(ss); + } + var activeTheme = null; + if (active !== null) { + // If we did find an active theme, we'll (1) add the theme--$(theme) class to + document.getElementsByTagName("html")[0].className = "theme--" + theme; + activeTheme = theme; + } else { + // If we did _not_ find an active theme, then we need to fall back to the primary theme + // which can either be dark or light, depending on the user's OS preference. + var activeTheme = darkPreference ? primaryDarkTheme : primaryLightTheme; + // In case it somehow happens that the relevant primary theme was not found in the + // preceding loop, we abort without doing anything. + if (activeTheme === null) { + console.error("Unable to determine primary theme."); + return; + } + // When switching to the primary light theme, then we must not have a class name + // for the tag. That's only for non-primary or the primary dark theme. + if (darkPreference) { + document.getElementsByTagName("html")[0].className = + "theme--" + activeTheme; + } else { + document.getElementsByTagName("html")[0].className = ""; + } + } + for (var i = 0; i < document.styleSheets.length; i++) { + var ss = document.styleSheets[i]; + // The tag of each style sheet is expected to have a data-theme-name attribute + // which must contain the name of the theme. The names in localStorage much match this. + var themename = ss.ownerNode.getAttribute("data-theme-name"); + // attribute not set => non-theme stylesheet => ignore + if (themename === null) continue; + // we'll disable all the stylesheets, except for the active one + ss.disabled = !(themename == activeTheme); + } +} +set_theme_from_local_storage(); diff --git a/v2.16.2/assets/warner.js b/v2.16.2/assets/warner.js new file mode 100644 index 000000000..3f6f5d008 --- /dev/null +++ b/v2.16.2/assets/warner.js @@ -0,0 +1,52 @@ +function maybeAddWarning() { + // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE + // in siteinfo.js. + // If either of these are undefined something went horribly wrong, so we abort. + if ( + window.DOCUMENTER_NEWEST === undefined || + window.DOCUMENTER_CURRENT_VERSION === undefined || + window.DOCUMENTER_STABLE === undefined + ) { + return; + } + + // Current version is not a version number, so we can't tell if it's the newest version. Abort. + if (!/v(\d+\.)*\d+/.test(window.DOCUMENTER_CURRENT_VERSION)) { + return; + } + + // Current version is newest version, so no need to add a warning. + if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) { + return; + } + + // Add a noindex meta tag (unless one exists) so that search engines don't index this version of the docs. + if (document.body.querySelector('meta[name="robots"]') === null) { + const meta = document.createElement("meta"); + meta.name = "robots"; + meta.content = "noindex"; + + document.getElementsByTagName("head")[0].appendChild(meta); + } + + const div = document.createElement("div"); + div.classList.add("outdated-warning-overlay"); + const closer = document.createElement("button"); + closer.classList.add("outdated-warning-closer", "delete"); + closer.addEventListener("click", function () { + document.body.removeChild(div); + }); + const href = window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE; + div.innerHTML = + 'This documentation is not for the latest stable release, but for either the development version or an older release.
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/v2.16.2/contributing/new-documentation/index.html b/v2.16.2/contributing/new-documentation/index.html new file mode 100644 index 000000000..6a13d8921 --- /dev/null +++ b/v2.16.2/contributing/new-documentation/index.html @@ -0,0 +1,2 @@ + +Contributing to the documentation · RxInfer.jl
GitHub

Contributing to the documentation

Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:

  1. Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.

  2. Identify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.

  3. Fork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.

  4. Make Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.

  5. Submit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.

  6. Review and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.

  7. Merging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!

By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.

Use LiveServer.jl

LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.

To use LiveServer.jl, simply follow these steps[1]

  • Make sure to import the required packages 
julia> using LiveServer, Documenter
  • After importing the required packages, you can start the live server with the following command:
julia> servedocs()
  • 1Make sure to install the LiveServer and Documenter in your current working environment.
diff --git a/v2.16.2/contributing/new-example/index.html b/v2.16.2/contributing/new-example/index.html new file mode 100644 index 000000000..01f32c2fd --- /dev/null +++ b/v2.16.2/contributing/new-example/index.html @@ -0,0 +1,7 @@ + +Contributing to the examples · RxInfer.jl
GitHub

Contributing to the examples

We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.

In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/"subcategory" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.

After preparing the new example it is necessary to modify the examples/.meta.jl file.

  1. Make sure that the very first cell of the notebook contains ONLY # <title> in it and has the markdown cell type. This is important for generating links in our documentation.
  2. The path option must be set to a local path in a category sub-folder.
  3. The text in the description option will be used on the Examples page in the documentation.
  4. Set category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).
  5. Please do no use Overview as a name for the new example, the title Overview is reserved.
  6. Use the following template for equations, note that $$ and both \begin and \end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.
$$\begin{aligned}
+      <latex equations here>
+\end{aligned}$$
  1. When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.
  2. Notebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.
variable = 0
+for i in 1:10
+    global variable = variable + i
+end
  1. All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.
  2. All plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.
Note

Please avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.

Note

Use make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.

diff --git a/v2.16.2/contributing/new-package/index.html b/v2.16.2/contributing/new-package/index.html new file mode 100644 index 000000000..f7fef2a09 --- /dev/null +++ b/v2.16.2/contributing/new-package/index.html @@ -0,0 +1,28 @@ + +Contributing to the dependencies · RxInfer.jl
GitHub

Contributing to the dependencies

Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.

The benefits of small packages for the ecosystem

In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:

  1. Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.

  2. Collaboration: Teams can work on different packages concurrently, speeding up development.

  3. Version Control: Precise versioning and fewer dependencies lead to leaner projects.

  4. Performance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.

  5. Flexibility: Developers can select and customize packages for their needs.

  6. Community: Smaller packages attract contributors, fostering collaboration and faster feedback.

In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.

Use PkgTemplates

PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:

julia> using PkgTemplates
+
+julia> USER = "your github user name" # Use `reactivebayes` if developing within the ReactiveBayes organisation
+
+julia> template = Template(
+    user = USER, 
+    plugins = [
+        CompatHelper(), 
+        ProjectFile(), 
+        SrcDir(), 
+        Git(), 
+        License(), 
+        Readme(), 
+        Tests(), 
+        GitHubActions(), 
+        Codecov(), 
+        Documenter{GitHubActions}(), 
+        Formatter(style="blue"), 
+        BlueStyleBadge(), 
+        PkgEvalBadge()
+])
+
+julia> template("MyNewCoolPackage")

This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.

  • Adjust the minimum supported version of Julia

After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:

[compat]
+julia = "1.9.2"

Try to be conservative and set as low version of Julia as possible.

  • Adjust the authors of the package

The authors field is present in the Project.toml, e.g 

authors = ["John Wick <john.wick@continental.com>", ...]

  • Add requires dependencies and their [compat] bounds

To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:

julia --project=.

or 

julia
julia> ] activate .

Then, add dependencies like this:

julia> ] add SomeCoolDependency, SomeOtherCoolDependency

For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:

[compat]
+julia = "1.9"
+SomeCoolDependency = "0.19.2"
+SomeOtherCoolDependency = "1.3.12"

For more details on compat bounds, check the official Julia documentation.

Adjust README.md

The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.

Note

Some badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.

Write code and tests

The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.

Simplify Testing with ReTestItems

You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.

Write code and the documentation

Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):

julia --project=docs docs/make.jl

For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.

Hosting Documentation with GitHub Actions

The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.

Enable GitHub Pages in Repository Settings

The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:

  1. Navigate to the GitHub Pages settings of your repository.
  2. Choose the Deploy from a branch option.
  3. Select the gh-pages branch.
diff --git a/v2.16.2/contributing/new-release/index.html b/v2.16.2/contributing/new-release/index.html new file mode 100644 index 000000000..08effbad4 --- /dev/null +++ b/v2.16.2/contributing/new-release/index.html @@ -0,0 +1,2 @@ + +Publishing a new release · RxInfer.jl
GitHub

Publishing a new release

Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.

Start the release process

In order to start the release process a person with the associated permissions should:

  • Open a commit page on GitHub
  • Write the @JuliaRegistrator register comment for the commit:

Release comment

The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.

diff --git a/v2.16.2/contributing/overview/index.html b/v2.16.2/contributing/overview/index.html new file mode 100644 index 000000000..0a394e7b8 --- /dev/null +++ b/v2.16.2/contributing/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Contributing

We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.

Reporting bugs

We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.

Nightly Julia status

The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.

PkgEval

Suggesting features

We welcome new feature proposals. However, before submitting a feature request, consider a few things:

  • Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.
  • If you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.

Contributing code

Installing RxInfer

We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:

] dev git@github.com:your_username/RxInfer.jl.git

The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.

Note

It is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.

Core dependencies

RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.

Committing code

We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.

Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well.

Note

Use make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.

Style conventions

We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:

  • Use 4 spaces for indentation
  • Type names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..
  • Function names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..
  • Variable names and function arguments use snake_case
  • The name of a method that modifies its argument(s) must end in !
Note

RxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.

Unit tests

We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.

All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.

The tests can be evaluated by running following command in the Julia REPL:

] test RxInfer

In addition tests can be evaluated by running following command in the RxInfer root directory:

make test
Note

Use make devtest to use local dev-ed versions of the core packages.

Makefile

RxInfer.jl uses Makefile for most common operations:

  • make help: Shows help snippet
  • make test: Run tests, supports extra arguments
    • make test test_args="distributions:normal_mean_variance" would run tests only from distributions/test_normal_mean_variance.jl
    • make test test_args="distributions:normal_mean_variance models:lgssm" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl
    • make test dev=true would run tests while using dev-ed versions of core packages
  • make devtest: Alias for the make test dev=true ...
  • make docs: Compile documentation
  • make devdocs: Same as make docs, but uses dev-ed versions of core packages
  • make examples: Run all examples and put them in the docs/ folder if successfull
  • make devexamples: Same as make examples, but uses dev-ed versions of core packages
  • make lint: Check codestyle
  • make format: Check and fix codestyle
Note

Core packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.

diff --git a/v2.16.2/examples/advanced_examples/Active Inference Mountain car/index.html b/v2.16.2/examples/advanced_examples/Active Inference Mountain car/index.html new file mode 100644 index 000000000..582b68c2b --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Active Inference Mountain car/index.html @@ -0,0 +1,286 @@ + +Active Inference Mountain car · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Active Inference Mountain car

import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.

The environmental process of the mountain

Firstly, we specify the environmental process according to Ueltzhoeffer (2017) "Deep active inference". This process shows how the environment evolves after interacting with the agent.

Particularly, let's denote $z_t = (\phi_t, \,\,\dot{\phi_t})$ as the environmental state depending on the position $\phi_t$ and velocity $\dot{\phi_t}$ of the car; $a_t$ as the action of the environment on the car. Then the evolution of the state is described as follows

\[\begin{aligned} +\dot{\phi_t} &= \dot{\phi}_{t-1} + F_g(\phi_{t-1}) + F_f(\dot{\phi}_{t-1}) + F_a(a_t)\\ +\phi_t &= \phi_{t-1} + \dot{\phi_t} +\end{aligned}\]

where $F_g(\phi_{t-1})$ is the gravitational force of the hill landscape that depends on the car's position

\[F_g(\phi) = \begin{cases} + -0.05(2\phi + 1) , \, & \mathrm{if} \, \phi < 0 \\ + -0.05 \left[(1 + 5\phi^2)^{-\frac{1}{2}} + \phi^2 (1 + 5\phi^2)^{-\frac{3}{2}} + \frac{1}{16}\phi^4 \right], \, & \mathrm{otherwise} +\end{cases}\]

\[F_f(\dot{\phi})\]

is the friction on the car defined through the car's velocity $F_f(\dot{\phi}) = -0.1 \, \dot{\phi}\,$ and $F_a(a)$ is the engine force $F_a(a) = 0.04 \,\tanh(a).$ Since the car is on low battery, we use the $\tanh(\cdot)$ function to limit the engine force to the interval [-0.04, 0.04].

In the cell below, the create_physics function defines forces $F_g,\, F_f,\, F_a\,$; and the create_world function defines the environmental process of the mountain.

import HypergeometricFunctions: _₂F₁
+
+function create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)
+    # Engine force as function of action
+    Fa = (a::Real) -> engine_force_limit * tanh(a) 
+
+    # Friction force as function of velocity
+    Ff = (y_dot::Real) -> -friction_coefficient * y_dot 
+    
+    # Gravitational force (horizontal component) as function of position
+    Fg = (y::Real) -> begin
+        if y < 0
+            0.05*(-2*y - 1)
+        else
+            0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)
+        end
+    end
+    
+    # The height of the landscape as a function of the horizontal coordinate
+    height = (x::Float64) -> begin
+        if x < 0
+            h = x^2 + x
+        else
+            h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80
+        end
+        return 0.05*h
+    end
+
+    return (Fa, Ff, Fg,height)
+end;
+
+function create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)
+
+    y_t_min = initial_position
+    y_dot_t_min = initial_velocity
+    
+    y_t = y_t_min
+    y_dot_t = y_dot_t_min
+    
+    execute = (a_t::Float64) -> begin
+        # Compute next state
+        y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)
+        y_t = y_t_min + y_dot_t
+    
+        # Reset state for next step
+        y_t_min = y_t
+        y_dot_t_min = y_dot_t
+    end
+    
+    observe = () -> begin 
+        return [y_t, y_dot_t]
+    end
+        
+    return (execute, observe)
+end
create_world (generic function with 1 method)

Let's visualize the mountain landscape and the situation of the car. 

engine_force_limit   = 0.04
+friction_coefficient = 0.1
+
+Fa, Ff, Fg, height = create_physics(
+    engine_force_limit = engine_force_limit,
+    friction_coefficient = friction_coefficient
+);
+initial_position = -0.5
+initial_velocity = 0.0
+
+x_target = [0.5, 0.0] 
+
+valley_x = range(-2, 2, length=400)
+valley_y = [ height(xs) for xs in valley_x ]
+plot(valley_x, valley_y, title = "Mountain valley", label = "Landscape", color = "black")
+scatter!([ initial_position ], [ height(initial_position) ], label="initial car position")   
+scatter!([x_target[1]], [height(x_target[1])], label="camping site")

Naive approach

Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.

N_naive  = 100 # Total simulation time
+pi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only
+
+# Let there be a world
+(execute_naive, observe_naive) = create_world(; 
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+);
+
+y_naive = Vector{Vector{Float64}}(undef, N_naive)
+for t = 1:N_naive
+    execute_naive(pi_naive[t]) # Execute environmental process
+    y_naive[t] = observe_naive() # Observe external states
+end
+
+animation_naive = @animate for i in 1:N_naive
+    plot(valley_x, valley_y, title = "Naive policy", label = "Landscape", color = "black", size = (800, 400))
+    scatter!([y_naive[i][1]], [height(y_naive[i][1])], label="car")
+    scatter!([x_target[1]], [height(x_target[1])], label="goal")   
+end
+
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_naive, "../pics/ai-mountain-car-naive.gif", fps = 24, show_msg = false);

They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.

Active inference approach

Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.

We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows

\[\begin{aligned} +p_t(x,s,u) \propto p(s_{t-1}) \prod_{k=t}^{t+T} p(x_k \mid s_k) \, p(s_k \mid s_{k-1},u_k) \, p(u_k) \, p'(x_k) \nonumber +\end{aligned}\]

where the factors are defined as

\[p'(x_k) = \mathcal{N}(x_k \mid x_{goal},\,V_{goal}) , \quad (\mathrm{target})\]

\[p(s_k \mid s_{k-1},u_k) = \mathcal{N}(s_k \mid \tilde{g}(s_{k-1})+h(u_k),\,\gamma^{-1}) , \quad (\mathrm{state \,\, transition})\]

\[p(x_k \mid s_k) = \mathcal{N}(x_k \mid s_k,\,\theta), \quad (\mathrm{observation})\]

\[p(u_k) = \mathcal{N}(u_k \mid m_u,\,V_u), \quad (\mathrm{control})\]

\[p(s_{t-1}) = \mathcal{N}(s_{t-1} \mid m_{t-1},\,V_{t-1}), \quad (\mathrm{previous \,\, state})\]

where

  • \[x\]

    denotes observations of the agent after interacting with the environment;

  • \[s_t = (s_t,\dot{s_t})\]

    is the state of the car embodying its position and velocity;

  • \[u_t\]

    denotes the control state of the agent;

  • \[h(\cdot)\]

    is the $\tanh(\cdot)$ function modeling engine control;

  • \[\tilde{g}(\cdot)\]

    executes a linear approximation of equations (1) and (2):

\[\begin{aligned} +\dot{s_t} &= \dot{s}_{t-1} + F_g(s_{t-1}) + F_f(\dot{s}_{t-1})\\ +s_t &= s_{t-1} + \dot{s_t} +\end{aligned}\]

In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.

@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)
+    
+    # Transition function modeling transition due to gravity and friction
+    g = (s_t_min::AbstractVector) -> begin 
+        s_t = similar(s_t_min) # Next state
+        s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity
+        s_t[1] = s_t_min[1] + s_t[2] # Update position
+        return s_t
+    end
+    
+    # Function for modeling engine control
+    h = (u::AbstractVector) -> [0.0, Fa(u[1])] 
+    
+    # Inverse engine force, from change in state to corresponding engine force
+    h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] 
+    
+    # Internal model perameters
+    Gamma = 1e4*diageye(2) # Transition precision
+    Theta = 1e-4*diageye(2) # Observation variance
+    
+    m_s_t_min = datavar(Vector{Float64})
+    V_s_t_min = datavar(Matrix{Float64})
+
+    s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)
+    s_k_min = s_t_min
+    
+    m_u = datavar(Vector{Float64}, T)
+    V_u = datavar(Matrix{Float64}, T)
+    
+    m_x = datavar(Vector{Float64}, T)
+    V_x = datavar(Matrix{Float64}, T)
+    
+    u = randomvar(T)
+    s = randomvar(T)
+    x = randomvar(T)
+    
+    u_h_k = randomvar(T)
+    s_g_k = randomvar(T)
+    u_s_sum = randomvar(T)
+    
+    for k in 1:T
+        u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])
+        u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }
+        s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }
+        u_s_sum[k] ~ s_g_k[k] + u_h_k[k]
+        s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)
+        x[k] ~ MvNormal(mean = s[k], cov = Theta)
+        x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal
+        s_k_min = s[k]
+    end
+    
+    return (s, )
+end

After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.

  1. Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time $t$ and gets $T$ observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next $T$ time step.
  2. Infer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state $s_t$ and control $u_t$, i.e. $p(s_t\mid x_t)$ and $p(u_t\mid x_t)$.
  3. Slide: After updating its internal belief, the agent moves to the next time step and uses the inferred action $u_t$ in the previous time step to interact with the environment.

In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:

  • The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next $T$ positions based on the current action. These two function implement the Act-Execute-Observe phase.
  • The compute function infers the policy (which is a set of actions for the next $T$ time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.
  • The slide function implements the Slide phase, which moves the agent internal model to the next time step.
# We are going to use some private functionality from ReactiveMP, 
+# in the future we should expose a proper API for this
+import RxInfer.ReactiveMP: getrecent, messageout
+
+function create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)
+    Epsilon = fill(huge, 1, 1)                # Control prior variance
+    m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors
+    V_u = Matrix{Float64}[ Epsilon for k=1:T ]
+
+    Sigma    = 1e-4*diageye(2) # Goal prior variance
+    m_x      = [zeros(2) for k=1:T]
+    V_x      = [huge*diageye(2) for k=1:T]
+    V_x[end] = Sigma # Set prior to reach goal at t=T
+
+    # Set initial brain state prior
+    m_s_t_min = [initial_position, initial_velocity] 
+    V_s_t_min = tiny * diageye(2)
+    
+    # Set current inference results
+    result = nothing
+
+    # The `infer` function is the heart of the agent
+    # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing
+    compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin
+        m_u[1] = [ upsilon_t ] # Register action with the generative model
+        V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action
+
+        m_x[1] = y_hat_t # Register observation with the generative model
+        V_x[1] = tiny*diageye(2) # Clamp goal prior to observation
+
+        data = Dict(:m_u       => m_u, 
+                    :V_u       => V_u, 
+                    :m_x       => m_x, 
+                    :V_x       => V_x,
+                    :m_s_t_min => m_s_t_min,
+                    :V_s_t_min => V_s_t_min)
+        
+        model  = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) 
+        result = infer(model = model, data = data)
+    end
+    
+    # The `act` function returns the inferred best possible action
+    act = () -> begin
+        if result !== nothing
+            return mode(result.posteriors[:u][2])[1]
+        else
+            return 0.0 # Without inference result we return some 'random' action
+        end
+    end
+    
+    # The `future` function returns the inferred future states
+    future = () -> begin 
+        if result !== nothing 
+            return getindex.(mode.(result.posteriors[:s]), 1)
+        else
+            return zeros(T)
+        end
+    end
+
+    # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step
+    # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`
+    slide = () -> begin
+        (s, ) = result.returnval
+        
+        slide_msg_idx = 3 # This index is model dependend
+        (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))
+
+        m_u = circshift(m_u, -1)
+        m_u[end] = [0.0]
+        V_u = circshift(V_u, -1)
+        V_u[end] = Epsilon
+
+        m_x = circshift(m_x, -1)
+        m_x[end] = x_target
+        V_x = circshift(V_x, -1)
+        V_x[end] = Sigma
+    end
+
+    return (compute, act, slide, future)    
+end
create_agent (generic function with 1 method)

Now it's time to see if we can help our friends arrive at the camping site by midnight?

(execute_ai, observe_ai) = create_world(
+    Fg = Fg, Ff = Ff, Fa = Fa, 
+    initial_position = initial_position, 
+    initial_velocity = initial_velocity
+) # Let there be a world
+
+T_ai = 50
+
+(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent
+    T  = T_ai, 
+    Fa = Fa,
+    Fg = Fg, 
+    Ff = Ff, 
+    engine_force_limit = engine_force_limit,
+    x_target = x_target,
+    initial_position = initial_position,
+    initial_velocity = initial_velocity
+) 
+
+N_ai = 100
+
+# Step through experimental protocol
+agent_a = Vector{Float64}(undef, N_ai) # Actions
+agent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future
+agent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations
+
+for t=1:N_ai
+    agent_a[t] = act_ai()               # Invoke an action from the agent
+    agent_f[t] = future_ai()            # Fetch the predicted future states
+    execute_ai(agent_a[t])              # The action influences hidden external states
+    agent_x[t] = observe_ai()           # Observe the current environmental outcome (update p)
+    compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)
+    slide_ai()                          # Prepare for next iteration
+end
+
+animation_ai = @animate for i in 1:N_ai
+    # pls - plot landscape
+    pls = plot(valley_x, valley_y, title = "Active inference results", label = "Landscape", color = "black")
+    pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label="car")
+    pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label="goal")   
+    pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = "Predicted future", alpha = map(i -> 0.5 / i, 1:T_ai))
+    
+    # pef - plot engine force
+    pef = plot(Fa.(agent_a[1:i]), title = "Engine force (agents actions)", xlim = (0, N_ai), ylim = (-0.05, 0.05))
+    
+    plot(pls, pef, size = (800, 400))
+end
+    
+# The animation is saved and displayed as markdown picture for the automatic HTML generation
+gif(animation_ai, "../pics/ai-mountain-car-ai.gif", fps = 24, show_msg = false);

Voila! The car now is able to reach the camping site with a smart strategy.

The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.

Now our friends can enjoy their trip at the camping site!.

Reference

We refer reader to the Thijs van de Laar (2019) "Simulating active inference processes by message passing" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) "Deep active inference".

diff --git a/v2.16.2/examples/advanced_examples/Advanced Tutorial/index.html b/v2.16.2/examples/advanced_examples/Advanced Tutorial/index.html new file mode 100644 index 000000000..f87e2a86d --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Advanced Tutorial/index.html @@ -0,0 +1,416 @@ + +Advanced Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Advanced Tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Plots

This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.

This tutorial is also available in the documentation.

General model specification syntax

We use the @model macro from the RxInfer.jl package to create a probabilistic model $p(s, y)$ and we also specify extra constraints on the variational family of distributions $\mathcal{Q}$, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.

# the `@model` macro accepts a regular Julia function
+@model function test_model1(s_mean, s_precision)
+    
+    # We use the `randomvar` function to create 
+    # a random variable in our model
+    s = randomvar()
+    
+    # the `tilde` operator creates a functional dependency
+    # between variables in our model and can be read as 
+    # `sampled from` or `is modeled by`
+    s ~ Normal(mean = s_mean, precision = s_precision)
+    
+    # We use the `datavar` function to create 
+    # observed data variables in our models
+    # We also need to specify the type of our data 
+    # In this example it is `Float64`
+    y = datavar(Float64)
+    
+    y ~ Normal(mean = s, precision = 1.0)
+    
+    # It is possible to return something from the model specification (including variables and nodes)
+    return "Hello world"
+end

The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.

modelgenerator = test_model1(0.0, 1.0)
+
+model, returnval = create_model(modelgenerator)
(FactorGraphModel(), "Hello world")

The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.

RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as:

  • getnodes(): returns an array of factor nodes in a corresponding factor graph
  • getrandom(): returns an array of random variables in the model
  • getdata(): returns an array of data inputs in the model
  • getconstant(): returns an array of constant values in the model
getnodes(model)
FactorNodesCollection(nodes: 2)
getrandom(model) .|> name
1-element Vector{Symbol}:
+ :s
getdata(model) .|> name
1-element Vector{Symbol}:
+ :y
getconstant(model) .|> getconst
3-element Vector{Float64}:
+ 0.0
+ 1.0
+ 1.0

It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:

@model function test_model2(n)
+    
+    if n <= 1
+        error("`n` argument must be greater than one.")
+    end
+    
+    # `randomvar(n)` creates a dense sequence of 
+    # random variables
+    s = randomvar(n)
+    
+    # `datavar(Float64, n)` creates a dense sequence of 
+    # observed data variables of type `Float64`
+    y = datavar(Float64, n)
+    
+    s[1] ~ Normal(mean = 0.0, precision = 0.1)
+    y[1] ~ Normal(mean = s[1], precision = 1.0)
+    
+    for i in 2:n
+        s[i] ~ Normal(mean = s[i - 1], precision = 1.0)
+        y[i] ~ Normal(mean = s[i], precision = 1.0)
+    end
+    
+end
model, _ = create_model(test_model2(10));
# An amount of factor nodes in generated Factor Graph
+getnodes(model) |> length
20
# An amount of random variables
+getrandom(model) |> length
10
# An amount of data inputs
+getdata(model) |> length
10
# An amount of constant values
+getconstant(model) |> length
21

It is also possible to use complex expressions inside the functional dependency expressions

y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)

The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists

# s = randomvar() here is optional
+# `~` creates random variables automatically
+s ~ NormalMeanPrecision(0.0, 1.0)

An example model which will throw an error:

@model function error_model1()
+    s = 1.0
+    s ~ NormalMeanPrecision(0.0, 1.0)
+end

By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as

# Creates constant reference in a model with a prespecified value
+c = constvar(0.0)

An example:

@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)
+    
+    s = randomvar(n)
+    
+    y = datavar(Vector{Float64}, n)
+    
+    # Here we create constant references
+    # for constant matrices in our model 
+    # to make inference more memory efficient
+    cA = constvar(A)
+    cP = constvar(P)
+    cQ = constvar(Q)
+    
+    s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)
+    y[1] ~ MvNormal(mean = s[1], covariance = cQ)
+    
+    for i in 2:n
+        s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)
+        y[i] ~ MvNormal(mean = s[i], covariance = cQ)
+    end
+    
+end

The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:

@model function test_model()
+
+    # In this example `ynode` refers to the corresponding 
+    # `GaussianMeanVariance` node created in the factor graph
+    ynode, y ~ GaussianMeanVariance(0.0, 1.0)
+    
+    return ynode, y
+end

Probabilistic inference in RxInfer.jl

RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.

Observables

Observables are lazy push-based collections and they deliver their values over time.

# Timer that emits a new value every second and has an initial one second delay 
+observable = timer(300, 300)
TimerObservable(300, 300)

A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:

actor = (value) -> println(value)
+subscription1 = subscribe!(observable, actor)
TimerSubscription()
# We always need to unsubscribe from some observables
+unsubscribe!(subscription1)
# We can modify our observables
+modified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)
ProxyObservable(Int64, MapProxy(Int64))
subscription2 = subscribe!(modified, (value) -> println(value))
TimerSubscription()
unsubscribe!(subscription2)
@model function coin_toss_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+    
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    
+    # We assume that the outcome of each coin flip 
+    # is modeled by a Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+    
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during the inference step
+    return y, θ
+end

We can call the inference function to run inference in such model:

p = 0.75 # Bias of a coin
+
+dataset = float.(rand(Bernoulli(p), 500));
+
+result = infer(
+    model = coin_toss_model(length(dataset)),
+    data  = (y = dataset, )
+)
+
+println("Inferred bias: ", mean_var(result.posteriors[:θ]))
Inferred bias: (0.7642436149312377, 0.0003532849254275917)

We can see that the inferred bias is quite close to the actual value we used in the dataset generation.

The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions:

  • getmarginal(x): for a single random variable x
  • getmarginals(xs): for a dense sequence of random variables sx

Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.

_, (y, θ) = create_model(coin_toss_model(length(dataset)));
# As soon as we have a new value for the marginal posterior over the `θ` variable
+# we simply print the first two statistics of it
+θ_subscription = subscribe!(getmarginal(θ), (marginal) -> println("New update: mean(θ) = ", mean(marginal), ", std(θ) = ", std(marginal)));

To pass data to our model we use update! function

update!(y, dataset)
New update: mean(θ) = 0.7642436149312377, std(θ) = 0.018795875223771616
# It is necessary to always unsubscribe from running observables
+unsubscribe!(θ_subscription)
# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them
+# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing
+update!(y, dataset)

Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.

# the `keep` actor simply keeps all incoming updates in an internal storage, ordered
+θvalues = keep(Marginal)
KeepActor{Marginal}(Marginal[])
# `getmarginal` always emits last cached value as its first value
+subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=389.0, β=120.0))
subscribe!(getmarginal(θ) |> take(1), θvalues);
getvalues(θvalues)
2-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=389.0, β=120.0))
+ Marginal(Beta{Float64}(α=389.0, β=120.0))
# the `buffer` actor keeps very last incoming update in an internal storage and can also store 
+# an array of updates for a sequence of random variables
+θbuffer = buffer(Marginal, 1)
BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=389.0, β=120.0))
subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);
getvalues(θbuffer)
1-element Vector{Marginal}:
+ Marginal(Beta{Float64}(α=389.0, β=120.0))

Reactive Online Inference

RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.

@model function online_coin_toss_model()
+    
+    # We create datavars for the prior 
+    # over `θ` variable
+    θ_a = datavar(Float64)
+    θ_b = datavar(Float64)
+    
+    θ ~ Beta(θ_a, θ_b)
+    
+    y = datavar(Float64)
+    y ~ Bernoulli(θ)
+
+end
autoupdates = @autoupdates begin 
+    θ_a, θ_b = params(q(θ))
+end
(θ_a,θ_b = params(q(θ)),)
rxresult = infer(
+    model = online_coin_toss_model(),
+    data  = (y = dataset, ),
+    autoupdates = autoupdates,
+    historyvars = (θ = KeepLast(), ),
+    keephistory = length(dataset),
+    initmarginals = (
+        θ = vague(Beta),
+    ),
+    autostart = true
+);
animation = @animate for i in 1:length(dataset)
+    plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = "Online coin bias inference", label = "Inferred bias", legend = :bottomright)
+    hline!([ p ], label = "Real bias", size = (600, 200))
+end
+
+gif(animation, "../pics/online-coin-bias-inference.gif", fps = 24, show_msg = false);

In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.

That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.

Variational inference

On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions $q \in \mathcal{Q}$. Often this involves assuming some factorization over $q$. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.

@model function test_model6_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+
+end

In this example we specified an extra constraints for $q_a$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

There are several options to specify the mean-field factorisation constraint. 

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name

It is also possible to use local structured factorisation:

y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification
+y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification

RxInfer.jl constraints macro

RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:

constraints6 = @constraints begin
+     q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

Note: where blocks have higher priority over constraints specification

@model function test_model6(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        # Here we assume a mean-field assumption on our 
+        # variational family of distributions locally for the current node
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end

Inference

To run inference in this model we again need to create a synthetic dataset:

dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);

inference function

In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:

Use ?inference to quickly check the documentation for the inference function.

result = infer(
+    model         = test_model6(length(dataset)),
+    data          = (y = dataset, ),
+    constraints   = constraints6, 
+    initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),
+    returnvars    = (μ = KeepLast(), τ = KeepLast()),
+    iterations    = 10,
+    free_energy   = true,
+    showprogress  = true
+)
Inference results:
+  Posteriors       | available for (μ, τ)
+  Free Energy:     | Real[14763.3, 3275.55, 643.409, 599.743, 599.742, 599.
+742, 599.742, 599.742, 599.742, 599.742]
println("μ: mean = ", mean(result.posteriors[:μ]), ", std = ", std(result.posteriors[:μ]))
μ: mean = -2.9941782279022204, std = 0.013832445627312158
println("τ: mean = ", mean(result.posteriors[:τ]), ", std = ", std(result.posteriors[:τ]))
τ: mean = 5.226382915400179, std = 0.23349756856917872

Manual inference

For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);

For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:

setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values)
10-element Vector{Marginal}:
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.0001723247568237e-9, w
+=0.010000001002000566))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.485015477021832, w=9.
+189467886050704))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9988.618014104622, w=333
+6.0167911607655))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15639.907122824821, w=52
+23.438936935284))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.743045696663, w=52
+26.389965662661))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751868939184, w=52
+26.392912456405))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877744757, w=52
+26.392915397171))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877753584, w=52
+26.392915400165))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877753579, w=52
+26.392915400165))
+ Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877753586, w=52
+26.392915400165))
getvalues(τ_values)
10-element Vector{Marginal}:
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=5.0000000000457825e14))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=54578.32700317227))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=150.17955039164815))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.91400707251834))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85985008582941))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.8597960371289))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85979598318833))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85979598313438))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.8597959831344))
+ Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85979598313433))
println("μ: mean = ", mean(last(μ_values)), ", std = ", std(last(μ_values)))
μ: mean = -2.9941782279022204, std = 0.013832445627312158
println("τ: mean = ", mean(last(τ_values)), ", std = ", std(last(τ_values)))
τ: mean = 5.226382915400179, std = 0.23349756856917872

Form constraints

In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.

<img style="display: block; margin-left: auto; margin-right: auto; width: 50%;" src="./pics/posterior.png" />

@model function test_model7_with_manual_constraints(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }
+    end
+    
+    return μ, τ, y
+end

As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:

constraints7 = @constraints begin 
+    q(μ) :: PointMass
+    
+    q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`
+end
Constraints:
+  marginals form:
+    q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(μ, τ) = q(μ)q(τ)
+Options:
+  warn = true

In this example we specified an extra constraints for $q_i$ for Bethe factorisation:

\[\begin{aligned} +q(s) = \prod_{a \in \mathcal{V}} q_a(s_a) \prod_{i \in \mathcal{E}} q_i^{-1}(s_i) +\end{aligned}\]

@model function test_model7(n)
+    τ ~ Gamma(shape = 1.0, rate = 1.0) 
+    
+    # In case of form constraints `randomvar()` call is necessary
+    μ = randomvar()
+    μ ~ Normal(mean = 0.0, variance = 100.0)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = μ, precision = τ)
+    end
+    
+    return μ, τ, y
+end
model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);
setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, PointMass(1.0))
+
+μ_values = keep(Marginal)
+τ_values = keep(Marginal)
+
+μ_subscription = subscribe!(getmarginal(μ), μ_values)
+τ_subscription = subscribe!(getmarginal(τ), τ_values)
+
+for i in 1:10
+    update!(y, dataset)
+end
getvalues(μ_values) |> last
Marginal(PointMass{Float64}(-2.9941782336196785))
getvalues(τ_values) |> last
Marginal(GammaShapeRate{Float64}(a=501.0, b=95.76412770708546))

By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.

μ = randomvar() where { 
+    prod_constraint = ProdGeneric(),
+    form_constraint = SampleListFormConstraint() 
+}

Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:

μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }

Note: @constraints macro specifies required prod_constraint automatically.

Free Energy

During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.

model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);
bfe_observable = score(model, Float64, BetheFreeEnergy())
ProxyObservable(Float64, ErrorIfProxy())
bfe_subscription = subscribe!(bfe_observable, (fe) -> println("Current BFE value: ", fe));
# Reset the model with vague marginals
+setmarginal!(μ, vague(NormalMeanPrecision))
+setmarginal!(τ, vague(GammaShapeRate))
+
+for i in 1:10
+    update!(y, dataset)
+end
Current BFE value: 612.2308443178317
+Current BFE value: 599.7424442637521
+Current BFE value: 599.7424440148366
+Current BFE value: 599.742444014837
+Current BFE value: 599.7424440148343
+Current BFE value: 599.7424440148375
+Current BFE value: 599.7424440148361
+Current BFE value: 599.742444014837
+Current BFE value: 599.7424440148361
+Current BFE value: 599.742444014837
# It always necessary to unsubscribe and release computer resources
+unsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])

Meta data specification

During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:

# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of 
+# the autoregressive process and its order. In addition it specifies that the message computation rules should
+# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations
+# by cost of possible numerical instabilities during an inference procedure
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }
+...
+s[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }

Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:

# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` 
+# method with `21` sigma points for approximation of non-lineariety between hierarchy layers
+xt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }

The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.

RxInfer.jl @meta macro

Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:

@meta begin 
+     AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())
+end
Meta specification:
+  AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())
+Options:
+  warn = true

Creating custom nodes and message computation rules

Custom nodes

To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:

# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification
+@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]
+
+# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error
+struct NormalMeanVariance end 
+
+@node NormalMeanVariance Stochastic [ out, μ, v ]
+
+# It is also possible to use function objects as a node functional form
+function dot end
+
+# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them 
+# out = dot(x, a)
+@node typeof(dot) Deterministic [ out, x, a ]

Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.

After that it is possible to use the newly created node during model specification:

@model function test_model()
+    ...
+    y ~ dot(x, a)
+    ...
+end

Custom messages computation rules

RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:

\[\begin{aligned} +\mu_z = \mu_x + \mu_y\\ +V_z = V_x + V_y +\end{aligned}\]

To specify this in RxInfer.jl we use the @node and @rule macros:

@node typeof(+) Deterministic  [ z, x, y ]
+
+@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin
+    x_mean, x_var = mean_var(m_x)
+    y_mean, y_var = mean_var(m_y)
+    return NormalMeanVariance(x_mean + y_mean, x_var + y_var)
+end

In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:

\[\begin{aligned} +q(z) = \int q(z, x, y) \mathrm{d}x\mathrm{d}y +\end{aligned}\]

If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:

\[\begin{aligned} +\mu(z) = \int f(x, y, z)\mu(x)\mu(y)\mathrm{d}x\mathrm{d}y +\end{aligned}\]

\[\begin{aligned} +\nu(z) = \exp{ \int \log f(x, y, z)q(x)q(y)\mathrm{d}x\mathrm{d}y } +\end{aligned}\]

The @rule macro supports both cases with special prefixes during rule specification:

  • m_ prefix corresponds to the incoming message on a specific edge
  • q_ prefix corresponds to the posterior marginal of a specific edge

Example of a Sum-Product rule with m_ messages used:

@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin 
+    m_out_mean, m_out_cov = mean_cov(m_out)
+    return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))
+end

Example of a Variational rule with Mean-Field assumption with q_ posteriors used:

@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin 
+    return NormalMeanPrecision(mean(q_out), mean(q_τ))
+end

RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:

@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin
+    m, V = mean_cov(q_out_μ)
+    θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))
+    α = convert(typeof(θ), 1.5)
+    return Gamma(α, θ)
+end

NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:

# Inference backend expects arguments in `@rule` macro to be in the same order
+@node NormalMeanPrecision Stochastic [ out, μ, τ ]

Any rule always has access to the meta information with hidden the meta::Any variable:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin 
+    ...
+    println(meta)
+    ...
+end

It is also possible to dispatch on a specific type of a meta object:

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin 
+    ...
+end

or

@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin 
+    ...
+end

Customizing messages computational pipeline

In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.

<img style="display: block; margin-left: auto; margin-right: auto; width: 30%;" src="./pics/pipeline.png" width="20%" />

# Logs all outbound messages
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }
+# Initialise messages to be vague
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }
+# In principle, it is possible to approximate outbound messages with Laplace Approximation
+y[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }

Let us return to the coin toss model, but this time we want to print flowing messages:

@model function coin_toss_model_log(n)
+
+    y = datavar(Float64, n)
+
+    θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage("θ") }
+
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)  where { pipeline = LoggerPipelineStage("y[$i]") }
+    end
+    
+    return y, θ
+end
_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));
θ_subscription = subscribe!(getmarginal(θ), (value) -> println("New posterior marginal for θ: ", value));
[θ][Beta][out]: VariationalMessage()
coinflips = float.(rand(Bernoulli(0.5), 5));
update!(y, coinflips)
[y[1]][Bernoulli][p]: VariationalMessage()
+[y[2]][Bernoulli][p]: VariationalMessage()
+[y[3]][Bernoulli][p]: VariationalMessage()
+[y[4]][Bernoulli][p]: VariationalMessage()
+[y[5]][Bernoulli][p]: VariationalMessage()
+New posterior marginal for θ: Marginal(Beta{Float64}(α=5.0, β=9.0))
unsubscribe!(θ_subscription)
# Inference is lazy and does not send messages if no one is listening for them
+update!(y, coinflips)
diff --git a/v2.16.2/examples/advanced_examples/Assessing People Skills/index.html b/v2.16.2/examples/advanced_examples/Assessing People Skills/index.html new file mode 100644 index 000000000..5a9352b32 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Assessing People Skills/index.html @@ -0,0 +1,49 @@ + +Assessing People’s Skills · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Assessing People’s Skills

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of "Model-Based Machine Learning" by Winn et al.

Problem Statement

We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?

We model the result for question $i$ as a continuous variable $r_i\in[0,1]$, and skill/attitude as a binary variable $s_i \in \{0, 1\}$, where $s_1$ represents whether the student has partied, and $s_2$ and $s_3$ represent whether the student has studied the chapters for the corresponding questions.

We assume the following logic:

  • If the student is alert (has not partied), then they will score on the first question;
  • If the student is alert or has studied chapter two, then they will score on question two;
  • If the student can answer question two and has studied chapter three, then they will score on question three.

Generative Model Definition

To model the probability for correct answers, we assume a latent state variable $t_i \in \{0,1\}$. The dependencies between the variables can then be modeled by the following Bayesian network:

(s_1)   (s_2)   (s_3)
+  |       |       |
+  v       v       v
+(t_1)-->(t_2)-->(t_3)
+  |       |       |
+  v       v       v
+(r_1)   (r_2)   (r_3)

As prior beliefs, we assume that a student is equally likely to study/party or not: $s_i \sim Ber(0.5)\,,$ for all $i$. Next, we model the domain logic as $\begin{aligned} t_1 &= ¬s_1\\ + t_2 &= t_1 ∨ s_2\\ + t_3 &= t_2 ∧ s_3\,. \end{aligned}$ For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as $t_i \sim Ber(s_i)\,,$ for all $i$.

Custom Nodes and Rules

The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.

In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.

using RxInfer, Random
+
+# Create Score node
+struct Score end
+
+@node Score Stochastic [out, in]

We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.

# Adding update rule for the Score node
+@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin     
+    return Bernoulli(mean(q_out))
+end

Generative Model Specification

We can now build the full generative model.

# GraphPPL.jl exports the `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function skill_model()
+    s = randomvar(3)
+    t = randomvar(3)
+    r = datavar(Float64, 3)
+
+    # Priors
+    for i=1:3
+        s[i] ~ Bernoulli(0.5)
+    end
+
+    # Domain logic
+    t[1] ~ ¬s[1]
+    t[2] ~ t[1] || s[2]
+    t[3] ~ t[2] && s[3]
+    
+    # Results
+    for i=1:3
+        r[i] ~ Score(t[i])
+    end
+end

Inference Specification

Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.

test_results = [0.1, 0.1, 0.1]
+inference_result = infer(
+    model = skill_model(),
+    data  = (r = test_results, )
+)
Inference results:
+  Posteriors       | available for (s, t)

Results

# Inspect the results
+map(params, inference_result.posteriors[:s])
3-element Vector{Tuple{Float64}}:
+ (0.9872448979591837,)
+ (0.06377551020408162,)
+ (0.4719387755102041,)

These results suggest that this particular student was very likely out on the town last night.

diff --git a/v2.16.2/examples/advanced_examples/Chance Constraints/index.html b/v2.16.2/examples/advanced_examples/Chance Constraints/index.html new file mode 100644 index 000000000..3b129a3db --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Chance Constraints/index.html @@ -0,0 +1,166 @@ + +Chance-Constrained Active Inference · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Chance-Constrained Active Inference

This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, "Chance-constrained active inference") and discussion with John Boik.

We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. 

using Pkg; Pkg.activate(".."); Pkg.instantiate();
using Plots, Distributions, StatsFuns, RxInfer

Chance-Constraint Node Definition

A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not "overflow" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.

In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.

struct ChanceConstraint end  
+
+# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol
+@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]
# Function to compute normalizing constant and central moments of a truncated Gaussian distribution
+function truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)
+    V = clamp(V, tiny, huge)
+    StdG = Distributions.Normal(m, sqrt(V))
+    TrG = Distributions.Truncated(StdG, a, b)
+    
+    Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a)  # safe mass for standard Gaussian
+    
+    if Z < tiny
+        # Invalid region; return undefined mean and variance of truncated distribution
+        Z    = 0.0
+        m_tr = 0.0
+        V_tr = 0.0
+    else
+        m_tr = Distributions.mean(TrG)
+        V_tr = Distributions.var(TrG)
+    end
+    
+    return (Z, m_tr, V_tr)
+end;
@rule ChanceConstraint(:out, Marginalisation) (
+    m_out::UnivariateNormalDistributionsFamily, # Require inbound message
+    q_lo::PointMass, 
+    q_hi::PointMass, 
+    q_epsilon::PointMass, 
+    q_atol::PointMass) = begin 
+
+    # Extract parameters
+    lo = mean(q_lo)
+    hi = mean(q_hi)
+    epsilon = mean(q_epsilon)
+    atol = mean(q_atol)
+    
+    (m_bw, V_bw) = mean_var(m_out)
+    (xi_bw, W_bw) = (m_bw, 1. /V_bw)  # check division by  zero
+    (m_tilde, V_tilde) = (m_bw, V_bw)
+    
+    # Compute statistics (and normalizing constant) of q in safe region G
+    # Phi_G is called the "safe mass" 
+    (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)
+
+    xi_fw = xi_bw
+    W_fw  = W_bw
+    if epsilon <= 1.0 - Phi_G # If constraint is active
+        # Initialize statistics of uncorrected belief
+        m_tilde = m_bw
+        V_tilde = V_bw
+        for i = 1:100 # Iterate at most this many times
+            (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G
+            (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G
+
+            # Compute moments of non-G region as a mixture of left and right truncations
+            Phi_nG = Phi_lG + Phi_rG
+            m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG
+            V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2
+
+            # Compute moments of corrected belief as a mixture of G and non-G regions
+            m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG
+            V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2
+            # Re-compute statistics (and normalizing constant) of corrected belief
+            (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)
+            if (1.0 - Phi_G) < (1.0 + atol)*epsilon
+                break # Break the loop if the belief is sufficiently corrected
+            end
+        end
+        
+        # Convert moments of corrected belief to canonical form
+        W_tilde = inv(V_tilde)
+        xi_tilde = W_tilde * m_tilde
+
+        # Compute canonical parameters of forward message
+        xi_fw = xi_tilde - xi_bw
+        W_fw  = W_tilde - W_bw
+    end
+
+    return NormalWeightedMeanPrecision(xi_fw, W_fw)
+end

Definition of the Environment

We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.

wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile
+
+function initializeWorld()
+    x_0 = 0.0 # Initial elevation
+    
+    x_t_last = x_0
+    function execute(t::Int64, a_t::Float64)
+        x_t = x_t_last + a_t + wind(t) # Update elevation
+    
+        x_t_last = x_t # Reset state
+                
+        return x_t
+    end
+
+    x_t = x_0 # Predefine outcome variable
+    observe() = x_t # State is fully observed
+
+    return (execute, observe)
+end;

Generative Model for Regulator

We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.

@model function regulator_model(; T, lo, hi, epsilon, atol)
+    # Fully observed state
+    x_t = datavar(Float64)
+
+    # Control prior statistics
+    m_u = datavar(Float64, T)
+    v_u = datavar(Float64, T)    
+        
+    # Random variables
+    u = randomvar(T) # Control
+    x = randomvar(T) # Elevation
+    
+    # Loop over horizon
+    x_k_last = x_t
+    for k = 1:T
+        u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior
+        x[k] ~ x_k_last + u[k] # Transition model
+        x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state
+            pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency
+        x_k_last = x[k]
+    end
+    
+    return (u, x)
+end

Reactive Agent Definition

function initializeAgent()
+    # Set control prior statistics
+    m_u = zeros(T)
+    v_u = lambda^(-1)*ones(T)
+    
+    function compute(x_t::Float64)
+        model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)
+        data_t = (m_u = m_u, v_u = v_u, x_t = x_t)
+        
+        result = infer(
+            model = model_t, 
+            data = data_t,
+            iterations = n_its)
+
+        # Extract policy from inference results
+        pol = mode.(result.posteriors[:u][end])
+
+        return pol
+    end
+
+    pol = zeros(T) # Predefine policy variable
+    act() = pol[1]
+
+    return (compute, act)
+end;

Action-Perception Cycle

Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. 

# Simulation parameters
+N = 160 # Total simulation time
+T = 1 # Lookahead time horizon
+lambda = 1.0 # Control prior precision
+lo = 1.0 # Chance region lower bound
+hi = Inf # Chance region upper bound
+epsilon = 0.01 # Allowed chance violation
+atol = 0.01 # Convergence tolerance for chance constraints
+n_its = 10;  # Number of inference iterations
(execute, observe) = initializeWorld() # Let there be a world
+(compute, act) = initializeAgent() # Let there be an agent
+
+a = Vector{Float64}(undef, N) # Actions
+x = Vector{Float64}(undef, N) # States
+for t = 1:N
+    a[t] = act()
+           execute(t, a[t])
+    x[t] = observe()
+           compute(x[t])
+end

Results

Results show that the agent does not allow the wind to push it all the way to the ground.

p1 = plot(1:N, wind.(1:N), color="blue", label="Wind", ylabel="Velocity", lw=2)
+plot!(p1, 1:N, a, color="red", label="Control", lw=2)
+p2 = plot(1:N, x, color="black", lw=2, label="Agent", ylabel="Elevation")
+plot(p1, p2, layout=(2,1))

diff --git a/v2.16.2/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html b/v2.16.2/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html new file mode 100644 index 000000000..a4529d9d7 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Conjugate-Computational Variational Message Passing/index.html @@ -0,0 +1,143 @@ + +Conjugate-Computational Variational Message Passing (CVI) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Conjugate-Computational Variational Message Passing (CVI)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions

In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.

This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.

An example: nonlinear dynamical system

A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position $z_t$ at time $t$. Instead they have access to the observed squared distance $y_t$ between the object and some reference point $s$. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:

# data generating process
+nr_observations = 50
+reference_point = 53
+hidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)
+measurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);
# plot hidden location and reference frame
+p1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label="hidden location")
+hline!([reference_point], linewidth=3, label="reference point")
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot measurements
+p2 = scatter(1:nr_observations, measurements, linewidth=3, label="measurements")
+xlabel!("time [sec]"), ylabel!("squared distance [cm2]")
+
+plot(p1, p2, size=(1200, 500))

The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model

\[\begin{aligned} + p(\tau) & = \Gamma(\tau \mid \alpha_{\tau}, \beta_{\tau}),\\ + p(\gamma) & = \Gamma(\gamma \mid \alpha_{\gamma}, \beta_{\gamma}),\\ + p(z_t \mid z_{t - 1}, \tau) & = \mathcal{N}(z_t \mid z_{t - 1} + 1, \tau^{-1}),\\ + p(y_t \mid z_t, \gamma) & = \mathcal{N}(y_t \mid (z_t - s)^2, \gamma^{-1}), +\end{aligned}\]

where the researchers put priors on the process and measurement noise parameters, $\tau$ and $\gamma$, respectively. They do this, because they do not know the accuracy of their devices.

The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:

function compute_squared_distance(z)
+    (z - reference_point)^2
+end;
@model function measurement_model(nr_observations)
+
+    # allocate random variables and observations
+    z = randomvar(nr_observations)
+    y = datavar(Float64, nr_observations)
+
+    # set priors on precision parameters
+    τ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    γ ~ Gamma(shape = 1.0, rate = 1.0e-12)
+    
+    # specify estimate of initial location
+    z[1] ~ Normal(mean = 0, precision = τ)
+    y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)
+
+    # loop over observations
+    for t in 2:nr_observations
+
+        # specify state transition model
+        z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)
+
+        # specify non-linear observation model
+        y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)
+        
+    end
+
+end

But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).

The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:

@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)
+    compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)
+end;

In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:

@meta function model_meta(...)
+    f() -> CVI(args...)
+end

See ?CVI for more information about the args....

In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.

In the above example, we will assume the following posterior factorization:

@constraints function measurement_constraints()
+    q(z, τ, γ) = q(z)q(τ)q(γ)
+end;

This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as 

@constraints function posterior_constraints() begin
+    q(z, γ) = q(z)q(γ) # CVI
+    q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node
+end

Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.

results = infer(
+    model = measurement_model(nr_observations),
+    data = (y = measurements,),
+    iterations = 5,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = measurement_constraints(),
+    meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),
+    initmessages = (z = NormalMeanVariance(0, 5),),
+    initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),
+)
Inference results:
+  Posteriors       | available for (z)
+  Free Energy:     | Real[1241.91, 429.933, 376.869, 365.774, 362.879]
# plot estimates for location
+p1 = plot(collect(1:nr_observations), hidden_location, label = "hidden location", legend=:topleft, linewidth=3, color = :red)
+plot!(map(mean, results.posteriors[:z]), label = "estimated location (±2σ)", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)
+xlabel!("time [sec]"), ylabel!("location [cm]")
+
+# plot Bethe free energy
+p2 = plot(results.free_energy, linewidth=3, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size = (1200, 500))

Requirements

There are several main requirements for the CVI procedure to satisfy:

  1. The out interface of the non-linearity must be independently factorized with respect to other variables in the model.
  2. The messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.

In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as

@model function model(...)
+    ...
+    y ~ f(x1, x2, ..., xN)
+    ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity
+    ... 
+end
+
+@constraints function constraints_meta() begin
+    q(y, z1, ..., zn) = q(y)q(z1,...,zM)
+    ...
+end;
+
+@meta function model_meta(...)
+    f() -> CVI(rng, nr_samples, nr_iterations, optimizer))
+end

Note that not all exponential family distributions are implemented.

Extensions

Using a custom optimizer

CVI only supports Optimisers optimizers out of the box.

Below an explanation on how to extend to it to a custom optimizer.

Suppose we have CustomDescent structure which we want to use inside CVI for optimization.

To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).

ReactiveMP.cvi_update! incapsulates the gradient step:

  1. opt is used to select your optimizer structure
  2. λ is the current value
  3. ∇ is a gradient value computed inside CVI.
struct CustomDescent 
+    learning_rate::Float64
+end
+
+# Must return an optimizer and its initial state
+function ReactiveMP.cvi_setup(opt::CustomDescent, q)
+     return (opt, nothing)
+end
+
+# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)
+function ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)
+    opt, _ = opt_and_state
+    λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))
+    copyto!(new_λ, λ̂)
+    return opt_and_state, new_λ
+end

Let's try to apply it to a model: $\begin{aligned} p(x) & = \mathcal{N}(0, 1),\\ + p(y_{i}\mid x) & = \mathcal{N}(y_i \mid x^2, 1),\\ +\end{aligned}$

Let's generate some synthetic data for the model

# generate data
+y = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)
+histogram(y)

Again we can create the corresponding model as:

# specify non-linearity
+f(x) = x ^ 2
+
+# specify model
+@model function normal_square_model(nr_observations)
+
+    # allocate observations
+    y = datavar(Float64, nr_observations)
+
+    # describe prior on latent state
+    x ~ NormalMeanPrecision(0, 100)
+
+    # transform latent state
+    mean ~ f(x)
+
+    # observation model
+    y .~ NormalMeanVariance(mean, 1)
+
+end
+
+# specify meta
+@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)
+    f() ->  CVI(rng, nr_samples, nr_iterations, optimizer)
+end
normal_square_meta (generic function with 1 method)

We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:

Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.

res = infer(
+    model = normal_square_model(1000),
+    data = (y = y,),
+    iterations = 10,
+    free_energy = true,
+    initmessages = (x = NormalMeanVariance(0, 100),),
+    meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))
+)
+
+mean(res.posteriors[:x][end])
-18.998075156688632

The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working!

Note: $x^2$ can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.

diff --git a/v2.16.2/examples/advanced_examples/GP Regression by SSM/index.html b/v2.16.2/examples/advanced_examples/GP Regression by SSM/index.html new file mode 100644 index 000000000..e35b70084 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/GP Regression by SSM/index.html @@ -0,0 +1,99 @@ + +Solve GP regression by SDE · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Solve GP regression by SDE

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this notebook, we solve a GP regression problem by using "Stochastic Differential Equation" (SDE). This method is well described in the dissertation "Stochastic differential equation methods for spatio-temporal Gaussian process regression." by Arno Solin and "Sequential Inference for Latent Temporal Gaussian Process Models" by Jouni Hartikainen. The idea of the method is as follows.

Suppose a function $f(x)$ follows a zero-mean Gaussian Process $\begin{aligned} f(x) \sim \mathcal{GP}(0, k(x,x')). \end{aligned}$

When the dimensionality of $x$ is 1, we can consider $f(x)$ as a stochastic process over time, i.e. $f(t)$. For a certain classses of covariance functions, $f(t)$ is a solution to an $m$-th order linear stochastic differential equation (SDE) $\begin{aligned} a_0 f(t) + a_1 \frac{d f(t)}{dt} + \dots + a_m \frac{d^m f(t)}{dt^m} = w(t) \end{aligned}$

where $w(t)$ is a zero-mean white noise process with spectral density $Q_c$. If we define a vector-valued function $\mathbf{f}(t) = (f(t),\, d/dt f(t),\dots,\, d^{m-1}/dt^{m-1}f(t))$, then we can rewrite the above SDE under the companion form

\[\begin{aligned} +\frac{d \mathbf{f}(t)}{dt} = \mathbf{F}\, \mathbf{f}(t) + \mathbf{L} w(t) \quad (1) +\end{aligned}\]

where $\mathbf{F}$ and $\mathbf{L}$ are defined based on the choice of covariance functions. From (1), we have the following state-space model: $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \quad(2a) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}) \quad(2b). \\ +\end{aligned}$

where $\mathbf{A}_k = \exp{(\mathbf{F}\,\Delta t_k)}$, with $\Delta t_k = t_{k+1} - t_k$, is called the discrete-time state transition matrix, and $\mathbf{Q}_k$ the process noise covariance matrix. For the computation of $\mathbf{Q}_k$, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state $f_0 \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_0)$. For stationary covariance function, the SDE has a stationary state $f_\infty \sim \mathcal{N}(\mathbf{0},\, \mathbf{P}_\infty)$, where $\mathbf{P}_\infty$ is the solution to $\begin{aligned} \frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0 \quad (\mathrm{Lyapunov \, equation}). \end{aligned}$

With this stationary condition, the process noise covariance $\mathbf{Q}_k$ is computed as follows $\begin{aligned} \mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T \end{aligned}$

For one-dimensional problem the SDE representation of the GP is defined by the matrices $\mathbf{F}, \, \mathbf{L}, \, \mathbf{Q}_c, \, \mathbf{P}_0$ and $\mathbf{H}$. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.

using RxInfer, Random, Distributions, LinearAlgebra, Plots

Create state space model for GP regression

Here we create a state-space model $\begin{aligned} \mathbf{f}_k = \mathbf{A}_{k-1} \, \mathbf{f}_{k-1} + \mathbf{q}_{k-1}, \quad \mathbf{q}_{k-1} \sim \mathcal{N}(\mathbf{0}, \mathbf{Q}_{k-1}) \\ +y_k = \mathbf{H} \, \mathbf{f}(t_k) + \epsilon_k , \quad \epsilon_k \sim \mathcal{N}(0, \sigma^2_{noise}), \\ +\end{aligned}$ where $y_k$ is the noisy observation of the function $f$ at time $t_k$, and $\sigma^2_{noise}$ is the noise variance and assumed to be known.

@model function gp_regression(n, P∞, A, Q, H, σ²_noise)
+    f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)
+    f = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+    
+    f_prev = f_0
+
+    for i=1:n
+        f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])
+        y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)
+        f_prev = f[i]
+    end
+    return f, y
+end

Generate data

Random.seed!(10)
+n = 100
+σ²_noise = 0.04;
+t = collect(range(-2, 2, length=n)); #timeline
+f_true = sinc.(t); # true process
+f_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process
+
+pos = sort(randperm(75)[1:2:75]); 
+t_obser = t[pos]; # time where we observe data
+
+y_data = Array{Union{Float64,Missing}}(missing, n)
+for i in pos 
+    y_data[i] = f_noisy[i]
+end
+
+θ = [1., 1.]; # store [l, σ²]
+Δt = [t[1]]; # time difference
+append!(Δt, t[2:end] - t[1:end-1]);

Let's visualize our data

plot(t, f_true, label="True process f(t)")
+scatter!(t_obser, y_data[pos], label = "Noisy observations")
+xlabel!("t")
+ylabel!("f(t)")

Covariance function: Matern-3/2

The Matern is a stationary covariance function and defined as follows $\begin{aligned} k(\tau) = \sigma^2 \frac{2^{1-\nu}}{\Gamma(\nu)} \left(\frac{\sqrt{2\nu}\tau}{l} \right)^\nu K_\nu\left(\frac{\sqrt{2\nu}\tau}{l} \right) \end{aligned}$ where $\begin{aligned} \sigma^2: \text{the magnitude scale hyperparameter}\\ +l: \text{the characteristic length-scale}\\ +\nu: \text{the smoothness hyperparameter}\\ +K_\nu(.): \text{the modified Bessel function of the second kind}. \end{aligned}$ When we say the Matern-3/2, we mean $\nu=3/2$. The matrices for the state space model are computed as follows $\begin{aligned} \mathbf{F} = \begin{pmatrix} 0 & 1\\ +-\lambda^2 & -2\lambda \end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} 0 \\ 1 \end{pmatrix}, \quad \quad \mathbf{P}_\infty = \begin{pmatrix} \sigma^2 & 0 \\ 0 & \lambda^2\sigma^2 \end{pmatrix} ,\quad \quad \mathbf{H} = \begin{pmatrix} 1 & 0 \end{pmatrix}, \quad \quad Q_c = 4\lambda^3\sigma^2 \end{aligned}$ where $\lambda = \frac{\sqrt{3}}{l} $. From these matrices, we can define $\mathbf{A}_k$ and $\mathbf{Q}_k$.

λ = sqrt(3)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 1.];
+H = [1., 0.];
+F = [0. 1.; -λ^2 -2λ]
+P∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_32 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Covariance function: Matern-5/2

Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:

\[\begin{aligned} +\mathbf{F} = \begin{pmatrix} +0 & 1 & 0\\ +0 & 0 & 1 \\ +-\lambda^3 & -3\lambda^2 & -3\lambda +\end{pmatrix} ,\quad \quad \mathbf{L} = \begin{pmatrix} +0 \\ 0 \\ 1 +\end{pmatrix}, \quad \quad \mathbf{H} = \begin{pmatrix} +1 & 0 & 0 +\end{pmatrix}, \quad \quad Q_c = \frac{16}{3} \sigma^2 \lambda^5, +\end{aligned}\]

where $\lambda = \sqrt{5} / l$. To find $\mathbf{P}_\infty$, we solve the Lyapunov equation

\[\begin{aligned} +\frac{d\mathbf{P}_\infty}{dt} = \mathbf{F} \mathbf{P}_\infty + \mathbf{P}_\infty \mathbf{F}^T + \mathbf{L} \mathbf{Q}_c \mathbf{L}^T = 0, +\end{aligned}\]

of which the solution is

\[\begin{aligned} +vec(\mathbf{P}_\infty) = (\mathbf{I} \otimes \mathbf{F} + \mathbf{F}\otimes\mathbf{I})^{-1}\, vec(-\mathbf{L}Q_c\mathbf{L}^T) +\end{aligned}\]

where $vec(.)$ is the vectorization operator and $\otimes$ denotes the Kronecker product. Now we can find $\mathbf{A}_k$ and $\mathbf{Q}_k$

\[\begin{aligned} +\mathbf{A}_k = \exp{(\mathbf{F}\Delta t_k)} +\end{aligned}\]

\[\begin{aligned} +\mathbf{Q}_k = \mathbf{P}_\infty - \mathbf{A}_k \mathbf{P}_\infty \mathbf{A}_k^T +\end{aligned}\]

λ = sqrt(5)/θ[1];
+#### compute matrices for the state-space model ######
+L = [0., 0., 1.];
+H = [1., 0., 0.];
+F = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]
+Qc = 16/3 * θ[2] * λ^5;
+
+I = diageye(3) ; 
+vec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); 
+P∞ = reshape(vec_P,3,3);
+A = [exp(F * i) for i in Δt]; 
+Q = [P∞ - i*P∞*i' for i in A];
result_52 = infer(
+    model = gp_regression(n, P∞, A, Q, H, σ²_noise),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (f, f_0)
+  Predictions      | available for (y)

Result

slicedim(dim) = (a) -> map(e -> e[dim], a)
+
+plot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M32", title = "Matern-3/2", legend =false, lw = 2)
+plot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label ="Approx. process_M52",legend = :bottomleft, title = "GPRegression by SSM", lw = 2)
+plot!(t, f_true,label="true process", lw = 2)
+scatter!(t_obser, f_noisy[pos], label="Observations")
+xlabel!("t")
+ylabel!("f(t)")

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.

diff --git a/v2.16.2/examples/advanced_examples/Global Parameter Optimisation/index.html b/v2.16.2/examples/advanced_examples/Global Parameter Optimisation/index.html new file mode 100644 index 000000000..d4cdb60e2 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Global Parameter Optimisation/index.html @@ -0,0 +1,497 @@ + +Global Parameter Optimisation · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Global Parameter Optimisation

This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.

By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Univariate State Space Model

Let us try use the following simple state space model:

\[\begin{aligned} + {x}_t &= {x}_{t-1} + c \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, p \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Our goal is to optimize parameters $c$ and ${m_{{x}_0}}$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)
+    
+    x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n)
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ x_prev + c
+        y[i] ~ NormalMeanVariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+
+    return x, y
+end
rng = MersenneTwister(42)
+
+P      = 1.0
+n      = 250
+c_real = -5.0
+data   = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);
# c[1] is C
+# c[2] is μ0
+function f(c)
+    x0_prior = NormalMeanVariance(c[2], 100.0)
+    result = infer(
+        model = smoothing(n, x0_prior, c[1], P), 
+        data  = (y = data,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
using Optim
res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     3.651509e+02     1.001412e+03
+ * time: 0.023805856704711914
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     3.645772e+02
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.18e-06 ≰ 0.0e+00
+    |x - x'|/|x'|          = 2.30e-07 ≰ 0.0e+00
+    |f(x) - f(x')|         = 9.13e-07 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00
+    |g(x)|                 = 2.56e-06 ≤ 1.0e-03
+
+ * Work counters
+    Seconds run:   6  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    67
+    ∇f(x) calls:   67
res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)
2-element Vector{Float64}:
+  1.0007749243942134
+ -5.14368311177876
println("Real value vs Optimized")
+println("Real:      ", [ 1.0, c_real ])
+println("Optimized: ", res.minimizer)
Real value vs Optimized
+Real:      [1.0, -5.0]
+Optimized: [1.0007749243942134, -5.14368311177876]

Multivariate state space model

Let us consider the multivariate state space model:

\[\begin{aligned} + \mathbf{x}_t &\sim \mathcal{N}\left(\mathbf{Ax}_{t-1}, \mathbf{Q} \right) \\ + \mathbf{y}_t &\sim \mathcal{N}\left(\mathbf{x}_{t}, \mathbf{P} \right) +\end{aligned}\]

with prior

\[\begin{aligned} +\mathbf{x}_0 \sim \mathcal{N}(\mathbf{m_{{x}_0}}, \mathbf{V_{{x}_0}})\ +\end{aligned}\]

and transition matrix

\[\begin{aligned} +\mathbf{A} = \begin{bmatrix} \cos\theta & -\sin\theta \\ \sin\theta & \cos\theta \end{bmatrix} +\end{aligned}\]

Covariance matrices $\mathbf{V_{{x}_0}}$, $\mathbf{P}$ and $\mathbf{Q}$ are known. Our goal is to optimize parameters $\mathbf{m_{{x}_0}}$ and $\theta$.

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots
@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)
+    
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    
+    x_prev = x_prior
+    
+    A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)
+        y[i] ~ MvNormalMeanCovariance(x[i], P)
+        
+        x_prev = x[i]
+    end
+    
+end
# Generate data
+function generate_rotate_ssm_data()
+    rng = MersenneTwister(1234)
+
+    θ = π / 8
+    A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+    Q = Matrix(Diagonal(1.0 * ones(2)))
+    P = Matrix(Diagonal(1.0 * ones(2)))
+
+    n = 300
+
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(x[i], Q))
+        
+        x_prev = x[i]
+    end
+
+    return θ, A, Q, P, n, x, y
+end
generate_rotate_ssm_data (generic function with 1 method)
θ, A, Q, P, n, x, y = generate_rotate_ssm_data();
px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+
+plot(px, size = (1200, 450))

function f(θ)
+    x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))
+    result = infer(
+        model = rotate_ssm(n, θ[1], x0, Q, P), 
+        data  = (y = y,), 
+        free_energy = true
+    )
+    return result.free_energy[end]
+end
f (generic function with 1 method)
res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))
Iter     Function value   Gradient norm 
+     0     2.192003e+04     9.032537e+04
+ * time: 5.1975250244140625e-5
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.161372e+03
+
+ * Found with
+    Algorithm:     L-BFGS
+
+ * Convergence measures
+    |x - x'|               = 5.09e-09 ≰ 0.0e+00
+    |x - x'|/|x'|          = 4.48e-10 ≰ 0.0e+00
+    |f(x) - f(x')|         = 0.00e+00 ≤ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14
+    |g(x)|                 = 5.63e-07 ≰ 1.0e-12
+
+ * Work counters
+    Seconds run:   19  (vs limit Inf)
+    Iterations:    9
+    f(x) calls:    58
+    ∇f(x) calls:   58
println("Real value vs Optimized")
+println("Real:      ", θ)
+println("Optimized: ", res.minimizer[1])
+
+@show sin(θ), sin(res.minimizer[1])
+@show cos(θ), cos(res.minimizer[1])
Real value vs Optimized
+Real:      0.39269908169872414
+Optimized: 0.3929332481380117
+(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)
+(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)
+(0.9238795325112867, 0.9237898955654058)
x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))
+
+result = infer(
+    model = rotate_ssm(n, res.minimizer[1], x0, Q, P), 
+    data  = (y = y,), 
+    free_energy = true
+)
+
+xmarginals = result.posteriors[:x]
+
+px = plot()
+
+px = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = "real₁")
+px = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = "real₂")
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "inf₁")
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "inf₂")
+
+plot(px, size = (1200, 450))

Learning Kalman filter with LSTM driven dynamic

In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example.

Our objective is to compute the marginal posterior distribution of the latent (hidden) state $x_k$ at each time step $k$, considering the history of measurements up to that time step:

\[ +p(x_k | y_{1:k}). +$$ + +The above expression represents the probability distribution of the latent state $x_k$ given the measurements $y_{1:k}$ up to time step $k$. + +```julia +using RxInfer, BenchmarkTools, Flux, ReverseDiff, Random, Plots, LinearAlgebra, ProgressMeter, JLD, StableRNGs +``` + + + +### Generate data + +```julia +# Lorenz system equations to be used to generate dataset +Base.@kwdef mutable struct Lorenz + dt::Float64 + σ::Float64 + ρ::Float64 + β::Float64 + x::Float64 + y::Float64 + z::Float64 +end + +function step!(l::Lorenz) + dx = l.σ * (l.y - l.x); l.x += l.dt * dx + dy = l.x * (l.ρ - l.z) - l.y; l.y += l.dt * dy + dz = l.x * l.y - l.β * l.z; l.z += l.dt * dz +end +; +``` + + +```julia +# Dataset +rng = StableRNG(999) + +ordered_dataset = [] +ordered_parameters = [] +for σ = 11:15 + for ρ = 23:27 + for β_nom = 6:9 + attractor = Lorenz(0.02, σ, ρ, β_nom/3.0, 1, 1, 1) + noise_free_data = [[1.0, 1.0, 1.0]] + for i=1:99 + step!(attractor) + push!(noise_free_data, [attractor.x, attractor.y, attractor.z]) + end + push!(ordered_dataset, noise_free_data) + push!(ordered_parameters, [σ, ρ, β_nom/3.0]) + end + end +end + +new_order = collect(1:100) +shuffle!(rng,new_order) + +dataset = [] # noisy dataset +noise_free_dataset = [] # noise free dataset +lorenz_parameters = [] + +for i in new_order + local data = [] + push!(noise_free_dataset, ordered_dataset[i]) + push!(lorenz_parameters, ordered_parameters[i]) + for nfd in ordered_dataset[i] + push!(data,nfd+randn(rng,3)) + end + push!(dataset, data) +end + +trainset = dataset[1:60] +validset = dataset[61:80] +testset = dataset[81:end] + +noise_free_trainset = noise_free_dataset[1:60] +noise_free_validset = noise_free_dataset[61:80] +noise_free_testset = noise_free_dataset[81:end] +; +``` + + + +### Data visualization + +```julia +one_nonoise=noise_free_trainset[1] +one=trainset[1] +gx, gy, gz = zeros(100), zeros(100), zeros(100) +rx, ry, rz = zeros(100), zeros(100), zeros(100) +for i=1:100 + rx[i], ry[i], rz[i] = one[i][1], one[i][2], one[i][3] + gx[i], gy[i], gz[i] = one_nonoise[i][1], one_nonoise[i][2], one_nonoise[i][3] +end +p1=plot(rx,ry,label="Noise observations") +p1=plot!(gx,gy,label="True state") +xlabel!("x") +ylabel!("y") +p2=plot(rx,rz,label="Noise observations") +p2=plot!(gx,gz,label="True state") +xlabel!("x") +ylabel!("z") +p3=plot(ry,rz,label="Noise observations") +p3=plot!(gy,gz,label="True state") +xlabel!("y") +ylabel!("z") +plot(p1, p2, p3, size = (800, 200),layout=(1,3)) +``` + +![](../../assets/examples/Global Parameter Optimisation_22_1.png) + + +### Inference + + +We use the following state-space model representation: + +$$\begin{aligned} +x_k \sim p(x_k | x_{k-1}) \\ +y_k \sim p(y_k | x_k). +\end{aligned}\]

where $x_k \sim p(x_k | x_{k-1})$ represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system.

\[\begin{aligned} +A_{k-1}=NN(y_{k-1}) \\ +p(x_k | x_{k-1})=\mathcal{N}(x_k | A_{k-1}x_{k-1}, Q) \\ +p(y_k | x_k)=\mathcal{N}(y_k | Bx_k, R) +\end{aligned}\]

where $NN$ is the neural network. The input is the observation $y_{k-1}$, and output is the trasition matrix $A_{k-1}$. $B$ denote distortion or measurment matrix. $Q$ and $R$ are covariance matrices. Note that the hidden state $x_k$ comprises three coordinates, i.e. $x_k = (rx_k, ry_k, rz_k)$

By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.

# Neural Network model
+mutable struct NN
+    InputLayer
+    OutputLater
+    g
+    params
+    function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+        InputLayer = Dense(W1, b1, relu)
+        Lstm = LSTM(W2_1,W2_2,b2,s2_1)
+        OutputLayer = Dense(W3, b3)
+        g = Chain(InputLayer, OutputLayer);
+        new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))
+    end
+end

Model specification

Note that we treat the trasition matrix $A_{k-1}$ as time-varying.

#State Space Model
+@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)
+    x = randomvar(n)
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior_mean = zeros(3)
+    x_prior_cov  = Matrix(Diagonal(ones(3)))
+    
+    x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)
+    y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }
+    
+    for i in 2:n
+        x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }
+        y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }
+    end
+    
+    return x, y
+end

We set distortion matrix $B$ and the covariance matrices $Q$ and $R$ as identity matrix.

Q = Matrix(Diagonal(ones(3)))*2
+B = Matrix(Diagonal(ones(3)))
+R = Matrix(Diagonal(ones(3)))
+;

We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix $A$ output by the neural network. And the $A$ is treated as a datavar in the inference function.

function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    n = length(data)
+    neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])
+    return As
+end
get_matrix_AS (generic function with 1 method)

The weights of neural network $NN$ are initialized as follows:

# Initial model parameters
+W1, b1 = randn(5, 3)./100, randn(5)./100
+W2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)
+W3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100
+;

Before network training, we show the inference results for the hidden states:

# Performance on an instance from the testset before training
+index = 1
+data=testset[index]
+n=length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300))

Training network

In this part, we use the Free Energy as the objective function to optimize the weights of network.

# free energy objective to be optimized during training
+function fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+    fe_ = 0
+    for train_instance in trainset
+        result = infer(
+            model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), 
+            data  = (y = train_instance, ), 
+            returnvars = (x = KeepLast(), ),
+            free_energy = true
+        )
+        fe_ += result.free_energy[end]
+    end
+    return fe_
+end
fe_tot_est (generic function with 1 method)

Training

# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights
+# Uncomment the following code to train the network manually
+# opt = Flux.Optimise.RMSProp(0.006, 0.95)
+# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)
+# @showprogress for epoch in 1:800
+#     grads = ReverseDiff.gradient(fe_tot_est, params);
+#     for i=1:length(params)
+#         Flux.Optimise.update!(opt,params[i],grads[i])
+#     end
+# end

Test

Import the weights of neural network that we have trained.

W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load("../data/nn_prediction/weights.jld")["data"];
# Performance on an instance from the testset after training
+index = 1
+data = testset[index]
+n = length(data)
+result = infer(
+    model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), 
+    data  = (y = data, ), 
+    returnvars = (x = KeepLast(), ),
+    free_energy = true
+)
+x_est=result.posteriors[:x]
+
+gx, gy, gz = zeros(100), zeros(100), zeros(100)
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+
+for i=1:100
+    gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+
+p1 = plot(rx,label="Hidden state rx")
+p1 = plot!(rx_est_m,label="Inferred states", ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Hidden state ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Hidden state rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index]), label="Observations", markersize=1.0)
+
+plot(p1, p2, p3, size = (1000, 300))

Prediction

In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill $k$ and estimate the future state at time $k+1$, $k+2$, $\dots$,$k+T$.

We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.

\[\begin{aligned} +A_{k}=NN(x_{k}) \\ +p(x_{k+1} | x_{k})=\mathcal{N}(x_{k+1} | A_{k}x_{k}, Q) \\ +\end{aligned}\]

#Define the prediction function
+multiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))
+sumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)
+
+function runForward(A,B,Q,R,mh_old,Vh_old)
+    mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)
+    mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)
+end
+
+function g_predict(mh_old,Vh_old,Q)
+    neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)
+    # Flux.reset!(neural)
+    As  = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])
+    As = As[1]
+    return runForward(As,B,Q,R,mh_old,Vh_old), As
+end
g_predict (generic function with 1 method)

After $k=75$, the observations are not available, and we predict the future state from $k=76$ to the end

tt = 75
+mh = mean(x_est[tt])
+Vh = cov(x_est[tt])
+mo_list, Vo_list, A_list = [], [], [] 
+inv_Q = inv(Q)
+for t=1:100-tt
+    (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)
+    push!(mo_list, mo)
+    push!(Vo_list, Vh)
+    push!(A_list, A_t)
+    global mh = mo
+    global Vh = Vo
+end
# Prediction visualization
+rx, ry, rz = zeros(100), zeros(100), zeros(100)
+rx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)
+rx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)
+for i=1:tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]
+end
+for i=tt+1:100
+    ii=i-tt
+    rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]
+    rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]
+    rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]
+end
+p1 = plot(rx,label="Ground truth rx")
+p1 = plot!(rx_est_m,label="Inffered state rx",ribbon=rx_est_var)
+p1 = scatter!(first.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+p2 = plot(ry,label="Ground truth ry")
+p2 = plot!(ry_est_m,label="Inferred states", ribbon=ry_est_var)
+p2 = scatter!(getindex.(testset[index][1:tt], 2), label="Observations", markersize=1.0)
+
+p3 = plot(rz,label="Ground truth rz")
+p3 = plot!(rz_est_m,label="Inferred states", ribbon=rz_est_var)
+p3 = scatter!(last.(testset[index][1:tt]), label="Observations", markersize=1.0)
+
+
+plot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)

diff --git a/v2.16.2/examples/advanced_examples/Infinite Data Stream/index.html b/v2.16.2/examples/advanced_examples/Infinite Data Stream/index.html new file mode 100644 index 000000000..f5b55c259 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Infinite Data Stream/index.html @@ -0,0 +1,169 @@ + +Infinite Data Stream · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Infinite Data Stream

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:

using RxInfer, Plots, Random, StableRNGs

For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:

mutable struct Environment
+    rng                   :: AbstractRNG
+    current_state         :: Float64
+    observation_precision :: Float64
+    history               :: Vector{Float64}
+    observations          :: Vector{Float64}
+    
+    Environment(current_state, observation_precision; seed = 123) = begin 
+         return new(StableRNG(seed), current_state, observation_precision, [], [])
+    end
+end
+
+function getnext!(environment::Environment)
+    environment.current_state = environment.current_state + 1.0
+    nextstate  = 10sin(0.1 * environment.current_state)
+    observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))
+    push!(environment.history, nextstate)
+    push!(environment.observations, observation)
+    return observation
+end
+
+function gethistory(environment::Environment)
+    return environment.history
+end
+
+function getobservations(environment::Environment)
+    return environment.observations
+end
getobservations (generic function with 1 method)

Model specification

We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:

@model function kalman_filter()
+    
+    # Prior for the previous state
+    x_prev_mean = datavar(Float64)
+    x_prev_var  = datavar(Float64)
+    
+    x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)
+    
+    # Prior for the observation noise
+    τ_shape = datavar(Float64)
+    τ_rate  = datavar(Float64)
+    
+    τ ~ Gamma(shape = τ_shape, rate = τ_rate)
+    
+    # Random walk with fixed precision
+    x_current ~ Normal(mean = x_prev, precision = 1.0)
+    
+    # Noisy observation
+    y = datavar(Float64)
+    y ~ Normal(mean = x_current, precision = τ)
+    
+end
+
+# We assume the following factorisation between variables 
+# in the variational distribution
+@constraints function filter_constraints()
+    q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)
+end
filter_constraints (generic function with 1 method)

Prepare environment

initial_state         = 0.0
+observation_precision = 0.1
0.1

After we have created the environment we can observe how our signal behaves:

testenvironment = Environment(initial_state, observation_precision);
+
+animation = @animate for i in 1:100
+    getnext!(testenvironment)
+    
+    history = gethistory(testenvironment)
+    observations = getobservations(testenvironment)
+    
+    p = plot(size = (1000, 300))
+    
+    p = plot!(p, 1:i, history[1:i], label = "Hidden signal")
+    p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = "Observation")
+end
+
+gif(animation, "../pics/infinite-data-stream.gif", fps = 24, show_msg = false);

Filtering on static dataset

RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:

n                  = 300
+static_environment = Environment(initial_state, observation_precision);
+
+for i in 1:n
+    getnext!(static_environment)
+end
+
+static_history      = gethistory(static_environment)
+static_observations = getobservations(static_environment);
+static_datastream   = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
function run_static(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        keephistory   = 10_000,
+        historyvars   = (x_current = KeepLast(), τ = KeepLast()),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        free_energy   = true,
+        autostart     = true,
+    )
+    
+    return engine
+end
run_static (generic function with 1 method)
result = run_static(static_environment, static_datastream);
static_inference = @animate for i in 1:n
+    estimated = result.history[:x_current]
+    p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = "Estimation")
+    p = plot!(static_history[1:i], label = "Real states")    
+    p = scatter!(static_observations[1:i], ms = 2, label = "Observations")
+    p = plot(p, size = (1000, 300), legend = :bottomright)
+end
+
+gif(static_inference, "../pics/infinite-data-stream-inference.gif", fps = 24, show_msg = false);

plot(result.free_energy_history, label = "Bethe Free Energy (averaged)")

Filtering on realtime dataset

Next lets create a "real" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:

function run_and_plot(environment, datastream)
+    
+    # `@autoupdates` structure specifies how to update our priors based on new posteriors
+    # For example, every time we have updated a posterior over `x_current` we update our priors
+    # over `x_prev`
+    autoupdates = @autoupdates begin 
+        x_prev_mean, x_prev_var = mean_var(q(x_current))
+        τ_shape = shape(q(τ))
+        τ_rate = rate(q(τ))
+    end
+    
+    posteriors = []
+    
+    plotfn = (q_current) -> begin 
+        IJulia.clear_output(true)
+        
+        push!(posteriors, q_current)
+
+        p = plot(mean.(posteriors), ribbon = var.(posteriors), label = "Estimation")
+        p = plot!(gethistory(environment), label = "Real states")    
+        p = scatter!(getobservations(environment), ms = 2, label = "Observations")
+        p = plot(p, size = (1000, 300), legend = :bottomright)
+
+        display(p)
+    end
+    
+    engine = infer(
+        model         = kalman_filter(),
+        constraints   = filter_constraints(),
+        datastream    = datastream,
+        autoupdates   = autoupdates,
+        returnvars    = (:x_current, ),
+        initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),
+        iterations    = 10,
+        autostart     = false,
+    )
+    
+    qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)
+    
+    RxInfer.start(engine)
+    
+    return engine
+end
run_and_plot (generic function with 1 method)
# This example runs in our documentation pipeline, which does not support "real-time" execution context
+# We skip this code if run not in Jupyter notebook (see below an example with gif)
+engine = nothing 
+if isdefined(Main, :IJulia)
+    timegen      = 41 # 41 ms
+    environment  = Environment(initial_state, observation_precision);
+    observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations
+    datastream   = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));
+    engine = run_and_plot(environment, datastream)
+end;

The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:

if !isnothing(engine) && isdefined(Main, :IJulia)
+    RxInfer.stop(engine)
+    IJulia.clear_output(true)
+end;
diff --git a/v2.16.2/examples/advanced_examples/Nonlinear Sensor Fusion/index.html b/v2.16.2/examples/advanced_examples/Nonlinear Sensor Fusion/index.html new file mode 100644 index 000000000..83d9a72a5 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/Nonlinear Sensor Fusion/index.html @@ -0,0 +1,140 @@ + +Nonlinear Sensor Fusion · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Nonlinear Sensor Fusion

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers
+using DataFrames, DelimitedFiles, StableRNGs

In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.

A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.

To illustrate these noisy measurements, the engineers decided to plot them:

# fetch measurements
+beacon_locations = readdlm("../data/sensor_fusion/beacons.txt")
+distances = readdlm("../data/sensor_fusion/distances.txt")
+position = readdlm("../data/sensor_fusion/position.txt")
+nr_observations = size(distances, 1);
# plot beacon and actual location of WALL-E
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+xlabel!("longitude [m]"), ylabel!("latitude [m]")
+
+# plot noisy distance measurements
+p2 = plot(distances, legend=:topleft, linewidth=3, label=["distance to beacon 1" "distance to beacon 2" "distance to beacon 3"])
+xlabel!("time [sec]"), ylabel!("distance [m]")
+
+plot(p1, p2, size=(1200, 500))

In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time $t$, denoted by $z_t$, follows a 2-dimensional normal random walk:

\[\begin{aligned} + & p(z_t \mid z_{t - 1}) = \mathcal{N}(z_t \mid z_{t-1},~\mathrm{I}_{2}),\\ +\end{aligned}\]

where $\mathrm{I}_2$ denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements $y_t$ as a noisy set of the distances between WALL-E and the beacons, specified by $s_i$:

\[\begin{aligned} + & p(y_t \mid z_t) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~\mathrm{I}_{3}\! \right . \right)\!. +\end{aligned}\]

The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:

# function to compute distance to beacons
+function compute_distances(z)    
+    distance1 = norm(z - beacon_locations[1,:])
+    distance2 = norm(z - beacon_locations[2,:])
+    distance3 = norm(z - beacon_locations[3,:])
+    distances = [distance1, distance2, distance3]
+end;
@model function random_walk_model(nr_observations)
+    
+    # specify precision matrices
+    W = diageye(2)
+    R = diageye(3)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], W)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;

Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.

Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:

    compute_distances(z) -> CVI(..., Val(false), ...)

This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.

@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)
+    compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)
+end;

NOTE: You can try out different meta for approximating the nonlinearity, e.g.

@meta function random_walk_linear_meta()
+    compute_distances(z) -> Linearization()
+end;
@meta function random_walk_unscented_meta()
+    compute_distances(z) -> Unscented()
+end;
results_fast = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),
+);
results_accuracy = infer(
+    model = random_walk_model(nr_observations),
+    meta = random_walk_model_meta(1000, 100, StableRNG(42)),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = false,
+    returnvars = (z = KeepLast(),),
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),
+);

After running this fast inference procedure, the engineers plot the results and evaluate the performance:

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_fast.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Fast (1 sample, 3 iterations)"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot beacon and actual and estimated location of WALL-E (accurate inference)
+p2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_accuracy.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"), title!("Accurate (1000 samples, 100 iterations)"); p2.series_list[end][:label] = "estimated location ±2σ"
+
+plot(p1, p2, size=(1200, 500))

The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, $Q$ and $R$ respectively. They did this by adding Wishart priors to those matrices:

\[\begin{aligned} + & p(Q) = \mathcal{W}(Q \mid 3, \mathrm{I}_2), \\ + & p(R) = \mathcal{W}(R \mid 4, \mathrm{I}_3), \\ + & p(z_t \mid z_{t - 1}, Q) = \mathcal{N}(z_t \mid z_{t-1}, Q^{-1}),\\ + & p(y_t \mid z_t, R) = \mathcal{N} \left (y_t \left \vert \begin{bmatrix} \| z_{t} - s_{1}\| \\ \|z_{t} - s_{2}\| \\ \|z_{t} - s_{3}\|\end{bmatrix}\!,~R^{-1}\! \right . \right)\!. +\end{aligned}\]

@model function random_walk_model_wishart(nr_observations)
+
+    # allocate locations and observations
+    z = randomvar(nr_observations)
+    y = datavar(Vector{Float64}, nr_observations)
+
+    # set priors on precision matrices
+    Q ~ Wishart(3, diageye(2))
+    R ~ Wishart(4, diageye(3))
+
+    # specify initial estimates of the location
+    z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) 
+    y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))
+
+    # loop over time steps
+    for t in 2:nr_observations
+
+        # specify random walk state transition model
+        z[t] ~ MvNormalMeanPrecision(z[t-1], Q)
+
+        # specify non-linear distance observations model
+        y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)
+        
+    end
+
+end;
meta = @meta begin 
+    compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)
+end;

Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:

constraints = @constraints begin
+    q(z, Q, R) = q(z)q(Q)q(R)
+end;

The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.

results_wishart = infer(
+    model = random_walk_model_wishart(nr_observations),
+    data = (y = [distances[t,:] for t in 1:nr_observations],),
+    iterations = 100,
+    free_energy = true,
+    returnvars = (z = KeepLast(),),
+    constraints = constraints,
+    meta = meta,
+    initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),
+    initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))
+);

They plot the new estimates and the performance over time, and luckily WALL-E is found!

# plot beacon and actual and estimated location of WALL-E (fast inference)
+p1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label="beacon locations")
+plot!(position[1,:], position[2,:], label="actual location", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)
+map(posterior -> covellipse!(mean(posterior), cov(posterior), color="red", label="", n_std=2), results_wishart.posteriors[:z])
+xlabel!("longitude [m]"), ylabel!("latitude [m]"); p1.series_list[end][:label] = "estimated location ±2σ"
+
+# plot bethe free energy performance
+p2 = plot(results_wishart.free_energy, label = "")
+xlabel!("iteration"), ylabel!("Bethe free energy [nats]")
+
+plot(p1, p2, size=(1200, 500))

diff --git a/v2.16.2/examples/advanced_examples/overview/index.html b/v2.16.2/examples/advanced_examples/overview/index.html new file mode 100644 index 000000000..73cf18b93 --- /dev/null +++ b/v2.16.2/examples/advanced_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Advanced examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Advanced examples contain more complex inference problems.

  • Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.
  • Advanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.
  • Assessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.
  • Chance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.
  • Conjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.
  • Global Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.
  • Solve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.
  • Infinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.
  • Nonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors
diff --git a/v2.16.2/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html b/v2.16.2/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html new file mode 100644 index 000000000..98519d956 --- /dev/null +++ b/v2.16.2/examples/basic_examples/Bayesian Linear Regression Tutorial/index.html @@ -0,0 +1,550 @@ + +Bayesian Linear Regression Tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Bayesian Linear Regression Tutorial

This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM

Part 1. Bayesian Linear Regression

John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

He records the speed and fuel consumption for the urban road which is the xdata and ydata.

function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = infer(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (a, b)
+  Free Energy:     | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184
+.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821
+, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]

He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a\mid y)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0,Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b)", c=1, legend = :topleft)
+prb = vline!(prb, [ 25 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"p(b\mid y)", c=2, legend = :topleft)
+psb = vline!(psb, [ 25 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

a = results.posteriors[:a]
+b = results.posteriors[:b]
+
+println("Real a: ", 0.5, " | Estimated a: ", mean_var(a), " | Error: ", abs(mean(a) - 0.5))
+println("Real b: ", 25.0, " | Estimated b: ", mean_var(b), " | Error: ", abs(mean(b) - 25.0))
Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err
+or: 0.001490188462705988
+Real b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error
+: 0.18735789804394898

Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:

# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Univariate regression with unknown noise

Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. $\begin{aligned} p(y_n \mid a, b, s) &= \mathcal{N}(y_n \mid ax_n + b, s)\\ +p(s) &= \mathcal{IG}(s\mid\alpha, \theta)\\ +p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ +p(b) &= \mathcal{N}(b \mid m_b, v_b) \end{aligned}$

@model function linear_regression_unknown_noise(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+    s ~ InverseGamma(1.0, 1.0)
+    
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    y .~ Normal(mean = a .* x .+ b, variance = s)
+end
x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)
+
+scatter(x_data_un, y_data_un, title = "Dateset with unknown noise (mountain road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")

To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results_unknown_noise = infer(
+    model           = linear_regression_unknown_noise(length(x_data_un)), 
+    data            = (y = y_data_un, x = x_data_un), 
+    initmessages    = (b = NormalMeanVariance(0.0, 100.0), ), 
+    returnvars      = (a = KeepLast(), b = KeepLast(), s = KeepLast()), 
+    iterations      = 20,
+    constraints     = MeanField(),
+    initmarginals   = (s = vague(InverseGamma), ),
+    free_energy     = true
+)
Inference results:
+  Posteriors       | available for (a, b, s)
+  Free Energy:     | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125
+.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56
+, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]

Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:

plot(results_unknown_noise.free_energy, title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)

Below he visualizes the obtained posterior distributions for parameters:

pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L"Prior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(a)$", c=1,)
+pra = vline!(pra, [ 0.5 ], label=L"True $a$", c = 3)
+psa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L"Posterior for $a$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(a)$", c=2,)
+psa = vline!(psa, [ 0.5 ], label=L"True $a$", c = 3)
+
+plot(pra, psa, size = (1000, 200), xlabel=L"$a$", ylabel=L"$p(a)$", ylims=[0, Inf])

prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L"Prior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(b)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 25.0 ], label=L"True $b$", c = 3)
+psb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L"Posterior for $b$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(b)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 25.0 ], label=L"True $b$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$b$", ylabel=L"$p(b)$", ylims=[0, Inf])

prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L"Prior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$p(s)$", c=1, legend = :topleft)
+prb = vline!(prb, [ 200 ], label=L"True $s$", c = 3)
+psb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L"Posterior for $s$ parameter", fillalpha=0.3, fillrange = 0, label=L"$q(s)$", c=2, legend = :topleft)
+psb = vline!(psb, [ 200 ], label=L"True $s$", c = 3)
+
+plot(prb, psb, size = (1000, 200), xlabel=L"$s$", ylabel=L"$p(s)$", ylims=[0, Inf])

He sees that in the presence of more noise the inference result is more uncertain about the actual values for $a$ and $b$ parameters.

John samples $a$ and $b$ and plot many possible regression lines on the same plot:

as = rand(results_unknown_noise.posteriors[:a], 100)
+bs = rand(results_unknown_noise.posteriors[:b], 100)
+p = scatter(x_data_un, y_data_un, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)
+end
+
+plot(p, size = (900, 400))

From this plot John can see that many lines do fit the data well and there is no definite "best" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.

Multivariate linear regression

In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.

@model function linear_regression_multivariate(dim, nr_samples)
+    a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))
+    b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))
+    W ~ InverseWishart(dim + 2, 100 * diageye(dim))
+
+    # Here is a small trick to make the example work
+    # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`
+    x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)
+    y = datavar(Vector{Float64}, nr_samples)
+    z = randomvar(nr_samples)
+
+    z .~ x .* a .+ b
+    y .~ MvNormal(mean = z, covariance = W)
+
+end

After received all the measurement records, he plots the measurements and performance index:

dim_mv = 6
+nr_samples_mv = 50
+rng_mv = StableRNG(42)
+a_mv = randn(rng_mv, dim_mv)
+b_mv = 10 * randn(rng_mv, dim_mv)
+v_mv = 100 * rand(rng_mv, dim_mv)
+
+x_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));
p = plot(title = "Multivariate linear regression", legend = :topleft)
+
+plt = palette(:tab10)
+
+data_set_label = [""]
+
+for k in 1:dim_mv
+    global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = "Measurement #$k", ms = 2, color = plt[k])
+end
+xlabel!(L"$x$")
+ylabel!(L"$y$")
+p

Before this data can be used to perform inference, John needs to change its format slightly.

x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)
+y_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);
results_mv = infer(
+    model           = linear_regression_multivariate(dim_mv, nr_samples_mv),
+    data            = (y = y_data_mv_processed, x = x_data_mv_processed),
+    initmarginals   = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),
+    initmessages    = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),
+    returnvars      = (a = KeepLast(), b = KeepLast(), W = KeepLast()),
+    free_energy     = true,
+    iterations      = 50,
+    constraints     = MeanField()
+)
Inference results:
+  Posteriors       | available for (a, b, W)
+  Free Energy:     | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7
+22, 712.341, 700.865, 690.782, 682.505  …  664.434, 664.434, 664.434, 664.4
+34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]

Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.

p = plot(title = "Multivariate linear regression", legend = :topleft, xlabel=L"$x$", ylabel=L"$y$")
+
+# how many lines to plot
+r = 50
+
+i_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))
+i_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))
+
+plt = palette(:tab10)
+
+for k in 1:dim_mv
+    x_mv_k = x_data_mv[k]
+    y_mv_k = y_data_mv[k]
+
+    for i in 1:r
+        global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])
+    end
+
+    global p = scatter!(p, x_mv_k, y_mv_k, label = "Measurement #$k", ms = 2, color = plt[k])
+end
+
+# truncate the init step
+f = plot(results_mv.free_energy[2:end], title ="Bethe free energy convergence", label = nothing, xlabel = "Iteration", ylabel = "Bethe free energy [nats]") 
+
+plot(p, f, size = (1000, 400))

He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.

i_a_mv = results_mv.posteriors[:a]
+
+ps_a = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $a_{%$k}$", xlabel=L"$a_{%$k}$", ylabel=L"$p(a_{%$k})$", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])
+
+    local m_a_mv_k = mean(i_a_mv)[k]
+    local v_a_mv_k = std(i_a_mv)[k, k]
+    
+    _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(a_{%$k})$", c=2,)
+    _p = vline!(_p, [ a_mv[k] ], label=L"True $a_{%$k}$", c = 3)
+           
+    push!(ps_a, _p)
+end
+
+plot(ps_a...)

i_b_mv = results_mv.posteriors[:b]
+
+ps_b = []
+
+for k in 1:dim_mv
+    
+    local _p = plot(title = L"Estimated $b_{%$k}$", xlabel=L"$b_{%$k}$", ylabel=L"$p(b_{%$k})$", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])
+    local m_b_mv_k = mean(i_b_mv)[k]
+    local v_b_mv_k = std(i_b_mv)[k, k]
+
+    _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L"$q(b_{%$k})$", c=2,)
+    _p = vline!(_p, [ b_mv[k] ], label=L"Real $b_{%$k}$", c = 3)
+           
+    push!(ps_b, _p)
+end
+
+plot(ps_b...)

He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.

scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L"True $s_d$")
+scatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L"$\mathrm{E}[s_d] \pm \sigma$")
+plot!(; xlabel=L"Dimension $d$", ylabel="Variance", title="Estimated variance of the noise")

Part 2. Hierarchical Bayesian Linear Regression

Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro.

The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.

Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].

The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.

# https://www.machinelearningplus.com/linear-regression-in-julia/
+# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb

Understanding the Task

Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.

In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).

Now, let's explore the data and delve deeper into the problem involved.

dataset = CSV.read("../data/hbr/osic_pulmonary_fibrosis.csv", DataFrame);
describe(dataset)
7×7 DataFrame
+ Row │ variable       mean     min                        median   max     
+    ⋯
+     │ Symbol         Union…   Any                        Union…   Any     
+    ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ Patient                 ID00007637202177411956430           ID004266
+372 ⋯
+   2 │ Weeks          31.8618  -5                         28.0     133
+   3 │ FVC            2690.48  827                        2641.0   6399
+   4 │ Percent        77.6727  28.8776                    75.6769  153.145
+   5 │ Age            67.1885  49                         68.0     88      
+    ⋯
+   6 │ Sex                     Female                              Male
+   7 │ SmokingStatus           Currently smokes                    Never sm
+oke
+                                                               3 columns om
+itted
first(dataset, 5)
5×7 DataFrame
+ Row │ Patient                    Weeks  FVC    Percent  Age    Sex      Sm
+oki ⋯
+     │ String31                   Int64  Int64  Float64  Int64  String7  St
+rin ⋯
+─────┼─────────────────────────────────────────────────────────────────────
+─────
+   1 │ ID00007637202177411956430     -4   2315  58.2536     79  Male     Ex
+-sm ⋯
+   2 │ ID00007637202177411956430      5   2214  55.7121     79  Male     Ex
+-sm
+   3 │ ID00007637202177411956430      7   2061  51.8621     79  Male     Ex
+-sm
+   4 │ ID00007637202177411956430      9   2144  53.9507     79  Male     Ex
+-sm
+   5 │ ID00007637202177411956430     11   2069  52.0634     79  Male     Ex
+-sm ⋯
+                                                                1 column om
+itted

The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.

Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:

patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)
patientinfo (generic function with 1 method)
function patientchart(dataset, patient_id; line_kws = true)
+    info = patientinfo(dataset, patient_id)
+    x = info[!, "Weeks"]
+    y = info[!, "FVC"]
+
+    p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)
+    p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = "Weeks", ylabel = "FVC")
+    
+    if line_kws
+        # Use the `GLM.jl` package to estimate linear regression
+        linearFormulae = @formula(FVC ~ Weeks)
+        linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))
+        linearPredicted = predict(linearRegressor)
+        p = plot!(p, x, linearPredicted, color = :red, lw = 3)
+    end
+
+    return p
+end
patientchart (generic function with 1 method)
p1 = patientchart(dataset, "ID00007637202177411956430")
+p2 = patientchart(dataset, "ID00009637202177434476278")
+p3 = patientchart(dataset, "ID00010637202177584971671")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.

Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:

The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].

Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling

In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the "pooled model." On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the "unpooled model," where each patient has completely separate regression lines.

In this analysis, we will adopt a middle ground approach known as "Partial pooling." Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:

Mathematically, the model is described by the following equations:

\[\begin{equation} + \begin{aligned} + \mu_\alpha &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 250000.0) \\ + \sigma_\alpha &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mu_\beta &\sim \mathcal{N}(\mathrm{mean} = 0.0, \mathrm{variance} = 9.0) \\ + \sigma_\beta &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 1.36) \\ + \alpha_i &\sim \mathcal{N}(\mathrm{mean} = \mu_\alpha, \mathrm{precision} = \sigma_\alpha) \\ + \beta &\sim \mathcal{N}(\mathrm{mean} = \mu_\beta, \mathrm{precision} = \sigma_\beta) \\ + \sigma &\sim \mathcal{\Gamma}(\mathrm{shape} = 1.75, \mathrm{scale} = 45.54) \\ + \mathrm{FVC}_{ij} &\sim \mathcal{N}(\mathrm{mean} = \alpha_i + t \beta_i, \mathrm{precision} = \sigma) + \end{aligned} +\end{equation}\]

where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!

Implementing this model in RxInfer is pretty straightforward:

@model function partially_pooled(patient_codes, weeks)
+    μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β ~ Normal(mean = 0.0, var = 9.0)      # Prior for the mean of β (slope)
+    σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)
+    σ_β ~ Gamma(shape = 1.75, scale = 1.36)  # Prior for the precision of β (slope)
+
+    n_codes = length(patient_codes)            # Total number of data points
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    α = randomvar(n_patients)                # Individual intercepts for each patient
+    β = randomvar(n_patients)                # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution
+        β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54)   # Prior for the standard deviation of the error term
+    
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes) # Observed FVC measurements
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+end

Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.

@constraints function partially_pooled_constraints()
+    # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent
+    q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)
+    # Assume that `μ_α`, `σ_α`, `α` are jointly independent
+    q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)
+    # Assume that `μ_β`, `σ_β`, `β` are jointly independent
+    q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)
+    # Assume that `FVC_est`, `σ` are jointly independent
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_constraints (generic function with 1 method)

These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!

Inference in the model

A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.

Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.

patient_ids          = dataset[!, "Patient"] # get the column of all patients
+patient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));
+patient_code_column  = map(patient -> patient_code_encoder[patient], patient_ids)
+
+dataset[!, :PatientCode] = patient_code_column
+
+first(patient_code_encoder, 5)
5-element Vector{Pair{InlineStrings.String31, Int64}}:
+ "ID00197637202246865691526" => 85
+ "ID00388637202301028491611" => 160
+ "ID00341637202287410878488" => 142
+ "ID00020637202178344345685" => 9
+ "ID00305637202281772703145" => 127
function partially_pooled_inference(dataset)
+
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+
+    results = infer(
+        model = partially_pooled(patient_codes, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+            σ = vague(Gamma),
+            σ_α = vague(Gamma),
+            σ_β = vague(Gamma),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100
+    )
+    
+end
partially_pooled_inference (generic function with 1 method)

We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.

In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. 

partially_pooled_inference_results = partially_pooled_inference(dataset)
Inference results:
+  Posteriors       | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)

Checking the model

Inspecting the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)
+    local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))
+end

Looks like our model learned personalized alphas and betas for each patient!

Visualizing FVC decline curves for some patients

Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.

function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)
+    info            = patientinfo(dataset, patient_id)
+    patient_code_id = encoder[patient_id]
+
+    patient_α = results.posteriors[:α][patient_code_id]
+    patient_β = results.posteriors[:β][patient_code_id]
+
+    estimated_σ = inv(mean(results.posteriors[:σ]))
+    
+    predict_weeks = range(-12, 134)
+
+    predicted = map(predict_weeks) do week
+        pm = mean(patient_α) + mean(patient_β) * week
+        pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ
+        return pm, sqrt(pv)
+    end
+    
+    p = patientchart(dataset, patient_id; kwargs...)
+    
+    return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)
+end
patientchart_bayesian (generic function with 1 method)
p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430")
+p2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278")
+p3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184")
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

The results match our expectations perfectly! Let's highlight the observations:

  • The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.

  • The model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.

  • Additionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.

Computing the modified Laplace Log Likelihood and RMSE

As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.

To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:

\[\begin{equation} + \begin{aligned} + \sigma_{\mathrm{clipped}} &= \max(\sigma, 70) \\ + \delta &= \min(\vert \mathrm{FVC}_{\mathrm{true}} - \mathrm{FVC}_{\mathrm{pred}}\vert, 1000) \\ + \mathrm{metric} &= -\frac{\sqrt{2}\delta}{\sigma_{\mathrm{clipped}}} - \mathrm{ln}(\sqrt{2}\sigma_{\mathrm{clipped}}) \\ + \end{aligned} +\end{equation}\]

To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.

function FVC_predict(results)
+    return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s
+        return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)
+    end
+end
FVC_predict (generic function with 1 method)
function compute_rmse(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    return mean((dataset[!, "FVC"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)
+end
+
+function compute_laplace_log_likelihood(results, dataset)
+    FVC_predicted = FVC_predict(results)
+    sigma_c = std.(FVC_predicted)
+    sigma_c[sigma_c .< 70] .= 70
+    delta = abs.(mean.(FVC_predicted) .- dataset[!, "FVC"])
+    delta[delta .> 1000] .= 1000
+    return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))
+end
compute_laplace_log_likelihood (generic function with 1 method)
println("RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))")
RMSE: 124.0313266260767
+Laplace Log Likelihood: -6.15689374755478

What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!

Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.

Add layer to model hierarchy: Smoking Status

We can enhance the model by incorporating the column "SmokingStatus" as a pooling level, where model parameters will be partially pooled within the groups "Never smoked," "Ex-smoker," and "Currently smokes." To achieve this, we need to:

Encode the "SmokingStatus" column. Map the patient encoding to the corresponding "SmokingStatus" encodings. Refine and retrain the model with the additional hierarchical structure.

combine(groupby(dataset, "SmokingStatus"), nrow)
3×2 DataFrame
+ Row │ SmokingStatus     nrow
+     │ String31          Int64
+─────┼─────────────────────────
+   1 │ Ex-smoker          1038
+   2 │ Never smoked        429
+   3 │ Currently smokes     82
smoking_id_mapping   = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, "SmokingStatus"]))))
+smoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id
+    smoking_status = first(unique(patientinfo(dataset, patient_id)[!, "SmokingStatus"]))
+    return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]
+end)
+
+smoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));
@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)
+    μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)
+    μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)
+    σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+    σ_β_global ~ Gamma(shape = 1.75, scale = 1.36)  # Corresponds to half-normal with scale 3.0
+
+    n_codes = length(patient_codes) # Total number of data points
+    n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns
+    n_patients = length(unique(patient_codes)) # Number of unique patients in the data
+
+    μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern
+    μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern
+    
+    for i in 1:n_smoking_statuses
+        μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)
+        μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)
+    end
+    
+    α = randomvar(n_patients) # Individual intercepts for each patient
+    β = randomvar(n_patients) # Individual slopes for each patient
+
+    for i in 1:n_patients
+        α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)
+        β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)
+    end
+
+    σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0
+
+    FVC_est = randomvar(n_codes)
+    data = datavar(Int, n_codes)
+
+    for i in 1:n_codes
+        FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β
+        data[i] ~ Normal(mean = FVC_est[i], precision = σ)              # Likelihood of the observed FVC data
+    end
+    
+end
+
+@constraints function partially_pooled_with_smooking_constraints()
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)
+    q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)
+    q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)
+    q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)
+    q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)
+    q(FVC_est, σ) = q(FVC_est)q(σ) 
+end
partially_pooled_with_smooking_constraints (generic function with 1 method)
function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)
+    patient_codes = values(dataset[!, "PatientCode"])
+    weeks = values(dataset[!, "Weeks"])
+    FVC_obs = values(dataset[!, "FVC"]);
+    
+    return infer(
+        model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),
+        data = (data = FVC_obs, ),
+        options = (limit_stack_depth = 500, ),
+        constraints = partially_pooled_with_smooking_constraints(),
+        initmessages = (
+            α = vague(NormalMeanVariance),
+            β = vague(NormalMeanVariance),
+        ),
+        initmarginals = (
+            σ = Gamma(1.75, 45.54),
+            σ_α_global = Gamma(1.75, 45.54),
+            σ_β_global = Gamma(1.75, 1.36),
+        ),
+        returnvars = KeepLast(),
+        iterations = 100,
+    )
+end
partially_pooled_with_smoking (generic function with 2 methods)
partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);

Inspect the learned parameters

# Convert to `Normal` since it supports easy plotting with `StatsPlots`
+let 
+    local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)
+    local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)
+    local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])
+    local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])
+    local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])
+    local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])
+    
+    local p1 = plot(μ_α, title = "q(μ_α_global)", fill = 0, fillalpha = 0.2, label = false)
+    local p2 = plot(μ_β, title = "q(μ_β_global)", fill = 0, fillalpha = 0.2, label = false)
+    
+    local p3 = plot(title = "q(α)...", legend = false)
+    local p4 = plot(title = "q(β)...", legend = false)
+    
+    foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`
+    foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`
+    
+    local p5 = plot(title = "q(μ_α_smoking_status)...", legend = false)
+    local p6 = plot(title = "q(μ_β_smoking_status)...", legend = false)
+    
+    foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) 
+    foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)
+    
+    plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))
+end

Interpret smoking status model parameters

The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.

smoking_id_mapping
Dict{InlineStrings.String31, Int64} with 3 entries:
+  "Currently smokes" => 3
+  "Ex-smoker"        => 1
+  "Never smoked"     => 2
posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]
+
+println("Trend for")
+foreach(pairs(smoking_id_mapping)) do (key, id)
+    println("  $key: $(mean(posteriors_μ_β_smoking_status[id]))")
+end
Trend for
+  Currently smokes: 1.8157457671008241
+  Ex-smoker: -4.56516461765951
+  Never smoked: -4.446729680170274

Let's look at these curves for individual patients to help interpret these model results.

# Never smoked
+p1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00007637202177411956430") 
+# Ex-smoker
+p2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00009637202177434476278") 
+# Currently smokes
+p3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, "ID00011637202177653955184") 
+
+plot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))

Review patients that currently smoke

When plotting each patient with the smoking status "Currently smokes," we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.

Depending on the purpose of the model, we can proceed in different ways:

  • If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.

  • However, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the "Currently smokes" group's parameters closer to the global parameters, or even consider merging the group with "Ex-smokers." Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.

let 
+    local plots = []
+
+    for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==("Currently smokes"), dataset)[!, "Patient"]))
+        push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))
+    end
+
+    plot(plots..., size = (1200, 1200))
+end

Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level

We calculate the metrics for the updated model and compare to the original model.

println("RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))")
+println("Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))")
RMSE: 124.7845980866563
+Laplace Log Likelihood: -6.165346437287973

Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.

References

[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541

[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.

diff --git a/v2.16.2/examples/basic_examples/Coin Toss Model/index.html b/v2.16.2/examples/basic_examples/Coin Toss Model/index.html new file mode 100644 index 000000000..b7987c94a --- /dev/null +++ b/v2.16.2/examples/basic_examples/Coin Toss Model/index.html @@ -0,0 +1,42 @@ + +Coin toss model (Beta-Bernoulli) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Coin toss model (Beta-Bernoulli)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example, we are going to perform an exact inference for a coin toss model that can be represented as:

\[\begin{aligned} +p(\theta) &= \mathrm{Beta}(\theta|a, b),\\ +p(y_i|\theta) &= \mathrm{Ber}(y_i|\theta),\\ +\end{aligned}\]

where $y_i \in \{0, 1\}$ is a binary observation induced by Bernoulli likelihood while $\theta$ is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of $\theta$.

We start with importing all needed packages:

using RxInfer, Random

Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:

rng = MersenneTwister(42)
+n = 500
+θ_real = 0.75
+distribution = Bernoulli(θ_real)
+
+dataset = float.(rand(rng, Bernoulli(θ_real), n));
# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(4.0, 8.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+end
result = infer(
+    model = coin_model(length(dataset)), 
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
θestimated = result.posteriors[:θ]
Beta{Float64}(α=365.0, β=147.0)
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+plot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+vline!([θ_real], label="Real θ")

diff --git a/v2.16.2/examples/basic_examples/Hidden Markov Model/index.html b/v2.16.2/examples/basic_examples/Hidden Markov Model/index.html new file mode 100644 index 000000000..cd2c09edf --- /dev/null +++ b/v2.16.2/examples/basic_examples/Hidden Markov Model/index.html @@ -0,0 +1,132 @@ + +How to train your Hidden Markov Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

How to train your Hidden Markov Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate()
+;

In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment.

First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time $t$, let's call the estimate of the Roomba's position $s_t$.

However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call $A$.

Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.

At time $t$, we will call our observations $x_t$ and encode the mapping from the Roomba's position to the observations in a matrix we call $B$. $B$ also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:

\[\begin{aligned} + s_t & \sim \mathcal{C}at(A s_{t-1}),\\ + x_t & \sim \mathcal{C}at(B s_t).\\ +\end{aligned}\]

This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices $A$ and $B$ so we can use them to track the whereabouts of our little cleaning agent.

using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots

In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).

To generate our observation data, we'll follow these steps:

  1. Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.
  2. Determine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.
  3. Determine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.
  4. Repeat steps 2-3 for as many samples as we want.

The following code implements this process and generates our observation data:

"""
+    rand_vec(rng, distribution::Categorical)
+
+This function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.
+"""
+function rand_vec(rng, distribution::Categorical) 
+    k = ncategories(distribution)
+    s = zeros(k)
+    drawn_category = rand(rng, distribution)
+    s[drawn_category] = 1.0
+    return s
+end
+
+function generate_data(n_samples; seed = 42)
+    
+    rng = MersenneTwister(seed)
+    
+    # Transition probabilities 
+    state_transition_matrix = [0.9 0.0 0.1;
+                                                        0.0 0.9 0.1; 
+                                                        0.05 0.05 0.9] 
+    # Observation noise
+    observation_distribution_matrix = [0.9 0.05 0.05;
+                                                                         0.05 0.9 0.05;
+                                                                         0.05 0.05 0.9] 
+    # Initial state
+    s_initial = [1.0, 0.0, 0.0] 
+    
+    states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states
+    observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations
+    
+    s_prev = s_initial
+    
+    for t = 1:n_samples
+        s_probvec = state_transition_matrix * s_prev
+        states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))
+        obs_probvec = observation_distribution_matrix * states[t]
+        observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))
+        s_prev = states[t]
+    end
+    
+    return observations, states
+end
generate_data (generic function with 1 method)

We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.

# Test data
+N = 100
+x_data, s_data = generate_data(N);
+
+scatter(argmax.(s_data), leg=false, xlabel="Time",yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]))

Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the $A$ and $B$ matrices we can use MatrixDirichlet priors. For the $A$-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on $A$ with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on $B$. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.

Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!

# Model specification
+@model function hidden_markov_model(n)
+    
+    A ~ MatrixDirichlet(ones(3,3))
+    B ~ MatrixDirichlet([ 10.0 1.0 1.0; 
+                                            1.0 10.0 1.0; 
+                                            1.0 1.0 10.0 ])
+    
+    s_0 ~ Categorical(fill(1.0 / 3.0, 3))
+    
+    s = randomvar(n)
+    x = datavar(Vector{Float64}, n)
+    
+    s_prev = s_0
+    
+    for t in 1:n
+        s[t] ~ Transition(s_prev, A) 
+        x[t] ~ Transition(s[t], B)
+        s_prev = s[t]
+    end
+    
+end
+
+# Constraints specification
+@constraints function hidden_markov_model_constraints()
+    q(s_0, s, A, B) = q(s_0, s)q(A)q(B)
+end
hidden_markov_model_constraints (generic function with 1 method)

Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?

We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.

Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!

imodel = hidden_markov_model(N)
+idata = (x = x_data,)
+
+imarginals = (
+    A = vague(MatrixDirichlet, 3, 3), 
+    B = vague(MatrixDirichlet, 3, 3), 
+    s = vague(Categorical, 3)
+)
+
+ireturnvars = (
+    A = KeepLast(),
+    B = KeepLast(),
+    s = KeepLast()
+)
+
+result = infer(
+    model         = imodel, 
+    data          = idata,
+    constraints   = hidden_markov_model_constraints(),
+    initmarginals = imarginals, 
+    returnvars    = ireturnvars, 
+    iterations    = 20, 
+    free_energy   = true
+);

That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over $A$) and about the uncertainty in the roombas observations (A good posterior over $B$). Let's see if it worked

println("Posterior Marginal for A:")
+mean(result.posteriors[:A])
Posterior Marginal for A:
+3×3 Matrix{Float64}:
+ 0.871955   0.0290008  0.0572283
+ 0.0349989  0.817591   0.135675
+ 0.0930457  0.153408   0.807097
println("Posterior Marginal for B:")
+mean(result.posteriors[:B])
Posterior Marginal for B:
+3×3 Matrix{Float64}:
+ 0.949636   0.0974741  0.0518997
+ 0.0244903  0.833632   0.0277884
+ 0.0258734  0.0688939  0.920312

Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. 

p1 = scatter(argmax.(s_data), 
+                        title="Inference results", 
+                        label = "Real", 
+                        ms = 6, 
+                        legend=:right,
+                        xlabel="Time" ,
+                        yticks= ([1,2,3],["Bedroom","Living room","Bathroom"]),
+                        size=(900,550)
+                        )
+
+p1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),
+                        label = "Inferred",
+                        ms = 3
+                        )
+
+p2 = plot(result.free_energy, 
+                    label="Free energy",
+                    xlabel="Iteration Number"
+                    )
+
+plot(p1, p2, layout = @layout([ a; b ]))

Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.

diff --git a/v2.16.2/examples/basic_examples/Kalman filtering and smoothing/index.html b/v2.16.2/examples/basic_examples/Kalman filtering and smoothing/index.html new file mode 100644 index 000000000..881923855 --- /dev/null +++ b/v2.16.2/examples/basic_examples/Kalman filtering and smoothing/index.html @@ -0,0 +1,412 @@ + +Kalman filtering and smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Kalman filtering and smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.

We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.

We then solve an identification problem which does not have an analytical solution.

Utimately, we show how RxInfer.jl can deal with missing observations.

Gaussian Linear Dynamical System

LGSSM can be described with the following equations:

\[\begin{aligned} + p(x_i|x_{i - 1}) & = \mathcal{N}(x_i|A * x_{i - 1}, \mathcal{P}),\\ + p(y_i|x_i) & = \mathcal{N}(y_i|B * x_i, \mathcal{Q}), +\end{aligned}\]

where $x_i$ are hidden states, $y_i$ are noisy observations, $A$, $B$ are state transition and observational matrices, $\mathcal{P}$ and $\mathcal{Q}$ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, A, B, Q, P)
+    x_prev = [ 10.0, -10.0 ]
+
+    x = Vector{Vector{Float64}}(undef, n)
+    y = Vector{Vector{Float64}}(undef, n)
+
+    for i in 1:n
+        x[i] = rand(rng, MvNormal(A * x_prev, Q))
+        y[i] = rand(rng, MvNormal(B * x[i], P))
+        x_prev = x[i]
+    end
+    
+    return x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 1234
+
+rng = MersenneTwister(1234)
+
+# We will model 2-dimensional observations with rotation matrix `A`
+# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`
+# are known and fixed for all time-steps
+θ = π / 35
+A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]
+B = diageye(2)
+Q = diageye(2)
+P = 25.0 .* diageye(2)
+
+# Number of observations
+n = 300;
x, y = generate_data(rng, A, B, Q, P);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.

px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+px = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)
+
+plot(px)

To create a model we use GraphPPL package and @model macro:

@model function rotate_ssm(n, x0, A, B, Q, P)
+    
+    # We create constvar references for better efficiency
+    cA = constvar(A)
+    cB = constvar(B)
+    cQ = constvar(Q)
+    cP = constvar(P)
+    
+    # `x` is a sequence of hidden states
+    x = randomvar(n)
+    # `y` is a sequence of "clamped" observations
+    y = datavar(Vector{Float64}, n)
+    
+    x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))
+    x_prev = x_prior
+    
+    for i in 1:n
+        x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)
+        y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)
+        x_prev = x[i]
+    end
+
+end

To run inference we also specify prior for out first hidden state:

x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));
# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. 
+# infer(..., options = (limit_stack_depth = 500, ))`
+result = infer(
+    model = rotate_ssm(length(y), x0, A, B, Q, P), 
+    data = (y = y,),
+    free_energy = true
+);
+
+xmarginals  = result.posteriors[:x]
+logevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence
px = plot()
+
+px = plot!(px, getindex.(x, 1), label = "Hidden Signal (dim-1)", color = :orange)
+px = plot!(px, getindex.(x, 2), label = "Hidden Signal (dim-2)", color = :green)
+
+px = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :teal)
+px = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = "Estimated Signal (dim-1)", color = :violet)
+
+plot(px)

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:

logevidence
1-element Vector{Float64}:
+ -1882.2434870099778

We may be also interested in performance of our resulting Belief Propagation algorithm:

@benchmark infer(
+    model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), 
+    data = (y = $y,)
+)
BenchmarkTools.Trial: 138 samples with 1 evaluation.
+ Range (min … max):  27.959 ms … 101.209 ms  ┊ GC (min … max): 0.00% … 0.00
+%
+ Time  (median):     32.419 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   36.402 ms ±  10.555 ms  ┊ GC (mean ± σ):  5.16% ± 9.59
+%
+
+     █▆                                                         
+  ▃▁▅██▇▅▁▁▁▃▃▃▄▃▁▃▃▃▂▃▁▁▁▁▁▂▁▁▁▁▂▁▂▁▁▁▁▁▁▁▁▁▂▁▁▁▂▁▁▁▁▁▁▁▁▁▁▁▂ ▂
+  28 ms           Histogram: frequency by time         89.5 ms <
+
+ Memory estimate: 9.73 MiB, allocs estimate: 226250.

System Identification Problem

In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:

using RxInfer, Distributions, StableRNGs, Plots
function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)
+
+    rng = StableRNG(seed)
+
+    real_x = Vector{Float64}(undef, n)
+    real_w = Vector{Float64}(undef, n)
+    real_y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))
+        real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))
+        real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))
+
+        x_i_min = real_x[i]
+        w_i_min = real_w[i]
+    end
+    
+    return real_x, real_w, real_y
+end
generate_data (generic function with 2 methods)

The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.

Combination 1: y = x + w

In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:

n = 250
+real_x, real_w, real_y = generate_data(+, n);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, real_x, label = "x")
+pl = plot!(pl, real_w, label = "w")
+
+pr = plot(title = "Combined y = x + w")
+pr = scatter!(pr, real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:

@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x = randomvar(n)
+    w = randomvar(n)
+    s = randomvar(n)
+    y = datavar(Float64, n)
+    
+    x_i_min = x0
+    w_i_min = w0
+    
+    for i in 1:n
+        x[i] ~ Normal(mean = x_i_min, precision = τ_x)
+        w[i] ~ Normal(mean = w_i_min, precision = τ_w)
+        s[i] ~ f(x[i], w[i])
+        y[i] ~ Normal(mean = s[i], precision = τ_y)
+        
+        x_i_min = x[i]
+        w_i_min = w[i]
+    end
+    
+end

RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:

constraints = @constraints begin 
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y
+)
+Options:
+  warn = true

The next step is to assign priors, initialise needed messages and marginals and call the inference function:

m_x_0, τ_x_0 = -20.0, 1.0
+m_w_0, τ_w_0 = 20.0, 1.0
+
+# We set relatively strong priors for random walk noise components
+# and sort of vague prior for the noise of the observations
+a_x, b_x = 0.01, 0.01var(real_x)
+a_w, b_w = 0.01, 0.01var(real_w)
+a_y, b_y = 1.0, 1.0
+
+# We set relatively strong priors for messages
+xinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))
+winit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))
+
+imessages = (x = xinit, w = winit)
+imarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))
+
+result = infer(
+    model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),
+    data  = (y = real_y,), 
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = imessages, 
+    initmarginals = imarginals, 
+    iterations = 50
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)

Let's examine our inference results:

τ_x_marginals = result.posteriors[:τ_x]
+τ_w_marginals = result.posteriors[:τ_w]
+τ_y_marginals = result.posteriors[:τ_y]
+
+smarginals = result.posteriors[:s]
+xmarginals = result.posteriors[:x]
+wmarginals = result.posteriors[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.

Combination 2: y = min(x, w)

In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:

# Smoothed version of `min` without zero-ed derivatives
+function smooth_min(x, y)    
+    if x < y
+        return x + 1e-4 * y
+    else
+        return y + 1e-4 * x
+    end
+end
smooth_min (generic function with 1 method)

RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:

min_meta = @meta begin 
+    # In this example we are going to use a simple `Linearization` method
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true
n = 200
+min_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, min_real_x, label = "x")
+pl = plot!(pl, min_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, min_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

min_m_x_0, min_τ_x_0 = -1.0, 1.0
+min_m_w_0, min_τ_w_0 = 1.0, 1.0
+
+min_a_x, min_b_x = 1.0, 1.0
+min_a_w, min_b_w = 1.0, 1.0
+min_a_y, min_b_y = 1.0, 1.0
+
+min_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))
+min_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))
+
+min_result = infer(
+    model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),
+    data  = (y = min_real_y,), 
+    meta = min_meta,
+    options = (limit_stack_depth = 500, ), 
+    constraints = constraints, 
+    initmessages = min_imessages, 
+    initmarginals = min_imarginals, 
+    iterations = 100
+)
Inference results:
+  Posteriors       | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)
min_τ_x_marginals = min_result.posteriors[:τ_x]
+min_τ_w_marginals = min_result.posteriors[:τ_w]
+min_τ_y_marginals = min_result.posteriors[:τ_y]
+
+min_smarginals = min_result.posteriors[:s]
+min_xmarginals = min_result.posteriors[:x]
+min_wmarginals = min_result.posteriors[:w]
+
+px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, min_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = "Estimated X")
+
+px1 = plot!(px1, min_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = "Estimated W")
+
+px2 = scatter!(px2, min_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks).

Online (filtering) identification: y = min(x, w)

Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:

@model function rx_identification(f)
+    
+    # We are going to continuosly update our priors
+    # based on new posteriors
+    m_x_0 = datavar(Float64) 
+    τ_x_0 = datavar(Float64)
+    m_w_0 = datavar(Float64) 
+    τ_w_0 = datavar(Float64)
+    a_x   = datavar(Float64) 
+    b_x   = datavar(Float64)
+    a_y   = datavar(Float64) 
+    b_y   = datavar(Float64)
+    a_w   =  datavar(Float64) 
+    b_w   = datavar(Float64)
+    s     = randomvar()
+    y     = datavar(Float64)
+    
+    x0 ~ Normal(mean = m_x_0, precision = τ_x_0)
+    τ_x ~ Gamma(shape = a_x, rate = b_x)
+    w0 ~ Normal(mean = m_w_0, precision = τ_w_0)
+    τ_w ~ Gamma(shape = a_w, rate = b_w)
+    τ_y ~ Gamma(shape = a_y, rate = b_y)
+    
+    x ~ Normal(mean = x0, precision = τ_x)
+    w ~ Normal(mean = w0, precision = τ_w)
+
+    s ~ f(x, w)
+    y ~ Normal(mean = s, precision = τ_y)
+    
+end

We impose structured mean-field assumption for this model as well:

rx_constraints = @constraints begin 
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ
+_y)
+Options:
+  warn = true

Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:

autoupdates = @autoupdates begin 
+    m_x_0, τ_x_0 = mean_precision(q(x))
+    m_w_0, τ_w_0 = mean_precision(q(w))
+    a_x = shape(q(τ_x)) 
+    b_x = rate(q(τ_x))
+    a_y = shape(q(τ_y))
+    b_y = rate(q(τ_y))
+    a_w = shape(q(τ_w)) 
+    b_w = rate(q(τ_w))
+end
(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_
+x = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_
+y)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))

As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):

rx_meta = @meta begin 
+    smooth_min() -> Linearization()
+end
Meta specification:
+  smooth_min() -> Linearization()
+Options:
+  warn = true

Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:

n = 300
+rx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);
+
+pl = plot(title = "Underlying signals")
+pl = plot!(pl, rx_real_x, label = "x")
+pl = plot!(pl, rx_real_w, label = "w")
+
+pr = plot(title = "Combined y = min(x, w)")
+pr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = "y")
+
+plot(pl, pr, size = (800, 300))

engine = infer(
+    model         = rx_identification(smooth_min),
+    constraints   = rx_constraints,
+    data          = (y = rx_real_y,),
+    autoupdates   = autoupdates,
+    meta          = rx_meta,
+    returnvars    = (:x, :w, :τ_x, :τ_w, :τ_y, :s),
+    keephistory   = 1000,
+    historyvars   =  KeepLast(),
+    initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),
+    iterations    = 10,
+    free_energy = true, 
+    free_energy_diagnostics = nothing,
+    autostart     = true,
+)
RxInferenceEngine:
+  Posteriors stream    | enabled for (w, s, τ_x, τ_w, τ_y, x)
+  Free Energy stream   | enabled
+  Posteriors history   | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)
+  Free Energy history  | available
+  Enabled events       | [  ]
rx_smarginals = engine.history[:s]
+rx_xmarginals = engine.history[:x]
+rx_wmarginals = engine.history[:w];
px1 = plot(legend = :bottomleft, title = "Estimated hidden signals")
+px2 = plot(legend = :bottomright, title = "Estimated combined signals")
+
+px1 = plot!(px1, rx_real_x, label = "Real hidden X")
+px1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = "Estimated X")
+
+px1 = plot!(px1, rx_real_w, label = "Real hidden W")
+px1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = "Estimated W")
+
+px2 = scatter!(px2, rx_real_y, label = "Observations", ms = 2, alpha = 0.5, color = :red)
+px2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = "Combined estimated signal", color = :green)
+
+plot(px1, px2, size = (800, 300))

The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the "disabled" state, does not infer anything and simply increases its variance (which is expected for the random walk).

Handling Missing Data

An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.

Let us assume that the following model generates the data

\[\begin{aligned} + {x}_t &\sim \mathcal{N}\left({x}_{t-1}, 1.0\right) \\ + {y}_t &\sim \mathcal{N}\left({x}_{t}, P \right) +\end{aligned}\]

with prior ${x}_0 \sim \mathcal{N}({m_{{x}_0}}, {v_{{x}_0}})$. Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation $\hat{y}_t \in \mathrm{R}$ we sometimes will catch missing observations.

using RxInfer, Plots
@model function smoothing(n, x0)
+    
+    P ~ Gamma(shape = 0.001, scale = 0.001)
+    x_prior ~ Normal(mean = mean(x0), var = var(x0)) 
+
+    x = randomvar(n)
+    y = datavar(Float64, n) where { allow_missing = true }
+
+    x_prev = x_prior
+
+    for i in 1:n
+        x[i] ~ Normal(mean = x_prev, precision = 1.0)
+        y[i] ~ Normal(mean = x[i], precision = P)
+        
+        x_prev = x[i]
+    end
+
+end

We need to manually extend the set of rules to support ::Missing values

P = 1.0
+n = 250
+
+real_signal     = map(e -> sin(0.05 * e), collect(1:n))
+noisy_data      = real_signal + rand(Normal(0.0, sqrt(P)), n);
+missing_indices = 100:125
+missing_data    = similar(noisy_data, Union{Float64, Missing}, )
+
+copyto!(missing_data, noisy_data)
+
+for index in missing_indices
+    missing_data[index] = missing
+end
constraints = @constraints begin
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)
+Options:
+  warn = true
x0_prior = NormalMeanVariance(0.0, 1000.0)
+
+result = infer(
+    model = smoothing(n, x0_prior), 
+    data  = (y = missing_data,), 
+    constraints = constraints,
+    initmarginals = (P = Gamma(0.001, 0.001), ),
+    returnvars = (x = KeepLast(),),
+    iterations = 20
+);
plot(real_signal, label = "Noisy signal", legend = :bottomright)
+scatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = "Missing region")
+plot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = "Estimated hidden state")

diff --git a/v2.16.2/examples/basic_examples/Predicting Bike Rental Demand/index.html b/v2.16.2/examples/basic_examples/Predicting Bike Rental Demand/index.html new file mode 100644 index 000000000..b12e2d910 --- /dev/null +++ b/v2.16.2/examples/basic_examples/Predicting Bike Rental Demand/index.html @@ -0,0 +1,193 @@ + +Predicting Bike Rental Demand · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Predicting Bike Rental Demand

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer

Preamble: Enabling Predictions

RxInfer.jl facilitates predictions in two primary ways.

  1. Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.
  2. Explicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.

Example

Consider the following model:

@model function example_model()
+    y = datavar(Float64) where {allow_missing = true}
+
+    h ~ NormalMeanPrecision(0, 1.0)
+    x ~ NormalMeanPrecision(h, 1.0)
+    y ~ NormalMeanPrecision(x, 10.0)
+end
# Implicit Prediction
+result = infer(model = example_model(), data = (y = missing,))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)
# Explicit Prediction
+result = infer(model = example_model(), predictvars = (y = KeepLast(),))
Inference results:
+  Posteriors       | available for (h, x)
+  Predictions      | available for (y)

Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.

using CSV, DataFrames, Plots

Objective

This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.

Dataset Source

Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.

# Load the data
+df = CSV.read("../data/bike_count/modified_bicycle.csv", DataFrame)
+df[1:10, :]
10×6 DataFrame
+ Row │ datetime            temp     atemp    humidity  windspeed  count
+     │ String31            Float64  Float64  Float64   Float64    Int64
+─────┼──────────────────────────────────────────────────────────────────
+   1 │ 2011-01-01 0:00:00     9.84   14.395      81.0     0.0        16
+   2 │ 2011-01-01 1:00:00     9.02   13.635      80.0     0.0        40
+   3 │ 2011-01-01 2:00:00     9.02   13.635      80.0     0.0        32
+   4 │ 2011-01-01 3:00:00     9.84   14.395      75.0     0.0        13
+   5 │ 2011-01-01 4:00:00     9.84   14.395      75.0     0.0         1
+   6 │ 2011-01-01 5:00:00     9.84   12.88       75.0     6.0032      1
+   7 │ 2011-01-01 6:00:00     9.02   13.635      80.0     0.0         2
+   8 │ 2011-01-01 7:00:00     8.2    12.88       86.0     0.0         3
+   9 │ 2011-01-01 8:00:00     9.84   14.395      75.0     0.0         8
+  10 │ 2011-01-01 9:00:00    13.12   17.425      76.0     0.0        14
# we reserve few samples for prediction
+n_future = 24
+
+X = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]
+y = Union{Float64, Missing}[df[:, "count"]...][1:end-n_future]
+
+state_dim = length(X[1]); # dimensionality of feature space

Generative Model with Priors

We present a generative model that delineates the latent dynamics of feature evolution, represented by $\mathbf{h}_t$, and their link to the bike rental counts, $\mathbf{y}_t$.

Equations and Priors

  1. Feature Dynamics with Prior:

    • Prior: $\mathbf{a} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Dynamics: $\mathbf{h}_t \sim \mathcal{N}(\mathbf{A h}_{t-1}, \mathbf{Q})$

    • \[\mathbf{A}\]

      is the transition matrix, reshaped from the prior vector $\mathbf{a}$, and $\mathbf{Q}$ represents process noise.

  2. Noisy Observations:

    • \[\mathbf{x}_t \sim \mathcal{N}(\mathbf{h}_t, \mathbf{P})\]

    • Represents the observed noisy state of the features.

  3. Count Prediction with Prior:

    • Prior: $\boldsymbol{\theta} \sim \mathcal{N}(\mathbf{0}, \mathbf{I})$
    • Prediction: $y_t \sim \mathcal{N}(\text{softplus}(\boldsymbol{\theta}^\top\mathbf{h}_t), \sigma^2)$
    • Models the bike rental count as influenced by a non-linear transformation of the hidden state.

Interpretation

  • This framework aims to simultaneously infer the transition matrix $\mathbf{A}$ and the regression parameters $\boldsymbol{\theta}$, providing a comprehensive view of the feature space dynamics and the count prediction.
  • By employing Gaussian priors on both $\mathbf{a}$ and $\boldsymbol{\theta}$, we incorporate beliefs about their distributions.
  • The inference process aims to discover these underlying dynamics, enabling predictions of both features $\mathbf{x}_t$ and counts $y_t$.
# We augument the dataset with missing entries for 24 hours ahead
+append!(X, repeat([missing], n_future))
+append!(y, repeat([missing], n_future));
# Function to perform the state transition in the model.
+# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.
+function transition(a, x)
+    nm, n = length(a), length(x)
+    m = nm ÷ n  # Calculate the number of rows for reshaping 'a' into a matrix
+    A = reshape(a, (m, n))  
+    return A * x
+end
transition (generic function with 1 method)
# The dotsoftplus function combines a dot product and softplus transformation.
+# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,
+# especially if the data suggests other forms of relationships or distributions.
+function dotsoftplus(a, x)
+    log(1 + exp(dot(a, x)))
+end
dotsoftplus (generic function with 1 method)
# model definction
+@model function bicycle_ssm(n, h0, θ0, a0, Q, P)
+
+    # `h` is a sequence of hidden states
+    h = randomvar(n)
+
+    # `x` is a sequence of observed states (features)
+    x = datavar(Vector{Float64}, n) where {allow_missing = true}
+    # `y` is a sequence of "count" bicycles
+    y = datavar(Float64, n) where {allow_missing = true}
+
+    a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))
+
+    θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))
+
+    h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))
+    h_prev = h_prior
+    
+    for i in 1:n
+        
+        h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)
+        
+        x[i] ~ MvNormal(μ=h[i], Σ=P)
+        
+        y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)
+        
+        h_prev = h[i]
+    end
+
+end
# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.
+# However, alternative methods like Unscented or CVI approximations can also be considered.
+transition_meta = @meta begin 
+    transition() -> Linearization()
+    dotsoftplus() -> Linearization()
+end
Meta specification:
+  transition() -> Linearization()
+  dotsoftplus() -> Linearization()
+Options:
+  warn = true
# We define rather uninformative priors 
+prior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))
+prior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))
+prior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))
MvNormalMeanCovariance(
+μ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0
+.0, 0.0]
+Σ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … 
+0.0 1.0]
+)
# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages
+imessages = ( h = prior_h, a = prior_a, θ = prior_θ,)
+
+bicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))
+
+result = infer(
+    model = bicycle_model,
+    data  = (y = y, x=X), 
+    options = (limit_stack_depth = 500, ), 
+    returnvars = KeepLast(),
+    initmessages = imessages,
+    meta = transition_meta,
+    iterations = 20,
+    showprogress=true,
+)
Inference results:
+  Posteriors       | available for (a, h, h_prior, θ)
+  Predictions      | available for (y, x)
# For a sake of this example, we extract only predictions
+mean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])
+mean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])
+
+mean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)
+mean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)
+mean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)
+mean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);
slice = (300, length(y))
+data = df[:, "count"][length(y)-n_future:length(y)]
+
+p = scatter(y, 
+            color=:darkblue, 
+            markerstrokewidth=0,
+            label="Observed Count", 
+            alpha=0.6)
+
+# Plotting the mean prediction with variance ribbon
+plot!(mean_y, ribbon=sqrt.(cov_y), 
+      color=:orange, 
+      fillalpha=0.3,
+      label="Predicted Mean ± Std Dev")
+
+# Adding a vertical line to indicate the start of the future prediction
+vline!([length(y)-n_future], 
+       label="Prediction Start", 
+       linestyle=:dash, 
+       linecolor=:green)
+
+# Future (unobserved) data
+plot!(length(y)-n_future:length(y), data, label="Future Count")
+
+# Adjusting the limits
+xlims!(slice)
+
+# Enhancing the plot with titles and labels
+title!("Bike Rental Demand Prediction")
+xlabel!("Time")
+ylabel!("Bike Count")
+
+# Adjust the legend
+legend=:topright
+
+# Show the final plot
+display(p)

using Plots
+
+# Define a color palette
+palette = cgrad(:viridis)
+
+# Plot the hidden states with observations
+p1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label="Hidden State 1", legend=:topleft)
+plot!(df[!, :temp], color=:grey, label="Temperature")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Temperature vs Hidden State 1")
+
+p2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label="Hidden State 2", legend=:topleft)
+plot!(df[!, :atemp], color=:grey, label="Feels-Like Temp")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="")
+xlabel!("Time")
+ylabel!("Value")
+title!("Feels-Like Temp vs Hidden State 2")
+
+p3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label="Hidden State 3", legend=:topleft)
+plot!(df[!, :humidity], color=:grey, label="Humidity")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Humidity vs Hidden State 3")
+
+p4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label="Hidden State 4", legend=:topleft)
+plot!(df[!, :windspeed], color=:grey, label="Windspeed")
+vline!([length(y)-n_future], linestyle=:dash, color=:red, label="Prediction Start")
+xlabel!("Time")
+ylabel!("Value")
+title!("Windspeed vs Hidden State 4")
+
+for p in [p1, p2, p3, p4]
+    xlims!(p, first(slice), last(slice))
+end
+
+plot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))

Conclusion

While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.

The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.

diff --git a/v2.16.2/examples/basic_examples/overview/index.html b/v2.16.2/examples/basic_examples/overview/index.html new file mode 100644 index 000000000..dc0f9f513 --- /dev/null +++ b/v2.16.2/examples/basic_examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Basic examples

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Basic examples contain "Hello World!" of Bayesian inference in RxInfer.

  • Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.
  • Bayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.
  • Kalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations
  • Predicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.
  • How to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.
diff --git a/v2.16.2/examples/overview/index.html b/v2.16.2/examples/overview/index.html new file mode 100644 index 000000000..b81ea7bd3 --- /dev/null +++ b/v2.16.2/examples/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Examples overview

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

  • Basic examples: Basic examples contain "Hello World!" of Bayesian inference in RxInfer.
  • Advanced examples: Advanced examples contain more complex inference problems.
  • Problem specific: Problem specific examples contain specialized models and inference for various domains.
diff --git a/v2.16.2/examples/problem_specific/Autoregressive Models/index.html b/v2.16.2/examples/problem_specific/Autoregressive Models/index.html new file mode 100644 index 000000000..b7cb64b15 --- /dev/null +++ b/v2.16.2/examples/problem_specific/Autoregressive Models/index.html @@ -0,0 +1,311 @@ + +Autoregressive Models · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Autoregressive Models

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:

\[\begin{aligned} +p(\gamma) &= \mathrm{Gamma}(\gamma|a, b),\\ +p(\mathbf{\theta}) &= \mathcal{N}(\mathbf{\theta}|\mathbf{\mu}, \Sigma),\\ +p(x_t|\mathbf{x}_{t-1:t-k}) &= \mathcal{N}(x_t|\mathbf{\theta}^{T}\mathbf{x}_{t-1:t-k}, \gamma^{-1}),\\ +p(y_t|x_t) &= \mathcal{N}(y_t|x_t, \tau^{-1}), +\end{aligned}\]

where $x_t$ is a current state of our system, $\mathbf{x}_{t-1:t-k}$ is a sequence of $k$ previous states, $k$ is an order of autoregression process, $\mathbf{\theta}$ is a vector of transition coefficients, $\gamma$ is a precision of state transition process, $y_k$ is a noisy observation of $x_k$ with precision $\tau$.

For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.

We start with importing all needed packages:

using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters

Let's generate some synthetic dataset, we use a predefined sets of coeffcients for $k$ = 1, 3 and 5 respectively:

# The following coefficients correspond to stable poles
+coefs_ar_1 = [-0.27002517200218096]
+coefs_ar_2 = [0.4511170798064709, -0.05740081602446657]
+coefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];
function generate_ar_data(rng, n, θ, γ, τ)
+    order        = length(θ)
+    states       = Vector{Vector{Float64}}(undef, n + 3order)
+    observations = Vector{Float64}(undef, n + 3order)
+    
+    γ_std = sqrt(inv(γ))
+    τ_std = sqrt(inv(τ))
+    
+    states[1] = randn(rng, order)
+    
+    for i in 2:(n + 3order)
+        states[i]       = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])
+        observations[i] = rand(rng, Normal(states[i][1], τ_std))
+    end
+    
+    return states[1+3order:end], observations[1+3order:end]
+end
generate_ar_data (generic function with 1 method)
# Seed for reproducibility
+seed = 123
+rng  = MersenneTwister(seed)
+
+# Number of observations in synthetic dataset
+n = 500
+
+# AR process parameters
+real_γ = 1.0
+real_τ = 0.5
+real_θ = coefs_ar_5
+
+states, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);

Let's plot our synthetic dataset:

plot(first.(states), label = "Hidden states")
+scatter!(observations, label = "Observations")

Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order $k$ > 1 and for Univariate AR (reduces to simple State-Space-Model) with order $k$ = 1.

@model function lar_model(T::Type, n, order, c, τ)
+    
+     
+    # We create a sequence of random variables for hidden states
+    x = randomvar(n)
+    # As well a sequence of observartions
+    y = datavar(Float64, n)
+    
+    ct = constvar(c)
+    # We assume observation noise to be known
+    cτ = constvar(τ)
+    
+    γ  = randomvar()
+    θ  = randomvar()
+    x0 = randomvar()
+    
+    # Prior for first state
+    if T === Multivariate
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+        x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))
+    else
+        γ  ~ Gamma(α = 1.0, β = 1.0)
+        θ  ~ Normal(μ = 0.0, γ = 1.0)
+        x0 ~ Normal(μ = 0.0, γ = 1.0)
+    end
+    
+    x_prev = x0
+    
+    for i in 1:n
+        
+        x[i] ~ AR(x_prev, θ, γ) 
+        
+        if T === Multivariate
+            y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)
+        else
+            y[i] ~ Normal(μ = ct * x[i], γ = cτ)
+        end
+        
+        x_prev = x[i]
+    end
+
+end
@constraints function ar_constraints() 
+    q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)
+end
ar_constraints (generic function with 1 method)
@meta function ar_meta(artype, order, stype)
+    AR() -> ARMeta(artype, order, stype)
+end
ar_meta (generic function with 1 method)
morder  = 5
+martype = Multivariate
+mc      = ReactiveMP.ar_unit(martype, morder)
+mconstraints = ar_constraints()
+mmeta        = ar_meta(martype, morder, ARsafe())
+
+moptions = (limit_stack_depth = 100, )
+
+mmodel         = lar_model(martype, length(observations), morder, mc, real_τ)
+mdata          = (y = observations, )
+minitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))
+mreturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+# First execution is slow due to Julia's initial compilation 
+# Subsequent runs will be faster (benchmarks are below)
+mresult = infer(
+    model = mmodel, 
+    data  = mdata,
+    constraints   = mconstraints,
+    meta          = mmeta,
+    options       = moptions,
+    initmarginals = minitmarginals,
+    returnvars    = mreturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
@unpack x, γ, θ = mresult.posteriors
Dict{Symbol, Vector} with 3 entries:
+  :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)
+, Ga…
+  :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…
+  :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa
+t64}…

We will use different initial marginals depending on type of our AR process

p1 = plot(first.(states), label="Hidden state")
+p1 = scatter!(p1, observations, label="Observations")
+p1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label="Inferred states", legend = :bottomright)
+
+p2 = plot(mean.(γ), ribbon = std.(γ), label = "Inferred transition precision", legend = :topright)
+p2 = plot!([ real_γ ], seriestype = :hline, label = "Real transition precision")
+
+p3 = plot(mresult.free_energy, label = "Bethe Free Energy")
+
+plot(p1, p2, p3, layout = @layout([ a; b c ]))

Let's also plot a subrange of our results:

subrange = div(n,5):(div(n, 5) + div(n, 5))
+
+plot(subrange, first.(states)[subrange], label="Hidden state")
+scatter!(subrange, observations[subrange], label="Observations")
+plot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label="Inferred states", legend = :bottomright)

It is also interesting to see where our AR coefficients converge to:

let
+    pθ = plot()
+
+    θms = mean.(θ)
+    θvs = var.(θ)
+    
+    l = length(θms)
+
+    edim(e) = (a) -> map(r -> r[e], a)
+
+    for i in 1:length(first(θms))
+        pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = "Estimated θ[$i]")
+    end
+    
+    for i in 1:length(real_θ)
+        pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = "Real θ[$i]")
+    end
+    
+    plot(pθ, legend = :outertopright, size = (800, 300))
+end

println("$(length(real_θ))-order AR inference Bethe Free Energy: ", last(mresult.free_energy))
5-order AR inference Bethe Free Energy: 1024.0775661298358

We can also run a 1-order AR inference on 5-order AR data:

uorder  = 1
+uartype = Univariate
+uc      = ReactiveMP.ar_unit(uartype, uorder)
+uconstraints = ar_constraints()
+umeta        = ar_meta(uartype, uorder, ARsafe())
+
+uoptions = (limit_stack_depth = 100, )
+
+umodel         = lar_model(uartype, length(observations), uorder, uc, real_τ)
+udata          = (y = observations, )
+uinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))
+ureturnvars    = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())
+
+uresult = infer(
+    model = umodel, 
+    data  = udata,
+    meta  = umeta,
+    constraints   = uconstraints,
+    initmarginals = uinitmarginals,
+    returnvars    = ureturnvars,
+    free_energy   = true,
+    iterations    = 50, 
+    showprogress  = false
+);
println("1-order AR inference Bethe Free Energy: ", last(uresult.free_energy))
1-order AR inference Bethe Free Energy: 1025.8792949319954
if uresult.free_energy[end] > mresult.free_energy[end]
+    println("We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.")
+else
+    error("AR-1 performs better than AR-5...") 
+end
We can see that, according to final Bethe Free Energy value, in this exampl
+e 5-order AR process can describe data better than 1-order AR.

Autoregressive Moving Average Model

Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:

\[\begin{aligned} +e_t \sim \mathcal{N}(0, \gamma^{-1}) \quad +\theta &\sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \quad +\eta \sim \mathcal{MN}(\mathbf{0}, \mathbf{I}) \\ +\mathbf{h}_0 &\sim \mathcal{MN}\left(\begin{bmatrix} +e_{-1} \\ +e_{-2} +\end{bmatrix}, \mathbf{I}\right) \\ +\mathbf{h}_t &= \mathbf{S}\mathbf{h}_{t-1} + \mathbf{c} e_{t-1} \\ +\mathbf{x}_t &= \boldsymbol{\theta}^\top\mathbf{x}_{t-1} + \boldsymbol{\eta}^\top\mathbf{h}_{t} + e_t +\end{aligned}\]

where shift matrix $\mathbf{S}$ is

\[\begin{aligned} +\mathbf{S} = \begin{pmatrix} +0 & 0 \\ +1 & 0 +\end{pmatrix} +\end{aligned}\]

and unit vector $\mathbf{c}$:

\[\begin{aligned} +\mathbf{c}=[1, 0] +\end{aligned}\]

when MA order is $2$

In this way, $\mathbf{h}_t$ containing errors $e_t$ can be viewed as hidden state.

In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., $\boldsymbol{\eta}^\top\mathbf{h}_{t}$, (2) induced by errors $e_t$ that prevents analytical update of precision parameter $\gamma$ (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.

# Load packages
+using RxInfer, LinearAlgebra, CSV, DataFrames, Plots
# Define shift function
+function shift(dim)
+    S = Matrix{Float64}(I, dim, dim)
+    for i in dim:-1:2
+           S[i,:] = S[i-1, :]
+    end
+    S[1, :] = zeros(dim)
+    return S
+end
shift (generic function with 1 method)
@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)
+        
+    c = zeros(p); c[1] = 1.0; # AR
+    b = zeros(q); b[1] = 1.0; # MA
+    S = shift(q); # MA
+    
+    # initialize variables
+    h  = randomvar(n-1)
+    e  = randomvar(n)
+    z  = randomvar(n)
+    
+    x  = datavar(Float64, n) where { allow_missing = true }
+    
+    # priors
+    γ  ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))
+    η  ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))
+    θ  ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))
+    τ  ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))
+    
+    # initial
+    h_0  ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))
+    z[1] ~ AR(h_0, η, τ)
+    e[1] ~ Normal(mean = 0.0, precision = γ)
+
+    x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]
+    
+    h_prev = h_0
+    for t in 1:n-1
+        
+        e[t+1] ~ Normal(mean = 0.0, precision = γ)
+        h[t]   ~ S*h_prev + b*e[t]
+        z[t+1] ~ AR(h[t], η, τ)
+        x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]
+        h_prev = h[t]
+    end
+end

To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle

x_df = CSV.read("../data/arma/aal_stock.csv", DataFrame)
1259×7 DataFrame
+  Row │ date        open     high     low      close    volume    Name
+      │ Date        Float64  Float64  Float64  Float64  Int64     String3
+──────┼───────────────────────────────────────────────────────────────────
+    1 │ 2013-02-08    15.07    15.12   14.63     14.75   8407500  AAL
+    2 │ 2013-02-11    14.89    15.01   14.26     14.46   8882000  AAL
+    3 │ 2013-02-12    14.45    14.51   14.1      14.27   8126000  AAL
+    4 │ 2013-02-13    14.3     14.94   14.25     14.66  10259500  AAL
+    5 │ 2013-02-14    14.94    14.96   13.16     13.99  31879900  AAL
+    6 │ 2013-02-15    13.93    14.61   13.93     14.5   15628000  AAL
+    7 │ 2013-02-19    14.33    14.56   14.08     14.26  11354400  AAL
+    8 │ 2013-02-20    14.17    14.26   13.15     13.33  14725200  AAL
+  ⋮   │     ⋮          ⋮        ⋮        ⋮        ⋮        ⋮         ⋮
+ 1253 │ 2018-01-30    52.45    53.05   52.36     52.59   4741808  AAL
+ 1254 │ 2018-01-31    53.08    54.71   53.0      54.32   5962937  AAL
+ 1255 │ 2018-02-01    54.0     54.64   53.59     53.88   3623078  AAL
+ 1256 │ 2018-02-02    53.49    53.99   52.03     52.1    5109361  AAL
+ 1257 │ 2018-02-05    51.99    52.39   49.75     49.76   6878284  AAL
+ 1258 │ 2018-02-06    49.32    51.5    48.79     51.18   6782480  AAL
+ 1259 │ 2018-02-07    50.91    51.98   50.89     51.4    4845831  AAL
+                                                         1244 rows omitted
# we will use "close" column
+x_data = filter(!ismissing, x_df[:, 5]);
# Plot data
+plot(x_data, xlabel="day", ylabel="price", label=false)

p_order = 10 # AR
+q_order = 4 # MA
4
# Training set
+train_size = 1000
+x_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]
+x_train = Float64.(x_data[p_order+1:end])[1:train_size];
# Test set
+x_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]
+x_test = Float64.(x_data[p_order+1:end])[train_size+1:end];

Inference

# Constraints are needed for performing VMP
+arma_constraints = @constraints begin
+    q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)
+end;
# This cell defines prior knowledge for model parameters
+h_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+γ_prior = GammaShapeRate(1e4, 1.0)
+τ_prior = GammaShapeRate(1e2, 1.0)
+η_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))
+θ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));
# Model's graph has structural loops, hence, it requires pre-initialisation
+arma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);
+arma_imessages  = (h_0 = h_prior, h = h_prior);
+arma_meta       = ar_meta(Multivariate, q_order, ARsafe());
result = infer(
+    model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), 
+    data  = (x = x_train, ),
+    initmarginals = arma_imarginals,
+    initmessages  = arma_imessages,
+    constraints   = arma_constraints,
+    meta          = arma_meta,
+    iterations    = 50,
+    options       = (limit_stack_depth = 400, ),
+);
plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = "eₜ")

# extract posteriors
+h_posterior = result.posteriors[:h][end][end]
+γ_posterior = result.posteriors[:γ][end]
+τ_posterior = result.posteriors[:τ][end]
+η_posterior = result.posteriors[:η][end]
+θ_posterior = result.posteriors[:θ][end];

Prediction

Here we are going to use our inference results in order to predict the dataset itself

# The prediction function is aimed at approximating the predictive posterior distribution
+# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)
+function prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)
+    h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))
+    ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))
+    c = zeros(p); c[1] = 1.0
+    b = zeros(q); b[1] = 1.0
+    ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)
+    θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))
+    ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)
+    e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))
+    ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out)  
+    @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out)  
+end
prediction (generic function with 1 method)
predictions = []
+for x_prev in x_prev_test
+    push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))
+    # after every new prediction we can actually "retrain" the model to use the power of Bayesian approach
+    # we will skip this part at this notebook
+end
plot(x_test, label="test data", legend=:topleft)
+plot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label="predicted", xlabel="day", ylabel="price")

diff --git a/v2.16.2/examples/problem_specific/Gamma Mixture/index.html b/v2.16.2/examples/problem_specific/Gamma Mixture/index.html new file mode 100644 index 000000000..87745732a --- /dev/null +++ b/v2.16.2/examples/problem_specific/Gamma Mixture/index.html @@ -0,0 +1,129 @@ + +Gamma Mixture Model · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gamma Mixture Model

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.

Load packages

using RxInfer, Random, StatsPlots
# create custom structure for model parameters for simplicity
+struct GammaMixtureModelParameters
+    nmixtures   # number of mixtures
+    priors_as   # tuple of priors for variable a
+    priors_bs   # tuple of priors for variable b
+    prior_s     # prior of variable s
+end

Model specification

@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)
+
+    # fetch information from struct
+    nmixtures = parameters.nmixtures
+    priors_as = parameters.priors_as
+    priors_bs = parameters.priors_bs
+    prior_s   = parameters.prior_s
+
+    # set prior on global selection variable
+    s ~ Dirichlet(probvec(prior_s))
+
+    # allocate vectors of random variables
+    as = randomvar(nmixtures)
+    bs = randomvar(nmixtures)
+
+    # set priors on variables of mixtures
+    for i in 1:nmixtures
+        as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))
+        bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))
+    end
+
+    # introduce random variables for local selection variables and data
+    z = randomvar(nobservations)
+    y = datavar(Float64, nobservations)
+
+    # convert vector to tuples for proper functioning of GammaMixture node
+    tas = tuple(as...)
+    tbs = tuple(bs...)
+
+    # specify local selection variable and data generating process
+    for i in 1:nobservations
+        z[i] ~ Categorical(s)
+        y[i] ~ GammaMixture(z[i], tas, tbs)
+    end
+    
+end
constraints = @constraints begin 
+
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+
+    q(as) = q(as[begin])..q(as[end])
+    q(bs) = q(bs[begin])..q(bs[end])
+    
+    q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])
+end
Constraints:
+  marginals form:
+    q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(z, as, bs, s) = q(z)q(as)q(bs)q(s)
+    q(as) = q(as[(begin)..(end)])
+    q(bs) = q(bs[(begin)..(end)])
+Options:
+  warn = true
# specify seed and number of data points
+rng = MersenneTwister(43)
+n_samples = 2500
+
+# specify parameters of mixture model that generates the data
+# Note that mixture components have exactly the same means
+mixtures  = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]
+nmixtures = length(mixtures)
+mixing    = rand(rng, nmixtures)
+mixing    = mixing ./ sum(mixing)
+mixture   = MixtureModel(mixtures, mixing)
+
+# generate data set
+dataset = rand(rng, mixture, n_samples);
# specify priors of probabilistic model
+# NOTE: As the means of the mixtures "collide", we specify informative prior for selector variable
+nmixtures = 2
+gpriors = GammaMixtureModelParameters(
+    nmixtures,                                                    # number of mixtures
+    [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ],                         # priors on variables a
+    [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ],      # priors on variables b
+    Dirichlet(1e3*mixing)                                         # prior on variable s
+)
+
+gmodel         = gamma_mixture_model(length(dataset), gpriors)
+gdata          = (y = dataset, )
+ginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))
+greturnvars    = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())
+
+goptions = (
+     
+    default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently
+)
+
+gresult = infer(
+    model         = gmodel, 
+    data          = gdata,
+    constraints   = constraints,
+    options       = (limit_stack_depth = 100,),
+    initmarginals = ginitmarginals,
+    returnvars    = greturnvars,
+    free_energy   = true,
+    iterations    = 250, 
+    showprogress  = true
+);
# extract inferred parameters
+_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])
+_dists   = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))
+_mixing = mean(gresult.posteriors[:s])
+
+# create model from inferred parameters
+_mixture   = MixtureModel(_dists, _mixing);
# report on outcome of inference
+println("Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))")
+println("Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))")
+println("========")
+println("Generated mixing: $(mixing)")
+println("Inferred mixing: $(_mixing)")
Generated means: 0.3333333333333333 and 0.33333333333333337
+Inferred means: 0.33822470398804994 and 0.33305534672666653
+========
+Generated mixing: [0.18923488676601088, 0.8107651132339891]
+Inferred mixing: [0.11395888467453213, 0.8860411153254679]
# plot results
+p1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p1 = plot!(mixture, label=false, title="Generated mixtures", linewidth=3.0)
+
+p2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label="data", opacity=0.3)
+p2 = plot!(_mixture, label=false, title="Inferred mixtures", linewidth=3.0)
+
+# evaluate the convergence of the algorithm by monitoring the BFE
+p3 = plot(gresult.free_energy, label=false, xlabel="iterations", title="Bethe FE")
+
+plot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))

diff --git a/v2.16.2/examples/problem_specific/Gaussian Mixture/index.html b/v2.16.2/examples/problem_specific/Gaussian Mixture/index.html new file mode 100644 index 000000000..4195817b2 --- /dev/null +++ b/v2.16.2/examples/problem_specific/Gaussian Mixture/index.html @@ -0,0 +1,170 @@ + +Gaussian Mixture · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Gaussian Mixture

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.

Load packages

using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings

Univariate Gaussian Mixture Model

Consider the data set of length $N$ observed below.

function generate_univariate_data(nr_samples; rng = MersenneTwister(123))
+
+    # data generating parameters
+    class        = [1/3, 2/3]
+    mean1, mean2 = -10, 10
+    precision    = 1.777
+
+    # generate data
+    z = rand(rng, Categorical(class), nr_samples)
+    y = zeros(nr_samples)
+    for k in 1:nr_samples
+        y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))
+    end
+
+    return y
+
+end;
data_univariate = generate_univariate_data(100)
+histogram(data_univariate, bins=50, label="data", normed=true)
+xlims!(minimum(data_univariate), maximum(data_univariate))
+ylims!(0, Inf)
+ylabel!("relative occurrence [%]")
+xlabel!("y")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, w, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(w_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Beta}(s \mid \alpha_s, \beta_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \sigma_k^2) \\ p(w_{k}) &= \Gamma(w_k \mid \alpha_k, \beta_k) \\ + p(z_n \mid s) &= \mathrm{Ber}(z_n \mid s) \\ + p(y_n \mid m, w, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, w_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $w = \{ w_1, w_2, \ldots, w_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

Here we implement the following model with uninformative values for the hyperparameters as

@model function univariate_gaussian_mixture_model(nr_samples)
+    
+    s ~ Beta(1.0, 1.0)
+    
+    m1 ~ Normal(mean = -2.0, var = 1e3)
+    w1 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    m2 ~ Normal(mean = 2.0, var = 1e3)
+    w2 ~ Gamma(shape = 0.01, rate = 0.01)
+    
+    z = randomvar(nr_samples)
+    y = datavar(Float64, nr_samples)
+    
+    for n in 1:nr_samples
+        z[n] ~ Bernoulli(s)
+        y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, w \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, w \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(w_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Beta}(s \mid \hat{\alpha}_s, \hat{\beta}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\sigma}^2_k) \\ + q(w_k) &= \Gamma (w_k \mid \hat{\alpha}_k, \hat{\beta}_k) \\ + q(z_n) &= \mathrm{Ber}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

results_univariate = infer(
+    model = univariate_gaussian_mixture_model(length(data_univariate)), 
+    constraints = MeanField(),
+    data  = (y = data_univariate,), 
+    initmarginals = (
+        s  = vague(Beta), 
+        m1 = NormalMeanVariance(-2.0, 1e3), 
+        m2 = NormalMeanVariance(2.0, 1e3), 
+        w1 = vague(GammaShapeRate), 
+        w2 = vague(GammaShapeRate)
+    ), 
+    iterations  = 10, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m2, m1, s, w2, w1, z)
+  Free Energy:     | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.
+277, 135.277, 135.277, 135.277, 135.277]

Results

Below the inference results can be seen as a function of the iterations

mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L"posterior $m_1$")
+mp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L"posterior $m_2$")
+mp = plot!(mp, [ -10 ], seriestype = :hline, label = L"true $m_1$")
+mp = plot!(mp, [ 10 ], seriestype = :hline, label = L"true $m_2$")
+
+wp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L"posterior $w_1$", legend = :bottomright, ylim = (-1, 3))
+wp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L"posterior $w_2$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_1$")
+wp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L"true $w_2$")
+
+swp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L"posterior $s$")
+swp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L"true $s$")
+
+fep = plot(results_univariate.free_energy, label = "Free Energy", legend = :topright)
+
+plot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))
+xlabel!("iteration")

Multivariate Gaussian Mixture Model

The above example can also be extended to the multivariate case. Consider the data set below

function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))
+
+    L         = 50.0
+    nr_mixtures = 6
+
+    probvec = normalize!(ones(nr_mixtures), 1)
+
+    switch = Categorical(probvec)
+
+    gaussians = map(1:nr_mixtures) do index
+        angle      = 2π / nr_mixtures * (index - 1)
+        basis_v    = L * [ 1.0, 0.0 ]
+        R          = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]
+        mean       = R * basis_v 
+        covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))
+        return MvNormal(mean, covariance)
+    end
+
+    z = rand(rng, switch, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+
+    for n in 1:nr_samples
+        y[n] = rand(rng, gaussians[z[n]])
+    end
+
+    return y
+
+end;
data_multivariate = generate_multivariate_data(500)
+
+sdim(n) = (a) -> map(d -> d[n], a) # helper function
+scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)
+xlabel!(L"y_1")
+ylabel!(L"y_2")

Model specification

The goal here is to create a model for the data set above. In this case a Gaussian mixture model with $K$ components seems to suite the situation well. We specify the factorized model as $p(y, z, s, m, w) = \prod_{n=1}^N \bigg(p(y_n \mid m, W, z_n) p(z_n \mid s) \bigg)\prod_{k=1}^K \bigg(p(m_k) p(W_k) \bigg) p(s),$ where the individual terms are specified as $\begin{aligned} p(s) &= \mathrm{Dir}(s \mid \alpha_s) \\ + p(m_{k}) &= \mathcal{N}(m_k \mid \mu_k, \Sigma_k) \\ p(W_{k}) &= \mathcal{W}(W_k \mid V_k, \nu_k) \\ + p(z_n \mid s) &= \mathrm{Cat}(z_n \mid s) \\ + p(y_n \mid m, W, z_n) &= \prod_{k=1}^K \mathcal{N}\left(y_n \mid m_{k}, W_{k}\right)^{z_{nk}} \end{aligned}$

The set of observations $y = \{y_1, y_2, \ldots, y_N\}$ is modeled by a mixture of Gaussian distributions, parameterized by means $m = \{m_1, m_2, \ldots, m_K\}$ and precisions $W = \{ W_1, W_2, \ldots, W_K\}$, where $k$ denotes the component index. This component is selected per observation by the indicator variable $z_n$, which is a one-of-$K$ encoded vector satisfying $\sum_{k=1}^K z_{nk} = 1$ and $z_{nk} \in \{0, 1\} \forall k$. We put a hyperprior on these variables, termed $s$, which represents the relative occurrence of the different realizations of $z_n$.

@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)
+    
+    z = randomvar(nr_samples)
+    m = randomvar(nr_mixtures)
+    w = randomvar(nr_mixtures)
+    y = datavar(Vector{Float64}, nr_samples)
+    
+    for k in 1:nr_mixtures        
+        m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])
+        w[k] ~ Wishart(3, 1e2*diagm(ones(2)))
+    end
+    
+    s ~ Dirichlet(ones(nr_mixtures))
+    
+    means = tuple(m...)
+    precs = tuple(w...)
+    
+    for n in 1:nr_samples
+        z[n] ~ Categorical(s) 
+        y[n] ~ NormalMixture(z[n], means, precs)
+    end
+    
+end

Probabilistic inference

In order to fit the model to the data, we are interested in computing the posterior distribution $p(z, s, m, W \mid y)$ However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as $p(z, s, m, W \mid y) \approx \prod_{n=1}^N q(z_n) \prod_{k=1}^K \bigg(q(m_k) q(W_k)\bigg) q(s),$ with the functional forms $\begin{aligned} q(s) &= \mathrm{Dir}(s \mid \hat{\alpha}_s) \\ + q(m_k) &= \mathcal{N}(m_k \mid \hat{\mu}_k, \hat{\Sigma}_k) \\ + q(w_k) &= \mathcal{W}(W_k \mid \hat{V}_k, \hat{\nu}_k) \\ + q(z_n) &= \mathrm{Cat}(z_n \mid \hat{p}_n) \end{aligned}$ In order to get the inference procedure started, these marginal distribution need to be initialized.

rng = MersenneTwister(121)
+m = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]
+results_multivariate = infer(
+    model = multivariate_gaussian_mixture_model(
+        6, 
+        length(data_multivariate), 
+        m,
+        [diagm(1e2 * ones(2)) for k in 1:6]
+    ), 
+    data  = (y = data_multivariate,), 
+    constraints   = MeanField(),
+    initmarginals = (
+        s = vague(Dirichlet, 6), 
+        m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], 
+        w = Wishart(3, diagm(1e2 * ones(2)))
+    ), 
+    iterations  = 50, 
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (m, w, s, z)
+  Free Energy:     | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49  …  3894.49, 3894.49, 3894.49, 3894.
+49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]

Results

Below the inference results can be seen

p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title="Data", xlims=(-75, 75), ylims=(-75, 75))
+p_result = plot(xlims = (-75, 75), ylims = (-75, 75), title="Inference result", legend=false, colorbar = false)
+for (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])
+    gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))
+    global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title="Inference result", legend=false, levels = 7, colorbar = false)
+end
+p_fe = plot(results_multivariate.free_energy, label = "Free Energy")
+
+plot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))

diff --git a/v2.16.2/examples/problem_specific/Hierarchical Gaussian Filter/index.html b/v2.16.2/examples/problem_specific/Hierarchical Gaussian Filter/index.html new file mode 100644 index 000000000..c28913384 --- /dev/null +++ b/v2.16.2/examples/problem_specific/Hierarchical Gaussian Filter/index.html @@ -0,0 +1,145 @@ + +Hierarchical Gaussian Filter · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Hierarchical Gaussian Filter

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).

Simple HGF model can be defined as:

\[\begin{aligned} + x^{(j)}_k & \sim \, \mathcal{N}(x^{(j)}_{k - 1}, f_k(x^{(j - 1)}_k)) \\ + y_k & \sim \, \mathcal{N}(x^{(j)}_k, \tau_k) +\end{aligned}\]

where $j$ is an index of layer in hierarchy, $k$ is a time step and $f_k$ is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with $f_k = \exp(\kappa x + \omega)$ variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:

\[\begin{aligned} + z_k & \sim \, \mathcal{N}(z_{k - 1}, \mathcal{\tau_z}) \\ + x_k & \sim \, \mathcal{N}(x_{k - 1}, \exp(\kappa z_k + \omega)) \\ + y_k & \sim \, \mathcal{N}(x_k, \mathcal{\tau_y}) +\end{aligned}\]

In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.

For simplicity we will consider $\tau_z$, $\tau_y$, $\kappa$ and $\omega$ known and fixed, but there are no principled limitations to make them random variables too.

To model this process in RxInfer, first, we start with importing all needed packages:

using RxInfer, BenchmarkTools, Random, Plots

Next step, is to generate some synthetic data:

function generate_data(rng, k, w, zv, yv)
+    z_prev = 0.0
+    x_prev = 0.0
+
+    z = Vector{Float64}(undef, n)
+    v = Vector{Float64}(undef, n)
+    x = Vector{Float64}(undef, n)
+    y = Vector{Float64}(undef, n)
+
+    for i in 1:n
+        z[i] = rand(rng, Normal(z_prev, sqrt(zv)))
+        v[i] = exp(k * z[i] + w)
+        x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))
+        y[i] = rand(rng, Normal(x[i], sqrt(yv)))
+
+        z_prev = z[i]
+        x_prev = x[i]
+    end 
+    
+    return z, x, y
+end
generate_data (generic function with 1 method)
# Seed for reproducibility
+seed = 42
+
+rng = MersenneTwister(seed)
+
+# Parameters of HGF process
+real_k = 1.0
+real_w = 0.0
+z_variance = abs2(0.2)
+y_variance = abs2(0.1)
+
+# Number of observations
+n = 300
+
+z, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);

Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.

let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    scatter!(px, 1:n, y, label = "y_i", color = :red, ms = 2, alpha = 0.2)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

To create a model we use the @model macro:

# We create a single-time step of corresponding state-space process to
+# perform online learning (filtering)
+@model function hgf(real_k, real_w, z_variance, y_variance)
+    
+    # Priors from previous time step for `z`
+    zt_min_mean = datavar(Float64)
+    zt_min_var  = datavar(Float64)
+    
+    # Priors from previous time step for `x`
+    xt_min_mean = datavar(Float64)
+    xt_min_var  = datavar(Float64)
+
+    zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)
+    xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)
+
+    # Higher layer is modelled as a random walk 
+    zt ~ NormalMeanVariance(zt_min, z_variance)
+    
+    # Lower layer is modelled with `GCV` node
+    gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)
+    
+    # Noisy observations 
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(xt, y_variance)
+    
+    return gcvnode
+end
+
+@constraints function hgfconstraints() 
+    q(xt, zt, xt_min) = q(xt, xt_min)q(zt)
+end
+
+@meta function hgfmeta()
+    # Lets use 31 approximation points in the Gauss Hermite cubature approximation method
+    GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) 
+end
hgfmeta (generic function with 1 method)
function run_inference(data, real_k, real_w, z_variance, y_variance)
+
+    autoupdates   = @autoupdates begin
+        zt_min_mean, zt_min_var = mean_var(q(zt))
+        xt_min_mean, xt_min_var = mean_var(q(xt))
+    end
+
+    return infer(
+        model         = hgf(real_k, real_w, z_variance, y_variance),
+        constraints   = hgfconstraints(),
+        meta          = hgfmeta(),
+        data          = (y = data, ),
+        autoupdates   = autoupdates,
+        keephistory   = length(data),
+        historyvars    = (
+            xt = KeepLast(),
+            zt = KeepLast()
+        ),
+        initmarginals = (
+            zt = NormalMeanVariance(0.0, 5.0),
+            xt = NormalMeanVariance(0.0, 5.0),
+        ), 
+        iterations    = 5,
+        free_energy   = true,
+        autostart     = true,
+        callbacks     = (
+            after_model_creation = (model, returnval) -> begin 
+                gcvnode = returnval
+                setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))
+            end,
+        )
+    )
+end
run_inference (generic function with 1 method)
result = run_inference(y, real_k, real_w, z_variance, y_variance);
+
+mz = result.history[:zt];
+mx = result.history[:xt];
let 
+    pz = plot(title = "Hidden States Z")
+    px = plot(title = "Hidden States X")
+    
+    plot!(pz, 1:n, z, label = "z_i", color = :orange)
+    plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = "estimated z_i", color = :teal)
+    
+    plot!(px, 1:n, x, label = "x_i", color = :green)
+    plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = "estimated x_i", color = :violet)
+    
+    plot(pz, px, layout = @layout([ a; b ]))
+end

As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:

plot(result.free_energy_history, label = "Bethe Free Energy")

As we can see BetheFreeEnergy converges nicely to a stable point.

At final, lets check the overall performance of our resulting Variational Message Passing algorithm:

@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)
BenchmarkTools.Trial: 45 samples with 1 evaluation.
+ Range (min … max):   84.766 ms … 164.193 ms  ┊ GC (min … max): 0.00% … 0.0
+0%
+ Time  (median):     109.323 ms               ┊ GC (median):    0.00%
+ Time  (mean ± σ):   112.571 ms ±  13.115 ms  ┊ GC (mean ± σ):  1.76% ± 3.3
+8%
+
+                   █▄▃▃                                          
+  ▄▁▁▁▁▁▁▄▁▁▁▁▄▇▄▁▆████▁▁▆▄▆▄▁▁▁▄▁▁▁▁▄▁▄▁▁▁▄▁▁▁▁▁▄▁▁▁▁▁▁▁▁▁▁▁▁▄ ▁
+  84.8 ms          Histogram: frequency by time          164 ms <
+
+ Memory estimate: 18.78 MiB, allocs estimate: 456890.
diff --git a/v2.16.2/examples/problem_specific/Invertible Neural Network Tutorial/index.html b/v2.16.2/examples/problem_specific/Invertible Neural Network Tutorial/index.html new file mode 100644 index 000000000..75c744537 --- /dev/null +++ b/v2.16.2/examples/problem_specific/Invertible Neural Network Tutorial/index.html @@ -0,0 +1,293 @@ + +Invertible neural networks: a tutorial · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Invertible neural networks: a tutorial

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

Table of contents

  1. Introduction
  2. Model specification
  3. Model compilation
  4. Probabilistic inference
  5. Parameter estimation

Introduction

Load required packages

Before we can start, we need to import some packages:

using RxInfer
+using Random
+using StableRNGs
+
+using ReactiveMP        # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality
+using LinearAlgebra     # only used for some matrix specifics
+using Plots             # only used for visualisation
+using Distributions     # only used for sampling from multivariate distributions
+using Optim             # only used for parameter optimisation

Model specification

Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as 

model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Alternatively, the input_dim can also be passed as an InputLayer layer as 

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

In the above AdditiveCouplingLayer layers the input ${\bf{x}} = [x_1, x_2, \ldots, x_N]$ is partitioned into chunks of unit length. These partitions are additively coupled to an output ${\bf{y}} = [y_1, y_2, \ldots, y_N]$ as

\[\begin{aligned} + y_1 &= x_1 \\ + y_2 &= x_2 + f_1(x_1) \\ + \vdots \\ + y_N &= x_N + f_{N-1}(x_{N-1}) +\end{aligned}\]

Importantly, this structure can easily be converted as

\[\begin{aligned} + x_1 &= y_1 \\ + x_2 &= y_2 - f_1(x_1) \\ + \vdots \\ + x_N &= y_N - f_{N-1}(x_{N-1}) +\end{aligned}\]

\[f_n\]

is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.

A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.

model = FlowModel(
+    (
+        InputLayer(2),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false),
+        PermutationLayer(PermutationMatrix(2)),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

Model compilation

In the current models, the layers are setup to work with the passed input dimension. This means that the function $f_n$ is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get

model
FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P
+lanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa
+yerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou
+plingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar
+FlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad
+ditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive
+MP.PlanarFlowEmpty{1}(),), 1)))

The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):

  • FlowModel - specifies that we are dealing with a flow model.
  • 3 - Number of layers.
  • Tuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.
  • Tuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions $f_n$.
  • PermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].

From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as

compiled_model = compile(model)
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(-0.5530639593835304, -0.2163616
+102550308, 1.2521116434309154),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.34763211887023543, -0.9116171319236555, -0.0789378301
+24018),), 1)))

Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.

compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow
+{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, 
+Float64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361
+28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]
+), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo
+w{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323
+52386),), 1)))

Probabilistic inference

We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.

function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)
+
+    rng = StableRNG(seed)
+    
+    # specify latent sampling distribution
+    dist = MvNormal([1.5, 0.5], I)
+
+    # sample from the latent distribution
+    x = rand(rng, dist, nr_samples)
+
+    # transform data
+    y = zeros(Float64, size(x))
+    for k = 1:nr_samples
+        y[:,k] .= ReactiveMP.forward(model, x[:,k])
+    end
+
+    # return data
+    return y, x
+
+end;
# generate data
+y, x = generate_data(1000, compiled_model)
+
+# plot generated data
+p1 = scatter(x[1,:], x[2,:], alpha=0.3, title="Original data", size=(800,400))
+p2 = scatter(y[1,:], y[2,:], alpha=0.3, title="Transformed data", size=(800,400))
+plot(p1, p2, legend = false)

The probabilistic model for doing inference can be described as 

@model function invertible_neural_network(nr_samples::Int64)
+    
+    # initialize variables
+    z_μ   = randomvar()
+    z_Λ   = randomvar()
+    x     = randomvar(nr_samples)
+    y_lat = randomvar(nr_samples)
+    y     = datavar(Vector{Float64}, nr_samples)
+
+    # specify prior
+    z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))
+    z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)
+
+        # specify transformed latent value
+        y_lat[k] ~ Flow(x[k])
+
+        # specify observations
+        y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))
+
+    end
+
+    # return variables
+    return z_μ, z_Λ, x, y_lat, y
+
+end;

Here the model is passed inside a meta data object of the flow node. Inference then resorts to

observations = [y[:,k] for k=1:size(y,2)]
+
+fmodel         = invertible_neural_network(length(observations))
+data          = (y = observations, )
+initmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))
+returnvars    = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())
+
+constraints = @constraints begin
+    q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)
+end
+
+@meta function fmeta(model)
+    compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))
+    Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). 
+                                               # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))
+end
+
+# First execution is slow due to Julia's initial compilation 
+result = infer(
+    model = fmodel, 
+    data  = data,
+    constraints   = constraints,
+    meta          = fmeta(model),
+    initmarginals = initmarginals,
+    returnvars    = returnvars,
+    free_energy   = true,
+    iterations    = 10, 
+    showprogress  = false
+)
Inference results:
+  Posteriors       | available for (z_μ, z_Λ, y_lat, x)
+  Free Energy:     | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357
+0.6, 23570.6, 23570.6, 23570.6, 23570.6]
fe_flow = result.free_energy
+zμ_flow = result.posteriors[:z_μ]
+zΛ_flow = result.posteriors[:z_Λ]
+x_flow  = result.posteriors[:x]
+y_flow  = result.posteriors[:y_lat];

As we can see, the variational free energy decreases inside of our model.

plot(1:10, fe_flow/size(y,2), xlabel="iteration", ylabel="normalized variational free energy [nats/sample]", legend=false)

If we plot a random noisy observation and its approximated transformed uncertainty we obtain:

# pick a random observation
+id = rand(StableRNG(321), 1:size(y,2))
+rand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))
+warped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');
+
+p1 = scatter(x[1,:], x[2,:], alpha=0.1, title="Latent distribution", size=(1200,500), label="generated data")
+contour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)
+scatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color="red", markershape=:x, markersize=5, label="inferred mean")
+contour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors="red", levels=1, linewidth=2, colorbar=false)
+scatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color="red", label="transformed noisy observation")
+p2 = scatter(y[1,:], y[2,:], alpha=0.1, label="generated data")
+scatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color="red", marker=:x, label="inferred mean")
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)
+contour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors="red", levels=1, linewidth=2, label="random noisy observation", colorba=false)
+scatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color="red", label="random noisy observation")
+plot(p1, p2, legend = true)

Parameter estimation

The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+
+    # sample weights
+    w = rand(rng, nr_samples, 2)
+
+    # sample appraisal
+    y = zeros(Float64, nr_samples)
+    for k = 1:nr_samples
+        y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)
+    end
+
+    # return data
+    return y, w
+
+end;
data_y, data_x = generate_data(50);
+scatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel="w1", ylabel="w2", colorbar=false, legend=false)

We will then specify a possible model as

# specify flow model
+model = FlowModel(2,
+    (
+        AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow()),
+        AdditiveCouplingLayer(PlanarFlow(); permute=false)
+    )
+);

The corresponding probabilistic model for the binary classification task can be created as

@model function invertible_neural_network_classifier(nr_samples::Int64)
+    
+    # initialize variables
+    x_lat  = randomvar(nr_samples)
+    y_lat1 = randomvar(nr_samples)
+    y_lat2 = randomvar(nr_samples)
+    y      = datavar(Float64, nr_samples)
+    x      = datavar(Vector{Float64}, nr_samples)
+
+    # specify observations
+    for k = 1:nr_samples
+
+        # specify latent state
+        x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))
+
+        # specify transformed latent value
+        y_lat1[k] ~ Flow(x_lat[k])
+        y_lat2[k] ~ dot(y_lat1[k], [1, 1])
+
+        # specify observations
+        y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }
+
+    end
+
+    # return variables
+    return x_lat, x, y_lat1, y_lat2, y
+
+end;
fcmodel       = invertible_neural_network_classifier(length(data_y))
+data          = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )
+
+@meta function fmeta(model, params)
+    compiled_model = compile(model, params)
+    Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)
+end
fmeta (generic function with 2 methods)

Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as

For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.

function f(params)
+    Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure
+    result = infer(
+        model                   = fcmodel, 
+        data                    = data,
+        meta                    = fmeta(model, params),
+        free_energy             = true,
+        free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure
+        iterations              = 10, 
+        showprogress            = false
+    );
+    
+    result.free_energy[end]
+end;

Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:

res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)
  • uses finitediff and is slower/less accurate.

or

# create gradient function
+g = (x) -> ForwardDiff.gradient(f, x);
+
+# specify initial params
+params = randn(nr_params(model))
+
+# create custom optimizer (here Adam)
+optimizer = Adam(params; λ=1e-1)
+
+# allocate space for gradient
+∇ = zeros(nr_params(model))
+
+# perform optimization
+for it = 1:10000
+
+    # backward pass
+    ∇ .= ForwardDiff.gradient(f, optimizer.x)
+
+    # gradient update
+    ReactiveMP.update!(optimizer, ∇)
+
+end
+
res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)
Iter     Function value   Gradient norm 
+     0     5.888958e+02     8.943663e+02
+ * time: 0.024276018142700195
+   100     1.059826e+01     4.120090e+00
+ * time: 13.0049409866333
+ * Status: success
+
+ * Candidate solution
+    Final objective value:     1.010332e+01
+
+ * Found with
+    Algorithm:     Gradient Descent
+
+ * Convergence measures
+    |x - x'|               = 1.21e-03 ≰ 0.0e+00
+    |x - x'|/|x'|          = 5.80e-04 ≰ 0.0e+00
+    |f(x) - f(x')|         = 6.28e-03 ≰ 0.0e+00
+    |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03
+    |g(x)|                 = 2.07e+00 ≰ 1.0e-08
+
+ * Work counters
+    Seconds run:   15  (vs limit Inf)
+    Iterations:    113
+    f(x) calls:    301
+    ∇f(x) calls:   301

optimization results are then given as

params = Optim.minimizer(res)
+inferred_model = compile(model, params)
+trans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'
+trans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])
+trans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title="original data")
+p2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title="|> warp")
+p3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title="|> dot")
+plot(p1, p2, p3, layout=(1,3), legend=false)

using StatsFuns: normcdf
+p1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title="original labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title="predicted labels", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+p3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title="Classification map", xlabel="weight 1", ylabel="weight 2", size=(1200,400), c=:viridis)
+plot(p1, p2, p3, layout=(1,3), legend=false)

diff --git a/v2.16.2/examples/problem_specific/Probit Model (EP)/index.html b/v2.16.2/examples/problem_specific/Probit Model (EP)/index.html new file mode 100644 index 000000000..85186ff71 --- /dev/null +++ b/v2.16.2/examples/problem_specific/Probit Model (EP)/index.html @@ -0,0 +1,76 @@ + +Probit Model (EP) · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Probit Model (EP)

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable $x_t$ with the discrete variable $y_t$. The model is defined as:

\[\begin{aligned} + u &= 0.1 \\ + x_0 &\sim \mathcal{N}(0, 100) \\ + x_t &\sim \mathcal{N}(x_{t-1}+ u, 0.01) \\ + y_t &\sim \mathrm{Ber}(\Phi(x_t)) +\end{aligned}\]

Import packages

using RxInfer, StableRNGs, Random, Plots
+using StatsFuns: normcdf

Data generation

function generate_data(nr_samples::Int64; seed = 123)
+    
+    rng = StableRNG(seed)
+    
+    # hyper parameters
+    u = 0.1
+
+    # allocate space for data
+    data_x = zeros(nr_samples + 1)
+    data_y = zeros(nr_samples)
+    
+    # initialize data
+    data_x[1] = -2
+    
+    # generate data
+    for k = 2:nr_samples + 1
+        
+        # calculate new x
+        data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)
+        
+        # calculate y
+        data_y[k-1] = normcdf(data_x[k]) > rand(rng)
+        
+    end
+    
+    # return data
+    return data_x, data_y
+    
+end;
n = 40
40
data_x, data_y = generate_data(n);
p = plot(xlabel = "t", ylabel = "x, y")
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x")

Model specification

@model function probit_model(nr_samples::Int64)
+    
+    # allocate space for variables
+    x = randomvar(nr_samples + 1)
+    y = datavar(Float64, nr_samples)
+    
+    # specify uninformative prior
+    x[1] ~ Normal(mean = 0.0, precision = 0.01)
+    
+    # create model 
+    for k = 2:nr_samples + 1
+        x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)
+        y[k - 1] ~ Probit(x[k]) where {
+            # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge
+            # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations
+            pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) 
+        }
+    end
+    
+end;

Inference

result = infer(
+    model = probit_model(length(data_y)), 
+    data  = (y = data_y, ), 
+    iterations = 5, 
+    returnvars = (x = KeepLast(),),
+    free_energy  = true
+)
Inference results:
+  Posteriors       | available for (x)
+  Free Energy:     | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]

Results

mx = result.posteriors[:x]
+
+p = plot(xlabel = "t", ylabel = "x, y", legend = :bottomright)
+p = scatter!(p, data_y, label = "y")
+p = plot!(p, data_x[2:end], label = "x", lw = 2)
+p = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label="x (inferred mean)")
+
+f = plot(xlabel = "t", ylabel = "BFE")
+f = plot!(result.free_energy, label = "Bethe Free Energy")
+
+plot(p, f, size = (800, 400))

diff --git a/v2.16.2/examples/problem_specific/RTS vs BIFM Smoothing/index.html b/v2.16.2/examples/problem_specific/RTS vs BIFM Smoothing/index.html new file mode 100644 index 000000000..22da8dc13 --- /dev/null +++ b/v2.16.2/examples/problem_specific/RTS vs BIFM Smoothing/index.html @@ -0,0 +1,242 @@ + +RTS vs BIFM Smoothing · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

RTS vs BIFM Smoothing

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();

___Credits to Martin de Quincey___

This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:

  1. F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762
  2. H. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.

We perform Kalman smoothing in the linear state space model, represented by:

\[\begin{aligned} + Z_{k+1} &= A Z_k + B U_k \\ + Y_k &= C Z_k + W_k +\end{aligned}\]

with observations $Y_k$, latent states $Z_k$ and inputs $U_k$. $W_k$ is the observation noise. $A \in \mathrm{R}^{n \times n}$, $B \in \mathrm{R}^{n \times m}$ and $C \in \mathrm{R}^{d \times n}$ are the transition matrices in the model. Here $n$, $m$ and $d$ denote the dimensionality of the latent, input and output dimension, respectively.

The corresponding probabilistic model can be represented as

\[\begin{aligned} + p(y,\ z,\ u) + &= p(z_0) \prod_{k=1}^N p(y_k \mid z_k)\ p(z_k\mid z_{k-1},\ u_{k-1})\ p(u_{k-1}) \\ + &= \mathcal{N}(z_0 \mid \mu_{z_0}, \Sigma_{z_0}) \left( \prod_{k=1}^N \mathcal{N}(y_k \mid C z_k,\ \Sigma_W)\ \delta(z_k - (Az_{k-1} + Bu_{k-1})) \mathcal{N}(u_{k-1} \mid \mu_{i_{k-1}},\ \Sigma_{u_{k-1}}) \right) +\end{aligned}\]

Import packages

using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs

Data generation

function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)
+    
+    # define noise levels
+    input_noise  = 500.0
+    output_noise = 50.0
+
+    # create random generator for reproducibility
+    rng = MersenneTwister(seed)
+
+    # generate matrices, input statistics and noise matrices
+    A      = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat))                                            # size (dim_lat x dim_lat)
+    B      = rand(dim_lat, dim_in)                                                                              # size (dim_lat x dim_in)
+    C      = rand(dim_out, dim_lat)                                                                             # size (dim_out x dim_lat)
+    μu     = rand(dim_in) .* collect(1:dim_in)                                                                  # size (dim_in x 1)
+    Σu     = input_noise  .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in))))      # size (dim_in x dim_in)
+    Σy     = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out))))   # size (dim_out x dim_out)
+    Wu     = inv(Σu)
+    Wy     = inv(Σy)
+    
+    # return parameters
+    return A, B, C, μu, Σu, Σy, Wu, Wy
+
+end;
function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)
+        
+    # create random data generator
+    rng = StableRNG(seed)
+    
+    # preallocate space for variables
+    z = Vector{Vector{Float64}}(undef, nr_samples)
+    y = Vector{Vector{Float64}}(undef, nr_samples)
+    u = rand(rng, MvNormal(μu, Σu), nr_samples)'
+    
+    # set initial value of latent states
+    z_prev = zeros(size(A,1))
+    
+    # generate data
+    for i in 1:nr_samples
+
+        # generate new latent state
+        z[i] = A * z_prev + B * u[i,:]
+
+        # generate new observation
+        y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))
+        
+        # generate new observation
+        z_prev .= z[i]
+        
+    end
+    
+    # return generated data
+    return z, y, u
+    
+end
generate_data (generic function with 1 method)
# specify settings
+nr_samples = 200
+dim_out = 3
+dim_in = 3
+dim_lat = 25
+
+# generate parameters
+A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);
+            
+# generate data
+data_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);
+
+# visualise data
+p = Plots.plot(xlabel = "sample", ylabel = "observations")
+# plot each dimension independently
+for i in 1:dim_out
+    Plots.scatter!(p, getindex.(data_y, i), label = "y_$i", alpha = 0.5, ms = 2)
+end
+p

Model specification

@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+    
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    dim_out = size(C, 1)
+    
+    # initialize variables
+    z = randomvar(nr_samples)                 # hidden states (random variable)
+    u = randomvar(nr_samples)                 # inputs (random variable)
+    y = datavar(Vector{Float64}, nr_samples)  # outputs (observed variables)
+    
+    # set initial hidden state
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    
+    # update last/previous hidden state
+    z_prev = z_prior
+
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i] ~ MvNormalMeanPrecision(μu, Wu)
+        
+        # specify updated hidden state
+        z[i] ~ A * z_prev + B * u[i]
+        
+        # specify observation
+        y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+end
@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})
+
+    # fetch dimensionality
+    dim_lat = size(A, 1)
+    
+    # initialize variables
+    z  = randomvar(nr_samples)                  # latent states
+    yt = randomvar(nr_samples)                  # latent observations
+    y  = datavar(Vector{Float64}, nr_samples)   # actual observations
+    u  = randomvar(nr_samples)                  # inputs
+    
+    # set priors
+    z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))
+    z_tmp   ~ BIFMHelper(z_prior) where { q = MeanField() }
+    
+    # update last/previous hidden state
+    z_prev = z_tmp
+    
+    # loop through observations
+    for i in 1:nr_samples
+
+        # specify input as random variable
+        u[i]   ~ MvNormalMeanPrecision(μu, Wu)
+
+        # specify observation
+        yt[i]  ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }
+        y[i]   ~ MvNormalMeanPrecision(yt[i], Wy)
+        
+        # update last/previous hidden state
+        z_prev = z[i]
+
+    end
+    
+    # set final value
+    z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))
+    
+end

Probabilistic inference

function inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+    
+    # In this task the inference is unstable and can diverge
+    meta = @meta begin 
+        *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)
+    end
+    
+    result = infer(
+        model      = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast()),
+        meta = meta
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_RTS (generic function with 1 method)
function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)
+    result = infer(
+        model      = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),
+        data       = (y = data_y, ),
+        returnvars = (z = KeepLast(), u = KeepLast())
+    )
+    qs = result.posteriors
+    return (qs[:z], qs[:u])
+end
inference_BIFM (generic function with 1 method)

Experiments for 200 observations

z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)
+z_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);
ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state z")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state z")
+
+mz_RTS = mean.(z_RTS)
+mz_BIFM = mean.(z_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:5
+    Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

ax1 = Plots.plot(title = "RTS smoother", xlabel = "sample", ylabel = "latent state u")
+ax2 = Plots.plot(title = "BIFM smoother", xlabel = "sample", ylabel = "latent state u")
+
+rdata_u = collect(eachrow(data_u))
+mu_RTS = mean.(u_RTS)
+mu_BIFM = mean.(u_BIFM)
+
+# Do not plot all latent states, otherwise the output is just too cluttered
+# The main idea here is to check that both algorithms return the (approximately) same output
+for i in 1:1
+    Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)
+    Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)
+    Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)    
+    Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)
+end
+
+Plots.plot(ax1, ax2, layout = @layout([ a; b ]))

Benchmark

# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation
+# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`
+run_benchmark = false
+
+if run_benchmark
+    trials_range = 30
+    trials_n = 500
+    trials_RTS  = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+    trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)
+
+
+    @showprogress for k = 1 : trials_range
+
+        # generate parameters
+        local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);
+                    
+        # generate data|
+        local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);
+
+        # run inference
+        trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+        trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)
+
+    end
+
+    m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9
+    q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9
+    m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9
+    q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9
+    q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;
+
+    p = Plots.plot(ylabel = "duration [sec]", xlabel = "latent state dimension", title = "Benchmark", yscale = :log)
+    p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = "blue", label = "mean (RTS)")
+    p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = "orange", label = "mean (BIFM)")
+    Plots.savefig(p, "../pics/rts_bifm_benchmark.png")
+    p
+end

diff --git a/v2.16.2/examples/problem_specific/Simple Nonlinear Node/index.html b/v2.16.2/examples/problem_specific/Simple Nonlinear Node/index.html new file mode 100644 index 000000000..295846806 --- /dev/null +++ b/v2.16.2/examples/problem_specific/Simple Nonlinear Node/index.html @@ -0,0 +1,67 @@ + +Simple Nonlinear Node · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Simple Nonlinear Node

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Random, StableRNGs

Here is an example of creating custom node with nonlinear function approximation with samplelist.

Custom node creation

struct NonlinearNode end # Dummy structure just to make Julia happy
+
+struct NonlinearMeta{R, F}
+    rng      :: R
+    fn       :: F   # Nonlinear function, we assume 1 float input - 1 float output
+    nsamples :: Int # Number of samples used in approximation
+end
@node NonlinearNode Deterministic [ out, in ]

We need to define two Sum-product message computation rules for our new custom node

  • Rule for outbound message on out edge given inbound message on in edge
  • Rule for outbound message on in edge given inbound message on out edge
  • Both rules accept optional meta object
# Rule for outbound message on `out` edge given inbound message on `in` edge
+@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin 
+    samples = rand(meta.rng, m_in, meta.nsamples)
+    return SampleList(map(meta.fn, samples))
+end
# Rule for outbound message on `in` edge given inbound message on `out` edge
+@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin     
+    return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))
+end

Model specification

After we have defined our custom node with custom rules we may proceed with a model specification:

\[\begin{aligned} +p(\theta) &= \mathcal{N}(\theta|\mu_{\theta}, \sigma_{\theta}),\\ +p(m) &= \mathcal{N}(\theta|\mu_{m}, \sigma_{m}),\\ +p(w) &= f(\theta),\\ +p(y_i|m, w) &= \mathcal{N}(y_i|m, w), +\end{aligned}\]

Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable $\theta$ through a non-linear transformation $f$ to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of $\theta$. 

@model function nonlinear_estimation(n)
+    
+    θ ~ Normal(mean = 0.0, variance = 100.0)
+    m ~ Normal(mean = 0.0, variance = 1.0)
+    
+    w ~ NonlinearNode(θ)
+    
+    y = datavar(Float64, n)
+    
+    for i in 1:n
+        y[i] ~ Normal(mean = m, precision = w)
+    end
+    
+end
@constraints function nconstsraints(nsamples)
+    q(θ) :: SampleList(nsamples, LeftProposal())
+    q(w) :: SampleList(nsamples, RightProposal())
+    
+    q(θ, w, m) = q(θ)q(m)q(w)
+end
nconstsraints (generic function with 1 method)
@meta function nmeta(fn, nsamples)
+    NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)
+end
nmeta (generic function with 1 method)

Here we generate some data

nonlinear_fn(x) = abs(exp(x) * sin(x))
nonlinear_fn (generic function with 1 method)
seed = 123
+rng  = StableRNG(seed)
+
+niters   = 15 # Number of VMP iterations
+nsamples = 5_000 # Number of samples in approximation
+
+n = 500 # Number of IID samples
+μ = -10.0
+θ = -1.0
+w = nonlinear_fn(θ)
+
+data = rand(rng, NormalMeanPrecision(μ, w), n);
result = infer(
+    model = nonlinear_estimation(n),
+    meta =  nmeta(nonlinear_fn, nsamples),
+    constraints = nconstsraints(nsamples),
+    data = (y = data, ), 
+    initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),
+    returnvars = (θ = KeepLast(), ),
+    iterations = niters,  
+    showprogress = true
+)
Inference results:
+  Posteriors       | available for (θ)
θposterior = result.posteriors[:θ]
SampleList(Univariate, 5000)
using Plots, StatsPlots
+
+estimated = Normal(mean_std(θposterior)...)
+
+plot(estimated, title="Posterior for θ", label = "Estimated", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))
+vline!([ θ ], label = "Real value of θ")

diff --git a/v2.16.2/examples/problem_specific/Universal Mixtures/index.html b/v2.16.2/examples/problem_specific/Universal Mixtures/index.html new file mode 100644 index 000000000..6a7f398be --- /dev/null +++ b/v2.16.2/examples/problem_specific/Universal Mixtures/index.html @@ -0,0 +1,94 @@ + +Universal Mixtures · RxInfer.jl
GitHub

This example has been auto-generated from the examples/ folder at GitHub repository.

Universal Mixtures

# Activate local environment, see `Project.toml`
+import Pkg; Pkg.activate(".."); Pkg.instantiate();
using RxInfer, Distributions, Random, Plots

John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment

\[p(y_i \mid \theta) = \mathrm{Ber}(y_i \mid \theta),\]

where $y_i \in \{0,1\}$ are the outcomes of the coin tosses, i.e. heads or tails, and where $\theta$ is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter $\theta$, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of $\theta\in[0,1]$ they come up with the prior beliefs:

\[p(\theta \mid \text{John}) = \mathrm{Beta}(\theta \mid 7, 2)\]

\[p(\theta \mid \text{Jane}) = \mathrm{Beta}(\theta \mid 2, 7)\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior beliefs")
+plot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label="P(θ) John", c=1)
+plot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label="p(θ) Jane", c=3,)

John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. 

true_coin = Bernoulli(0.25)
+nr_throws = 10
+dataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))
+nr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)
+println("experimental outcome: \n - heads: ", nr_heads, "\n - tails: ", nr_tails);
experimental outcome: 
+ - heads: 3
+ - tails: 7

For computing the posterior beliefs $p(\theta \mid y)$ about the parameter $\theta$, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:

John's model:

\[p(y, \theta \mid \text{John}) = p(\theta \mid \text{John}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_john(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's prior model over θ
+    θ ~ Beta(7.0, 2.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Jane's model:

\[p(y, \theta \mid \text{Jane}) = p(\theta \mid \text{Jane}) \prod_{i=1}^N p(y_i \mid \theta)\]

@model function beta_model_jane(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify Jane's prior model over θ
+    θ ~ Beta(2.0, 7.0)
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy $\mathrm{F}_B$ bounds the model evidence $p(y)$ as

\[\mathrm{F}_B[p,q] \geq - \ln p(y)\]

result_john = infer(
+    model = beta_model_john(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true,
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[8.96366]
result_jane = infer(
+    model = beta_model_jane(nr_throws), 
+    data  = (y = dataset, ),
+    free_energy = true
+)
Inference results:
+  Posteriors       | available for (θ)
+  Free Energy:     | Real[6.63988]

From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying $\theta$ parameter. They formulate this through the posterior distributions $p(\theta \mid y, \text{John})$ and $p(\theta \mid y, \text{Jane})$:

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior beliefs")
+plot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) John", c=1)
+plot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="p(θ|y) Jane", c=3,)

What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over $\theta$, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as

\[p(y, \theta, c \mid \text{Mary}) = p(c \mid \text{Mary}) \, p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} \prod_{i=1}^N p(y_i \mid \theta),\]

where $c$ describes the probability of John being correct as

\[p(c \mid \text{Mary}) = \mathrm{Ber}(c \mid 0.7)\]

The predictive distribution $p(\theta \mid \text{Mary})$ for $\theta$ (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over $c$ as

\[p(\theta \mid \text{Mary}) = \sum_{c\in\{0,1\}} p(c\mid\text{Mary}) p(\theta \mid \text{John})^c p(\theta \mid \text{Jane})^{1-c} = 0.7 \cdot p(\theta \mid \text{John}) + 0.3 \cdot p(\theta \mid \text{Jane})\]

rθ = range(0, 1, length = 1000)
+p = plot(title = "prior belief")
+plot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label="P(θ) Mary", c=1)
+plot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label="")
+plot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label="")

She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:

@model function beta_model_mary(nr_throws)
+
+    # specify experimental outcomes
+    y = datavar(Int64, nr_throws)
+
+    # specify John's and Jane's prior models over θ
+    θ_jane ~ Beta(2.0, 7.0)
+    θ_john ~ Beta(7.0, 2.0)
+
+    # specify initial guess as to who is right
+    john_is_right ~ Bernoulli(0.7) 
+
+    # specify mixture prior Distribution
+    θ ~ Mixture(john_is_right, (θ_jane, θ_john))
+
+    # create likelihood models
+    for i in 1:nr_throws
+        y[i] ~ Bernoulli(θ)
+    end
+
+    return y, θ
+    
+end

This Mixture node updates the belief over $c$ on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.

result_mary = infer(
+    model = beta_model_mary(nr_throws), 
+    data  = (y = dataset, ),
+    returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),
+    addons = AddonLogScale(),
+    postprocess = UnpackMarginalPostprocess(),
+)
Inference results:
+  Posteriors       | available for (john_is_right, θ_john, θ, θ_jane)

Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over $\theta$ also changed, and as expected the estimate from Jane was more prominent.

rθ = range(0, 1, length = 1000)
+p = plot(title = "posterior belief")
+plot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label="P(θ|y) Mary", c=1)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label="", c=3)
+plot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label="", c=3)

diff --git a/v2.16.2/examples/problem_specific/overview/index.html b/v2.16.2/examples/problem_specific/overview/index.html new file mode 100644 index 000000000..65f0004c1 --- /dev/null +++ b/v2.16.2/examples/problem_specific/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Problem specific

This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.

Note

All examples have been pre-generated automatically from the examples/ folder at GitHub repository.

Problem specific examples contain specialized models and inference for various domains.

diff --git a/v2.16.2/index.html b/v2.16.2/index.html new file mode 100644 index 000000000..3eb5d2b9d --- /dev/null +++ b/v2.16.2/index.html @@ -0,0 +1,2 @@ + +Home · RxInfer.jl
GitHub

RxInfer

Julia package for automatic Bayesian inference on a factor graph with reactive message passing.

Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.

Package Features

  • User friendly syntax for specification of probabilistic models.
  • Automatic generation of message passing algorithms including
  • Support for hybrid models combining discrete and continuous latent variables.
  • Support for hybrid distinct message passing inference algorithm under a unified paradigm.
  • Factorisation and functional form constraints specification.
  • Evaluation of Bethe free energy as a model performance measure.
  • Schedule-free reactive message passing API.
  • High performance.
  • Scalability for large models with millions of parameters and observations.
  • Inference procedure is differentiable.
  • Easy to extend with custom nodes and message update rules.

Why RxInfer

Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a "variational Free Energy" cost function. For large models, manual derivation of these gradients might not be feasible, while automated "black-box" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.

RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different "what-if" scenarios and enables very efficient inference in specific cases.

Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.

How to get started?

Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.

Table of Contents

References

Ecosystem

The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:

  • ReactiveMP.jl - core package for efficient and scalable for reactive message passing
  • GraphPPL.jl - package for model and constraints specification
  • Rocket.jl - reactive programming tools

Index

diff --git a/v2.16.2/library/bethe-free-energy/index.html b/v2.16.2/library/bethe-free-energy/index.html new file mode 100644 index 000000000..8d3589cbf --- /dev/null +++ b/v2.16.2/library/bethe-free-energy/index.html @@ -0,0 +1,2 @@ + +Bethe Free Energy · RxInfer.jl
GitHub

Bethe Free Energy implementation in RxInfer

The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.

Factorized model

Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, $y = (y_1, \dots, y_j, \dots, y_m)\,,$ and variables that can not be observed directly, also known as latent variables, $x = (x_1, \dots, x_i, \dots, x_n)\,.$ We then define a model that factorizes over consituent smaller factors (functions), as $f(y,x) = \prod_a f_a(y_a,x_a)\,.$

Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).

Variational Free Energy

The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, $F[q](\hat{y}) = \mathbb{E}_{q(x)}\left[\log \frac{q(x)}{f(y=\hat{y}, x)} \right]\,.$ A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.

The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.

Variational inference

The goal of variational inference is to find a variational distibution that minimizes the VFE, $q^{*}(x) = \arg\min_{q\in\mathcal{Q}} F[q](\hat{y})\,.$ This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.

For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.

Bethe approximation

Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.

A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, $q(x) \triangleq \frac{\prod_a q_a(x_a)}{\prod_i q_i(x_i)^{d_i - 1}}\,.$ The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.

The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.

The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.

Bethe Free Energy

The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as $F_B[q](\hat{y}) = \sum_a U_a[q_a](\hat{y}_a) - \sum_a H[q_a] + \sum_i (d_i - 1) H[q_i]\,.$ The first term of the BFE specifies an average energy, $U_a[q_a](\hat{y}_a) = -\mathbb{E}_{q_a(x_a)}\left[\log f_a(y_a=\hat{y}_a, x_a)\right]\,,$ which internalizes the factors of the model. The last two terms specify entropies.

Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.

For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.

For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.

Further reading

  • Pearl (1986) on the original foundations of Bayesian networks and belief propagation;
  • Yedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;
  • Dauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);
  • Senoz et al. (2021) on constraint manipulation and message passing on FFGs.
RxInfer.AbstractScoreObjective — Type
AbstractScoreObjective

Abstract type for functional objectives that can be used in the score function.

Note

score is defined in the ReactiveMP package.

source
RxInfer.BetheFreeEnergy — Type
BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)

Creates Bethe Free Energy values stream when passed to the score function.

source
RxInfer.apply_diagnostic_check — Function
apply_diagnostic_check(check, context, stream)

This function applies a check to the stream. Accepts optional context object for custom error messages.

source
diff --git a/v2.16.2/library/exported-methods/index.html b/v2.16.2/library/exported-methods/index.html new file mode 100644 index 000000000..ccd08e6ed --- /dev/null +++ b/v2.16.2/library/exported-methods/index.html @@ -0,0 +1,860 @@ + +Exported methods · RxInfer.jl
GitHub

Using methods from RxInfer

In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:

using RxInfer

A nice explanation about how modules/packages work in Julia can be found in the official documentation.

In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:

import RxInfer: mean

One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:

import RxInfer: mean as mean_from_rxinfer
+import Distributions: mean as mean_from_distributions
+
+mean_from_rxinfer === mean_from_distributions
true

Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.

# It is easier to let Julia resolve names automatically
+# Julia will not overwrite `mean` that is coming from both packages
+using RxInfer, Distributions
mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`
0.0
mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`
0.0

List of available methods

Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.

Note

Some exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.

foreach(println, names(RxInfer))
@autoupdates
+@average_energy
+@call_marginalrule
+@call_rule
+@constraints
+@logscale
+@marginalrule
+@meta
+@model
+@node
+@rule
+AND
+AR
+ARMeta
+ARsafe
+ARunsafe
+AbstractActor
+AbstractActorFactory
+AbstractApproximationMethod
+AbstractFormConstraint
+AbstractMStorage
+AbstractMessage
+AbstractMixtureModel
+AbstractMvNormal
+AbstractOperator
+AbstractPipelineStage
+AbstractSubject
+AbstractSubjectFactory
+AbstractSubscribable
+AbstractVariable
+Actor
+ActorProxy
+ActorSourceProxy
+ActorTrait
+Adam
+AdditiveCouplingLayer
+AddonDebug
+AddonLogScale
+AddonMemory
+Arcsine
+ArrayLikeVariate
+ArrayObservable
+AsapScheduler
+AsyncPipelineStage
+AsyncScheduler
+AutoProposal
+AutoVar
+Autoregressive
+AverageEnergy
+BIFM
+BIFMHelper
+BIFMMeta
+BaseActorTrait
+BayesBase
+BehaviorSubject
+BehaviorSubjectFactory
+Bernoulli
+BernoulliLogit
+Beta
+BetaBinomial
+BetaPrime
+BetheFreeEnergy
+BetheFreeEnergyCheckInfs
+BetheFreeEnergyCheckNaNs
+BetheFreeEnergyDefaultChecks
+BetheFreeEnergyDefaultMarginalSkipStrategy
+Binomial
+Biweight
+BufferActor
+CTMeta
+CTransition
+CVI
+CallableTeardownLogic
+Categorical
+Cauchy
+Chernoff
+Chi
+Chisq
+CholeskyVariate
+CircularKeepActor
+ClosedProd
+CompanionMatrix
+CompanionMatrixTransposed
+CompiledFlowModel
+CompletedObservable
+CompletionActor
+CompletionActorTrait
+CompositeFormConstraint
+CompositePipelineStage
+ConnectableObservable
+ConstVariable
+ConstantBaseMeasure
+ConstraintsSpecification
+Contingency
+Continuous
+ContinuousDistribution
+ContinuousMatrixDistribution
+ContinuousMultivariateDistribution
+ContinuousMultivariateLogPdf
+ContinuousTransition
+ContinuousTransitionMeta
+ContinuousUnivariateDistribution
+ContinuousUnivariateLogPdf
+Cosine
+CountingReal
+CustomProdStrategy
+DataVariable
+DefaultConstraints
+DefaultMeta
+DefaultPostprocess
+DeltaFn
+DeltaFnNode
+DeltaMeta
+Deterministic
+DiagNormal
+DiagNormalCanon
+DifferentialEntropy
+Dirac
+Dirichlet
+DirichletMultinomial
+DiscontinuePipelineStage
+Discrete
+DiscreteDistribution
+DiscreteMatrixDistribution
+DiscreteMultivariateDistribution
+DiscreteNonParametric
+DiscreteUniform
+DiscreteUnivariateDistribution
+Distribution
+Distributions
+Domain
+DoubleExponential
+EdgeworthMean
+EdgeworthSum
+EdgeworthZ
+EmptyPipelineStage
+Epanechnikov
+Erlang
+ErrorActor
+ErrorActorTrait
+Estimator
+Exponential
+ExponentialFamily
+ExponentialFamilyDistribution
+ExponentialFamilyDistributionAttributes
+ExtraArgumentInCompleteCall
+FDist
+FactorBoundFreeEnergy
+FactorGraphModel
+FactorNodeCreationOptions
+FactorNodesCollection
+FactorizedJoint
+FastCholesky
+FaultedObservable
+FirstNotFoundException
+FisherNoncentralHypergeometric
+Flow
+FlowMeta
+FlowModel
+FoldLeftProdStrategy
+FoldRightProdStrategy
+FormConstraintCheckEach
+FormConstraintCheckLast
+FormConstraintCheckPickDefault
+ForwardDiffGrad
+Frechet
+FullFactorisation
+FullNormal
+FullNormalCanon
+FunctionActor
+FunctionObservable
+GCV
+GCVMetadata
+Gamma
+GammaDistributionsFamily
+GammaInverse
+GammaMixture
+GammaMixtureNode
+GammaShapeRate
+GammaShapeScale
+GaussHermiteCubature
+GaussLaguerreQuadrature
+GaussianDistributionsFamily
+GaussianMeanPrecision
+GaussianMeanVariance
+GaussianMixture
+GaussianMixtureNode
+GaussianWeighteMeanPrecision
+GeneralizedExtremeValue
+GeneralizedPareto
+GenericProd
+Geometric
+GraphPPL
+Gumbel
+HalfNormal
+Hypergeometric
+IMPLY
+ImportanceSamplingApproximation
+IncludeAll
+InconsistentActorWithSubscribableDataTypesError
+InconsistentSourceActorDataTypesError
+InconsistentSourceOperatorDataTypesError
+InconsistentSubjectDataTypesError
+InferableOperator
+InferableOperatorTrait
+InferenceResult
+InputLayer
+InvalidActorTrait
+InvalidActorTraitUsageError
+InvalidMultipleTeardownLogicTraitUsageError
+InvalidOperatorTrait
+InvalidOperatorTraitUsageError
+InvalidSubjectTrait
+InvalidSubjectTraitUsageError
+InvalidSubscribableTrait
+InvalidSubscribableTraitUsageError
+InvalidTeardownLogic
+InvalidTeardownLogicTraitUsageError
+InverseGamma
+InverseGaussian
+InverseWishart
+IsoNormal
+IsoNormalCanon
+JohnsonSU
+JointGaussian
+JointNormal
+JointOrderStatistics
+KSDist
+KSOneSided
+KeepActor
+KeepEach
+KeepLast
+Kolmogorov
+Kumaraswamy
+LKJ
+LKJCholesky
+LabeledObservable
+LambdaActor
+Laplace
+LaplaceApproximation
+LastNotFoundException
+LazyObservable
+LeftProposal
+LeftTypedOperator
+LeftTypedOperatorTrait
+Levy
+LimitSubscribersGuard
+Lindley
+Linearization
+LinearizedProductOf
+LocationScale
+LogNormal
+LogUniform
+LoggerActor
+LoggerPipelineStage
+Logistic
+LogitNormal
+MAX_PREGENERATED_MSTORAGE_SIZE
+MILLISECONDS_IN_SECOND
+MLEstimator
+Marginal
+Marginalisation
+MatrixBeta
+MatrixDirichlet
+MatrixDistribution
+MatrixFDist
+MatrixNormal
+MatrixReshaped
+MatrixTDist
+Matrixvariate
+MeanField
+MeanParametersSpace
+MeanToNatural
+Message
+MetaSpecification
+MissingCreateActorFactoryImplementationError
+MissingDataArgumentInNextCall
+MissingErrorArgumentInErrorCall
+MissingOnCallImplementationError
+MissingOnCompleteImplementationError
+MissingOnErrorImplementationError
+MissingOnNextImplementationError
+MissingOnScheduledSubscribeImplementationError
+MissingOnSubscribeImplementationError
+MissingOnUnsubscribeImplementationError
+MissingOperatorRightImplementationError
+Mixture
+MixtureDistribution
+MixtureModel
+MixtureNode
+MomentMatching
+Multinomial
+Multivariate
+MultivariateDistribution
+MultivariateGaussianDistributionsFamily
+MultivariateMixture
+MultivariateNormal
+MultivariateNormalDistributionsFamily
+MvGaussianMeanCovariance
+MvGaussianMeanPrecision
+MvGaussianWeightedMeanPrecision
+MvLogNormal
+MvLogitNormal
+MvNormal
+MvNormalCanon
+MvNormalKnownCov
+MvNormalMeanCovariance
+MvNormalMeanPrecision
+MvNormalMeanScalePrecision
+MvNormalWeightedMeanPrecision
+MvNormalWishart
+MvTDist
+NANOSECONDS_IN_MILLISECOND
+NANOSECONDS_IN_SECOND
+NOT
+NaturalParametersSpace
+NaturalToMean
+NegativeBinomial
+NetworkObservable
+NeverObservable
+NextActor
+NextActorTrait
+NonConstantBaseMeasure
+NonMatrixDistribution
+NoncentralBeta
+NoncentralChisq
+NoncentralF
+NoncentralHypergeometric
+NoncentralT
+NoopPostprocess
+Normal
+NormalCanon
+NormalDistributionsFamily
+NormalGamma
+NormalInverseGaussian
+NormalMeanPrecision
+NormalMeanVariance
+NormalMixture
+NormalMixtureNode
+NormalWeightedMeanPrecision
+OR
+OperatorTrait
+OperatorsComposition
+OrderStatistic
+OverrideHandler
+PGeneralizedGaussian
+Pareto
+PendingScheduler
+PendingSubject
+PendingSubjectFactory
+PermutationLayer
+PermutationMatrix
+PlanarFlow
+PointMass
+Poisson
+PoissonBinomial
+PostponeScheduler
+PreserveTypeLeftProd
+PreserveTypeProd
+PreserveTypeRightProd
+Probit
+ProbitMeta
+ProdCVI
+Product
+ProductOf
+ProxyObservable
+PushEach
+PushEachBut
+PushNew
+PushNewBut
+PushStrategy
+QQPair
+RadialFlow
+RandomVariable
+RandomVariableCreationOptions
+Rayleigh
+ReactiveMP
+RealInterval
+RecentSubject
+RecentSubjectFactory
+ReplaySubject
+ReplaySubjectFactory
+Rician
+RightProposal
+RightTypedOperator
+RightTypedOperatorTrait
+Rocket
+RxInfer
+RxInferenceEngine
+RxInferenceEvent
+SampleList
+SampleListMeta
+Sampleable
+ScheduledSubscribable
+ScheduledSubscribableTrait
+Semicircle
+ServerActor
+SimpleSubscribableTrait
+SingleObservable
+Skellam
+SkewNormal
+SkewedExponentialPower
+SkipClamped
+SkipClampedAndInitial
+SkipInitial
+SoftDot
+Soliton
+SourceProxy
+StandardBasisVector
+Stochastic
+StorageActor
+StudentizedRange
+Subject
+SubjectFactory
+SubjectTrait
+Subscribable
+SubscribableTrait
+SubstituteHandler
+SufficientStats
+SymTriangularDist
+SyncActor
+SyncActorTimedOutException
+SyncFileObservable
+TDist
+TapAfterSubscription
+TapAfterUnsubscription
+TapBeforeSubscription
+TapBeforeUnsubscription
+Teardown
+TeardownLogic
+TerminalProdArgument
+TimerObservable
+Transition
+TriangularDist
+Triweight
+Truncated
+TruncatedNormal
+TypedOperator
+TypedOperatorTrait
+UT
+Uniform
+Uninformative
+Univariate
+UnivariateDistribution
+UnivariateGMM
+UnivariateGaussianDistributionsFamily
+UnivariateMixture
+UnivariateNormalDistributionsFamily
+UnpackMarginalPostprocess
+Unscented
+UnscentedTransform
+UnspecifiedConstraints
+UnspecifiedDimension
+UnspecifiedDomain
+UnspecifiedFormConstraint
+UnspecifiedMeta
+UnsubscribableTeardownLogic
+ValidSubjectTrait
+ValueSupport
+VariableBoundEntropy
+VariablesCollection
+VariateForm
+VariationalMessage
+VoidActor
+VoidTeardown
+VoidTeardownLogic
+VonMises
+VonMisesFisher
+WalleniusNoncentralHypergeometric
+Weibull
+Wishart
+WishartDistributionsFamily
+ZeroMeanDiagNormal
+ZeroMeanDiagNormalCanon
+ZeroMeanFullNormal
+ZeroMeanFullNormalCanon
+ZeroMeanIsoNormal
+ZeroMeanIsoNormalCanon
+accumulated
+actor_extract_type
+actor_proxy!
+apply_pipeline_stage
+approximation_name
+approximation_short_name
+as_actor
+as_marginal
+as_message
+as_operator
+as_subject
+as_subscribable
+as_teardown
+as_variable
+async
+basemeasure
+buffer
+call_operator!
+call_operator_composition!
+canonform
+catch_error
+ccdf
+cdf
+censored
+cf
+cgf
+cholinv
+cholinv_logdet
+chollogdet
+cholsqrt
+circularkeep
+circvar
+clamplog
+collectLatest
+combineLatest
+combineLatestUpdates
+compile
+complete!
+completed
+component
+components
+componentwise_logpdf
+componentwise_pdf
+compute_logscale
+concat
+concat_map
+concat_map_to
+concentration
+connect
+connectable
+constrain_form
+constvar
+convert_paramfloattype
+convolve
+cor
+count
+cov
+cquantile
+create_actor
+create_model
+create_subject
+datavar
+debounce_time
+deep_eltype
+default_form_check_strategy
+default_if_empty
+default_prod_constraint
+default_prod_rule
+defer
+degree
+delay
+diageye
+dim
+dimension
+discontinue
+distribution_typewrapper
+dof
+dot
+dtanh
+entropy
+enumerate
+error!
+error_if
+error_if_empty
+error_if_not
+estimate
+exhaust_map
+expected_logdet
+factorisation
+failprob
+fastcholesky
+fastcholesky!
+faulted
+file
+filter
+filter_type
+find
+find_index
+first
+fisherinformation
+fit
+fit_mle
+from
+functional_dependencies
+functionalform
+fuse_supports
+generate
+getapproximation
+getattributes
+getbasemeasure
+getconditioner
+getconst
+getconstant
+getconstraints
+getdata
+getfisherinformation
+getgradlogpartition
+getlayers
+getlogpartition
+getlogscale
+getmapping
+getmarginal
+getmarginals
+getmemory
+getmeta
+getmodel
+getnaturalparameters
+getnode_ids
+getnodes
+getoptions
+getprediction
+getpredictions
+getrandom
+getsufficientstatistics
+getsupport
+getvalues
+getvardict
+getvariables
+ghcubature
+gradlogpartition
+gradlogpdf
+hasconstvar
+hasdatavar
+hasfinitesupport
+hasrandomvar
+huge
+ignore
+infer
+inference
+insupport
+interfaces
+interval
+invcov
+invlogccdf
+invlogcdf
+invscale
+is_clamped
+is_initial
+is_marginalisation
+is_moment_matching
+is_point_mass_form_constraint
+isbasemeasureconstant
+isbounded
+isconnected
+isdeterministic
+isequal_typeof
+isleptokurtic
+islowerbounded
+ismesokurtic
+isplatykurtic
+isprobvec
+isproper
+isstochastic
+isupperbounded
+iterable
+keep
+kldivergence
+kurtosis
+labeled
+lambda
+laplace
+last
+lazy
+limit_subscribers
+localmarginalnames
+localmarginals
+location
+location!
+logccdf
+logcdf
+logdetcov
+logdiffcdf
+logger
+loglikelihood
+logmvbeta
+logpartition
+logpdf
+logpdf!
+logpdf_optimized
+logpdf_sampling_optimized
+lowercase
+make
+make_form_constraint
+make_node
+map
+map_to
+marginalrule
+max
+mean
+mean_cov
+mean_invcov
+mean_precision
+mean_std
+mean_var
+meandir
+meanform
+meanlogx
+median
+merge_map
+merged
+metadata
+mgf
+min
+mirrorlog
+mode
+model_name
+modes
+moment
+multicast
+mvtrigamma
+name
+ncategories
+ncomponents
+network
+never
+next!
+noop
+nr_params
+nsamples
+ntrials
+of
+on_call!
+on_complete!
+on_error!
+on_next!
+on_subscribe!
+on_unsubscribe!
+operator_right
+override
+pairwise
+parallel
+paramfloattype
+params
+params!
+partype
+pdf
+pdf!
+pdfsquaredL2norm
+precision
+probs
+probval
+probvec
+prod
+prod!
+product_distribution
+promote_paramfloattype
+promote_samplefloattype
+promote_sampletype
+promote_variate_type
+proxy
+publish
+publish_behavior
+publish_recent
+publish_replay
+qqbuild
+quantile
+race
+rand
+rand!
+randomvar
+rate
+reduce
+ref_count
+release!
+rerun
+resolve_prod_strategy
+rule
+rxinference
+safe
+sample
+sample!
+samplefloattype
+sampler
+sampletype
+sampling_optimized
+scale
+scale!
+scan
+schedule_on
+scheduled
+score
+sdtype
+server
+set!
+setTimeout
+setmarginal!
+setmarginals!
+setmessage!
+setmessages!
+shape
+share
+share_recent
+share_replay
+skewness
+skip_complete
+skip_error
+skip_next
+skipindex
+softdot
+some
+source_proxy!
+span
+sqmahal
+sqmahal!
+srcubature
+start_with
+std
+stdlogx
+storage
+subscribable_extract_type
+subscribe!
+substitute
+succprob
+sufficientstatistics
+suffstats
+sum
+support
+switch_map
+switch_map_to
+sync
+take
+take_until
+tap
+tap_on_complete
+tap_on_subscribe
+tap_on_unsubscribe
+teardown!
+throwError
+timer
+tiny
+to_array
+truncated
+tuple_with_left
+tuple_with_right
+unsubscribe!
+update!
+uppercase
+vague
+value_support
+var
+variate_form
+varlogx
+void
+voidTeardown
+weightedmean
+weightedmean_cov
+weightedmean_invcov
+weightedmean_precision
+weightedmean_std
+weightedmean_var
+weights
+with_latest
+wsample
+wsample!
+xtlog
+zipped
diff --git a/v2.16.2/library/functional-forms/index.html b/v2.16.2/library/functional-forms/index.html new file mode 100644 index 000000000..8f83e9ab3 --- /dev/null +++ b/v2.16.2/library/functional-forms/index.html @@ -0,0 +1,26 @@ + +Built-in functional form constraints · RxInfer.jl
GitHub

Built-in Functional Forms

This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.

Custom functional forms

See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.

UnspecifiedFormConstraint

Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.

@constraints begin 
+    q(x) :: Nothing # This is the default setting
+end

PointMassFormConstraint

The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. 

@constraints begin 
+    q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object
+end
RxInfer.PointMassFormConstraint — Type
PointMassFormConstraint

One of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.

Keyword arguments

  • optimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer
  • starting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point
  • boundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries

Custom optimizer callback interface

# This is an example of the `custom_optimizer` interface
+function custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # should return argmin of the -logpdf(distribution)
+end

Custom starting point callback interface

# This is an example of the `custom_starting_point` interface
+function custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # built-in optimizer expects an array, even for a univariate distribution
+    return [ 0.0 ] 
+end

Custom boundaries callback interface

# This is an example of the `custom_boundaries` interface
+function custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)
+    # returns a tuple of `lower` and `upper` boundaries
+    return (-Inf, Inf)
+end

Traits

  • is_point_mass_form_constraint = true
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = PointMass (for use in @constraints macro)
source

SampleListFormConstraint

SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.

@constraints begin 
+    q(x) :: SampleList(1000)
+    # or 
+    q(y) :: SampleList(1000, LeftProposal())
+end
RxInfer.SampleListFormConstraint — Type
SampleListFormConstraint(rng, strategy, method)

One of the form constraint objects. Approximates DistProduct with a SampleList object.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = SampleList (for use in @constraints macro)
source
RxInfer.LeftProposal — Type

Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.

source
RxInfer.RightProposal — Type

Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.

source

FixedMarginalFormConstraint

Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.

@constraints function block_updates(x_posterior = nothing) 
+    # `nothing` returns the computed posterior marginal
+    q(x) :: Marginal(x_posterior)
+end
RxInfer.FixedMarginalFormConstraint — Type
FixedMarginalFormConstraint

One of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.

Traits

  • is_point_mass_form_constraint = false
  • default_form_check_strategy = FormConstraintCheckLast()
  • default_prod_constraint = GenericProd()
  • make_form_constraint = Marginal (for use in @constraints macro)
source

CompositeFormConstraint

It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:

form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()
@constraints begin 
+    q(x) :: SampleList(1000) :: PointMass()
+end
diff --git a/v2.16.2/library/model-specification/index.html b/v2.16.2/library/model-specification/index.html new file mode 100644 index 000000000..e841805c3 --- /dev/null +++ b/v2.16.2/library/model-specification/index.html @@ -0,0 +1,4 @@ + +Model specification · RxInfer.jl
GitHub

Model specification in RxInfer

RxInfer.@model — Macro
@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model description
+end

@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.

Supported alias in the model specification

  • a || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).
  • a && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • a -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).
  • ¬a and !a: alias for NOT(a) node (Unicode \neg, operator precedence ||, &&, -> and ! is the same as in Julia).
  • a + b + c: alias for (a + b) + c
  • a * b * c: alias for (a * b) * c
  • Normal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.
  • Normal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.
  • MvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • MvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.
  • Gamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.
  • Gamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.
source
RxInfer.ModelGenerator — Type
ModelGenerator

ModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.

See also: infer

source
RxInfer.create_model — Function
create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)

Creates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.

Returns a tuple of 2 values:

    1. an instance of FactorGraphModel
    1. return value from the @model macro function definition
source
RxInfer.ModelInferenceOptions — Type
ModelInferenceOptions(; kwargs...)

Creates model inference options object. The list of available options is present below.

Options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.
  • warn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.

Advanced options

  • pipeline: changes the default pipeline for each factor node in the graph
  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

See also: infer

source
diff --git a/v2.16.2/manuals/background/index.html b/v2.16.2/manuals/background/index.html new file mode 100644 index 000000000..d08c13d64 --- /dev/null +++ b/v2.16.2/manuals/background/index.html @@ -0,0 +1,2 @@ + +Background: variational inference · RxInfer.jl
GitHub
diff --git a/v2.16.2/manuals/comparison/index.html b/v2.16.2/manuals/comparison/index.html new file mode 100644 index 000000000..ee94668df --- /dev/null +++ b/v2.16.2/manuals/comparison/index.html @@ -0,0 +1,28 @@ + +RxInfer.jl vs. Others · RxInfer.jl
GitHub

Comparison to other packages

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.

DISCLAIMER:

  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, and we'll be more than willing to rectify.
  2. The comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.
ToolboxUniversalityEfficiencyExpressivenessDebugging & VisualizationModularityInference EngineLanguageCommunity & Ecosystem
RxInfer.jl~✓✓~✗Message-passingJulia✗
ForneyLab.jl✗~✗~✗Message-passingJulia✗
Infer.net~✓✗✓✗Message-passingC#✗
PGMax✗✓✗✓✗Message-passingPython✗
Turing.jl✓✗✓~✗SamplingJulia✓
PyMC✓✗✓✓✗SamplingPython✓
NumPyro✓✓~✓✗SamplingPython✓
TensorFlow Probability✓✗~✓✗SamplingPython✓
Stan✓✗✓✓✗SamplingStan✓

(Date of creation: 20/10/2023)

Legend

  • ✓ : Full capability or feature is present.
  • ~ : Partial capability or feature is present.
  • ✗ : No capability or feature.

Notes:

  • Universality: Denotes the capability to depict a vast array of probabilistic models.
  • Efficiency: Highlights computational competence. A "–" in this context suggests perceived slowness.
  • Expressiveness: Assesses the ability to concisely formulate intricate probabilistic models.
  • Debugging & Visualization: Evaluates the suite of tools for model debugging and visualization.
  • Modularity: Reflects the potential to create models by integrating smaller models.
  • Inference Engines: Pinpoints the primary inference strategy employed by the toolbox.
  • Language: Identifies the programming language integral to the toolbox.
  • Community & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.

RxInfer.jl breakdown

  • Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.

  • Efficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.

  • Modularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:

@model function inner_inner(τ, y)
+    y ~ Normal(τ[1], τ[2])
+end
+
+@model function inner(θ, α)
+    β ~ Normal(0, 1)
+    α ~ Gamma(β, 1)
+    α ~ inner_inner(τ = θ)
+end
+
+@model function outer()
+    local w
+    for i = 1:5
+        w[i] ~ inner(θ = Gamma(1, 1))
+    end
+    y ~ inner(θ = w[2:3])
+end
  • Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(0.0, 1.0)\\ + w & \sim \mathrm{InverseGamma}(1.0, 1.0)\\ + y & \sim \mathrm{Normal}(x, w) +\end{aligned}\]

The model then is expressed in RxInfer.jl as follows:

using RxInfer
+
+@model function example_model()
+    x ~ Normal(mean=0.0, var=1.0)
+    w ~ InverseGamma(α = 1, θ = 1)
+    y ~ Normal(mean = x, var = w)
+end
  • Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.
diff --git a/v2.16.2/manuals/constraints-specification/index.html b/v2.16.2/manuals/constraints-specification/index.html new file mode 100644 index 000000000..47cdf8980 --- /dev/null +++ b/v2.16.2/manuals/constraints-specification/index.html @@ -0,0 +1,111 @@ + +Constraints specification · RxInfer.jl
GitHub

Constraints Specification

RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.

using RxInfer

General syntax

@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:


+# `functional` style
+@constraints function create_my_constraints(arg1, arg2)
+    ...
+end
+
+# `block` style
+myconstraints = @constraints begin 
+    ...
+end
+

In the first case it returns a function that return constraints upon calling, e.g. 

@constraints function make_constraints(mean_field)
+    q(x) :: PointMass
+
+    if mean_field
+        q(x, y) = q(x)q(y)
+    end
+end
+
+myconstraints = make_constraints(true)
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

and in the second case it evaluates automatically and returns constraints object directly.

myconstraints = @constraints begin
+    q(x) :: PointMass
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

Options specification

@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

myconstraints = @constraints [ warn = false ] begin 
+   ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/constraints specification

Marginal and messages form constraints

To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)

The following constraint:

@constraints begin
+    q(x) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:

\[\mathrm{approximate~} q(x) = \frac{\overrightarrow{\mu}(x)\overleftarrow{\mu}(x)}{\int \overrightarrow{\mu}(x)\overleftarrow{\mu}(x) \mathrm{d}x}\mathrm{~as~PointMass}\]

Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):

@constraints begin
+    q(x) :: PointMass
+    μ(x) :: SampleList(1000)
+    # it is possible to assign different form constraints on the same variable
+    # both for the marginal and for the messages
+end
Constraints:
+  marginals form:
+    q(x) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+    μ(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) [ prod_constraint = GenericProd() ]
+  factorisation:
+Options:
+  warn = true
+

@constraints macro understands "stacked" form constraints. For example the following form constraint

@constraints begin
+    q(x) :: SampleList(1000) :: PointMass
+end
Constraints:
+  marginals form:
+    q(x) :: SampleListFormConstraint(Random._GLOBAL_RNG(), AutoProposal(), BayesBase.BootstrapImportanceSampling()) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]
+  messages form:
+  factorisation:
+Options:
+  warn = true
+

indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass.

Note

Not all combinations of "stacked" form constraints are compatible between each other.

You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.

Factorisation constraints on posterior distribution q()

@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:

For example:

@constraints begin
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.

@constraints begin
+    q(x) = q(x[begin])..q(x[end])
+    q(x, y) = q(x)q(y)
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x) = q(x[(begin)..(end)])
+    q(x, y) = q(x)q(y)
+Options:
+  warn = true
+

These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables $x_i$.

Note

@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])

It is possible to write more complex factorisation constraints, for example:

@constraints begin
+    q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])
+end
Constraints:
+  marginals form:
+  messages form:
+  factorisation:
+    q(x, y) = q(x[(begin)..(end)], y[(begin)..(end)])
+Options:
+  warn = true
+

specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is

@constraints function make_constraints(k)
+    q(x) = q(x[begin:k])q(x[k+1:end])
+end
make_constraints (generic function with 1 method)

In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end].

To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+constraints = @constraints begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); constraints = constraints)

Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument.

diff --git a/v2.16.2/manuals/custom-node/c457da72.svg b/v2.16.2/manuals/custom-node/c457da72.svg new file mode 100644 index 000000000..e11f4e95d --- /dev/null +++ b/v2.16.2/manuals/custom-node/c457da72.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/custom-node/index.html b/v2.16.2/manuals/custom-node/index.html new file mode 100644 index 000000000..156d33a4b --- /dev/null +++ b/v2.16.2/manuals/custom-node/index.html @@ -0,0 +1,86 @@ + +Defining a custom node and rules · RxInfer.jl
GitHub

Creating your own custom nodes

Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.

To create a custom node in RxInfer, 4 steps are required:

  1. Create your custom node in RxInfer using the @node macro.
  2. Define the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.
  3. Specify computations for marginal distributions of the relevant variables with the @marginalrule macro.
  4. Implement the computation of the Free Energy in a node with the @average_energy macro.

Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!

Problem statement

Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin $K=20$ times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment $x_k\in\{0,1\}$ using the Bernoulli distribution as

\[p(x_k \mid \pi) = \mathrm{Ber}(x_k \mid \pi) = \pi^{x_k} (1-\pi)^{1-x_k},\]

where $\pi \in[0,1]$ denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of $\pi$ which she models using the Beta distribution as

\[p(\pi) = \mathrm{Beta}(\pi \mid 4, 8).\]

With this prior belief, the total probabilistic model that she has for this experiment is given by

\[p(x_{1:K}, \pi) = p(\pi) \prod_{k=1}^K p(x_k \mid \pi).\]

Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of $\pi$, $p(\pi \mid x_{1:K})$, denoting how $\pi$ is distributed after we have seen the data.

Step 1: Creating the custom node

Note

In this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.

First things first, let's import RxInfer:

using RxInfer

In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:

  1. The name of the node. (::Type)
  2. Whether the node is Deterministic or Stochastic.
  3. The interfaces of the node and any potential aliases. (::Vector)

For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as

# struct for Bernoulli distribution with success probability π
+struct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution
+    π :: T
+    new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError("π must be between 0 and 1"))
+end
+
+# for simplicity, let's also specify the mean of the distribution
+Distributions.mean(d::MyBernoulli) = d.π

In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.

Note

You can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)

For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of $\pi$, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.

The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.

Concluding, we can create the MyBernoulli factor node as

@node MyBernoulli Stochastic [out, (π, aliases = [p])]

Cool! Step 1 is done, we have created a custom node.

Step 2: Defining rules for our node

In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as $p(\pi\mid x_{1:K})$, we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.

Sum-product message passing update rules

In sum-product message passing we compute outgoing messages to our node as

\[\vec{\mu}(x) \propto \int \mathrm{Ber}(x\mid \pi) \vec{\mu}(\pi) \mathrm{d}x\]

\[\overleftarrow{\mu}(\pi) \propto \sum_{x \in \{0,1\}} \mathrm{Ber}(x\mid \pi) \overleftarrow{\mu}(x)\]

This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.

For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain $\pi = \frac{\alpha}{\alpha + \beta}$, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as

@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))

Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for "the incoming message on interface π". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.

The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):

@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))

Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:

\[\overleftarrow{\mu}(π) \propto \mathrm{Beta}(1 + x, 2 - x)\]

Which gives us the following update rule:

@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin
+    p = mean(m_out)
+    Beta(one(p) + p, 2one(p) - p)
+end

Variational message passing update rules

We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as

\[\vec{\nu}(x) \propto \exp \int q(\pi) \ln \mathrm{Ber}(x\mid \pi) \mathrm{d}x\]

\[\overleftarrow{\nu}(\pi) \propto \exp \sum_{x \in \{0,1\}} q(x) \ln \mathrm{Ber}(x\mid \pi)\]

These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.

#rules towards out
+@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))
+
+@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin
+    rho_1 = mean(log, q_π)          # E[ln(x)]
+    rho_2 = mean(mirrorlog, q_π)    # E[log(1-x)]
+    m = max(rho_1, rho_2)
+    tmp = exp(rho_1 - m)
+    p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))
+    return Bernoulli(p)
+end
+
+#rules towards π
+@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin
+    p = mean(q_out)
+    return Beta(one(p) + p, 2one(p) - p)
+end
Node

Typically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.

In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.

Step 3: Defining joint marginals for our node

The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by

\[F[q,f] = - \sum_{a\in\mathcal{V}} \mathrm{H}[q_a(s_a)] - \sum_{a\in\mathcal{V}}\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)] + \sum_{i\in\mathcal{E}}\mathrm{H}[q_i(s_i)]\]

Here we call $q_a(s_a)$ the joint marginals around a node and $-\mathrm{E}_{q_a(s_a)}[\ln f_a(s_a)]$ we term the average energy.

In order to be able to compute the Bethe free energy, we need to first describe how to compute $q_a(s_a)$, defined in our case as

\[q(x_k, \pi) = \vec{\mu}(\pi) \overleftarrow{\mu}(x_k) \mathrm{Ber}(x_k \mid \pi)\]

To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:

@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin
+    r = mean(m_out)
+    p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)
+    return (out = m_out, p = p)
+end

In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as $q(x_k, \pi) = q(x_k)q(\pi)$. These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing $q(\pi)$ we need to compute the product $\vec{\mu}(\pi)\overleftarrow{\mu}(\pi)$. We already know how $\overleftarrow{\mu}(\pi)$ looks like from the previous step, so we can just use the prod function.

Step 4: Defining the average energy for our node

To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as $-\mathrm{E}_{q(x_k, \pi)}[\ln p(x_k \mid \pi)]$, however, because we know that we observe $x_k$ and therefore $q(x_k, \pi)$ factorizes, we can instead compute $\begin{aligned} -\mathrm{E}_{q(x_k)q(\pi)}[\ln p(x_k \mid \pi)] &= -\mathrm{E}_{q(x_k)q(\pi)} [\ln (\pi^{x_k} (1-\pi)^{1 - x_k})] \\ +&= -\mathrm{E}_{q(x_k)q(\pi)} [x_k \ln(\pi) + (1-x_k) \ln(1-\pi)] \\ +&= -\mathrm{E}_{q(x_k)}[x_k] \mathrm{E}_{q(\pi)} [\ln(\pi)] - (1-\mathrm{E}_{q(x_k)}[x_k]) \mathrm{E}_{q(\pi)}[\ln(1-\pi)] \end{aligned}$

Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to $\mathrm{E}_{q(x)}[1-\log{x}]$.

@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)

In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....

Using our node in a model

With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:

using Random
+
+rng = MersenneTwister(42)
+n = 500
+π_real = 0.75
+distribution = Bernoulli(π_real)
+
+dataset = float.(rand(rng, distribution, n))

Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:

@model function coin_model_mybernoulli(n)
+
+    # `datavar` creates data 'inputs' in our model
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    π ~ Beta(4.0, 8.0)
+
+    # We assume that outcome of each coin flip is governed by the MyBernoulli distribution
+    for i in 1:n
+        y[i] ~ MyBernoulli(π)
+    end
+
+end

Finally, we can run inference with this model and the generated dataset:

result_mybernoulli = infer(
+    model = coin_model_mybernoulli(length(dataset)),
+    data  = (y = dataset, ),
+)
Inference results:
+  Posteriors       | available for (π)
+

We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.

using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p = plot(title = "Inference results")
+
+plot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label="p(π|x)", c=3)
+vline!([π_real], label="Real π")
Example block output

As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.

@model function coin_model(n)
+
+    y = datavar(Float64, n)
+    p ~ Beta(4.0, 8.0)
+
+    for i in 1:n
+        y[i] ~ Bernoulli(p)
+    end
+
+end
+
+result_bernoulli = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, ),
+)
+
+if !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])
+    error("Results are not identical")
+else
+    println("Results are identical 🎉🎉🎉")
+end
Results are identical 🎉🎉🎉

Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.

diff --git a/v2.16.2/manuals/debugging/baca03fb.svg b/v2.16.2/manuals/debugging/baca03fb.svg new file mode 100644 index 000000000..554f40cf8 --- /dev/null +++ b/v2.16.2/manuals/debugging/baca03fb.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/debugging/cdd8bdc5.svg b/v2.16.2/manuals/debugging/cdd8bdc5.svg new file mode 100644 index 000000000..ebc6cb4dd --- /dev/null +++ b/v2.16.2/manuals/debugging/cdd8bdc5.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/debugging/index.html b/v2.16.2/manuals/debugging/index.html new file mode 100644 index 000000000..a9e513aa7 --- /dev/null +++ b/v2.16.2/manuals/debugging/index.html @@ -0,0 +1,60 @@ + +Debugging · RxInfer.jl
GitHub

Debugging

Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. 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

We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a "Memory Addon". Below is an example explaining how you can extract this history and use it to fix a bug.

Consider the coin toss example from earlier in the documentation. We model the binary outcome $x$ (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the $\theta$ parameter, with a known shape 𝑎 and rate 𝑏 parameter.

\[x_i \sim \mathrm{Bernoulli}(\theta)\]

\[\theta \sim \mathrm{Beta}(a, b)\]

where $x_i \in {0, 1}$ are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:

using RxInfer, Random, Plots
+
+n = 4
+θ_real = 0.3
+dataset = convert.(Int64, rand(Bernoulli(θ_real), n))
+
+@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, huge)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+

The model will run without errors. But when we plot the posterior distribution for $\theta$, something's wrong. The posterior seems to be a flat distribution:

rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+    addons = (AddonMemory(),)
+)
Inference results:
+  Posteriors       | available for (θ)
+

Now we have access to the messages that led to the marginal posterior:

Addons_messages

The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:

\[\underbrace{\overrightarrow{\mu}_{θ}(θ)}_{\substack{ \text{outgoing}\\ \text{message}}} = \sum_{x_1,\ldots,x_n} \underbrace{\overrightarrow{\mu}_{X_1}(x_1)\cdots \overrightarrow{\mu}_{X_n}(x_n)}_{\substack{\text{incoming} \\ \text{messages}}} \cdot \underbrace{f(θ,x_1,\ldots,x_n)}_{\substack{\text{node}\\ \text{function}}}\]

Graph

Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of $\theta$ we used in the code block above. So why does the posterior have this rate parameter?

All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.

@model function coin_model(n)
+
+    # Observations
+    x = datavar(Int64, n)
+
+    # Prior distribution
+    θ ~ Beta(4, 100)
+
+    # Likelihood for each input
+    for i in 1:n
+        x[i] ~ Bernoulli(θ)
+    end
+
+end
+
+result = infer(
+    model = coin_model(length(dataset)),
+    data  = (x = dataset, ),
+);
Inference results:
+  Posteriors       | available for (θ)
+
rθ = range(0, 1, length = 1000)
+
+plot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label="Infered posterior")
+vline!([θ_real], label="Real θ", title = "Inference results")
Example block output

Now the posterior is visible in the plot.

diff --git a/v2.16.2/manuals/delta-node/index.html b/v2.16.2/manuals/delta-node/index.html new file mode 100644 index 000000000..c99b7da7e --- /dev/null +++ b/v2.16.2/manuals/delta-node/index.html @@ -0,0 +1,59 @@ + +Delta node · RxInfer.jl
GitHub

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.

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:

  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.
  3. Stacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.

The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:

MethodsGaussian NodesExponential Family NodesStacking Delta Nodes
Linearization✓✗✓
Unscented✓✗✓
CVI✓✓✗

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.

For clarity, consider the following example:

using RxInfer
+
+@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=0.0, var=1.0)
+    y ~ tanh(x)
+    z ~ Normal(mean=y, var=1.0)
+end

To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:

delta_meta = @meta begin
+    tanh() -> Linearization()
+end
Meta specification:
+  tanh() -> Linearization()
+Options:
+  warn = true

or

delta_meta = @meta begin
+    tanh() -> Unscented()
+end
Meta specification:
+  tanh() -> Unscented{Float64, Float64, Float64, Nothing}(0.001, 2.0, 0.0, nothing)
+Options:
+  warn = true

For a deeper understanding of the Unscented method and its parameters, consult the docstrings.

Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:

delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)
+end
Meta specification:
+  tanh() -> DeltaMeta{Linearization, typeof(atanh)}(Linearization(), atanh)
+Options:
+  warn = true

To execute the inference procedure:

infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))
Inference results:
+  Posteriors       | available for (y, x)
+

This methodology is consistent even when the delta node is associated with multiple nodes. For instance:

f(x, g) = x*tanh(g)
f (generic function with 1 method)
@model function delta_node_example()
+    z = datavar(Float64)
+    x ~ Normal(mean=1.0, var=1.0)
+    g ~ Normal(mean=1.0, var=1.0)
+    y ~ f(x, g)
+    z ~ Normal(mean=y, var=0.1)
+end

The corresponding meta specification is:

delta_meta = @meta begin
+    f() -> DeltaMeta(method = Linearization())
+end
Meta specification:
+  f() -> DeltaMeta{Linearization, Nothing}(Linearization(), nothing)
+Options:
+  warn = true

or simply

delta_meta = @meta begin
+    f() -> Linearization()
+end
Meta specification:
+  f() -> Linearization()
+Options:
+  warn = true

If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:

delta_meta = @meta begin 
+    f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))
+end

Exponential Family Case

When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:

using RxInfer
+
+@model function delta_node_example1()
+    z = datavar(Float64)
+    x ~ Gamma(shape=1.0, rate=1.0)
+    y ~ tanh(x)
+    z ~ Bernoulli(y)
+end

The corresponding meta specification can be represented as:

using StableRNGs
+using Optimisers
+
+delta_meta = @meta begin
+    tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))
+end
Meta specification:
+  tanh() -> DeltaMeta{ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}, Nothing}(ProdCVI{StableRNGs.LehmerRNG, Optimisers.Descent{Float64}, ForwardDiffGrad{0}, true}(StableRNGs.LehmerRNG(state=0x00000000000000000000000000000055), 100, 100, Optimisers.Descent{Float64}(0.01), ForwardDiffGrad{0}(), 1, Val{true}(), true), nothing)
+Options:
+  warn = true

Consult the ProdCVI docstrings for a detailed explanation of these parameters.

diff --git a/v2.16.2/manuals/getting-started/3f1e2d6e.svg b/v2.16.2/manuals/getting-started/3f1e2d6e.svg new file mode 100644 index 000000000..6eed3f155 --- /dev/null +++ b/v2.16.2/manuals/getting-started/3f1e2d6e.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/getting-started/77673a55.svg b/v2.16.2/manuals/getting-started/77673a55.svg new file mode 100644 index 000000000..63c33b9c4 --- /dev/null +++ b/v2.16.2/manuals/getting-started/77673a55.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/getting-started/index.html b/v2.16.2/manuals/getting-started/index.html new file mode 100644 index 000000000..54c18a22c --- /dev/null +++ b/v2.16.2/manuals/getting-started/index.html @@ -0,0 +1,91 @@ + +Getting started · RxInfer.jl
GitHub

Getting started

RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.

RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.

This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.

Installation

Install RxInfer through the Julia package manager:

] add RxInfer

Importing RxInfer

To add RxInfer package (and all associated packages) into a running Julia session simply run:

using RxInfer

Read more about about using in the Using methods from RxInfer section of the documentation.

Example: Inferring the bias of a coin

The RxInfer approach to solving inference problems consists of three phases:

  1. Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.
  2. Inference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.
  3. Inference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.

Coin flip simulation

Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).

First let's setup our environment by importing all needed packages:

using RxInfer, Distributions, Random

Next, let's define our dataset:

rng = MersenneTwister(42)
+n = 10
+p = 0.75
+distribution = Bernoulli(p)
+
+dataset = float.(rand(rng, Bernoulli(p), n))
10-element Vector{Float64}:
+ 1.0
+ 1.0
+ 1.0
+ 1.0
+ 0.0
+ 0.0
+ 1.0
+ 1.0
+ 0.0
+ 1.0

Model specification

In 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.

Likelihood

We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.

\[y_i \sim \mathrm{Bernoulli}(\theta),\]

where $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]$.

Prior

We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.

\[\theta \sim Beta(a, b),\]

where $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.

Joint probability

The joint probability is given by the multiplication of the likelihood and the prior, i.e.

\[P(y_{1:N}, θ) = P(θ) \prod_{i=1}^N P(y_i | θ).\]

Now let's see how to specify this model using GraphPPL's package syntax.

# GraphPPL.jl export `@model` macro for model specification
+# It accepts a regular Julia function and builds an FFG under the hood
+@model function coin_model(n)
+
+    # `datavar` creates data 'inputs' in our model
+    # We will pass data later on to these inputs
+    # In this example we create a sequence of inputs that accepts Float64
+    y = datavar(Float64, n)
+
+    # We endow θ parameter of our model with some prior
+    θ ~ Beta(2.0, 7.0)
+    # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:
+    # θ ~ Uniform(0.0, 1.0)
+
+    # We assume that outcome of each coin flip is governed by the Bernoulli distribution
+    for i in 1:n
+        y[i] ~ Bernoulli(θ)
+    end
+
+    # We return references to our data inputs and θ parameter
+    # We will use these references later on during inference step
+    return y, θ
+end

As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create "clamped" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Inference specification

Automatic inference specification

Once 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 inference function that supports static datasets.

result = infer(
+    model = coin_model(length(dataset)),
+    data  = (y = dataset, )
+)
Inference results:
+  Posteriors       | available for (θ)
+
θestimated = result.posteriors[:θ]
Beta{Float64}(α=9.0, β=10.0)
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803

Read more information about the inference function in the Static Inference documentation section.

Manual inference specification

There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:

  1. Return variables of interests from model specification
  2. Subscribe on variables of interests posterior marginal updates
  3. Pass data to the model
  4. Unsubscribe

Here is an example of inference procedure:

function custom_inference(data)
+    n = length(data)
+
+    # `coin_model` function from `@model` macro returns a reference to the model generator object
+    # we need to use the `create_model` function to get actual model object
+    model, (y, θ) = create_model(coin_model(n))
+
+    # Reference for future posterior marginal
+    mθ = nothing
+
+    # `getmarginal` function returns an observable of future posterior marginal updates
+    # We use `Rocket.jl` API to subscribe on this observable
+    # As soon as posterior marginal update is available we just save it in `mθ`
+    subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)
+
+    # `update!` function passes data to our data inputs
+    update!(y, data)
+
+    # It is always a good practice to unsubscribe and to
+    # free computer resources held by the subscription
+    unsubscribe!(subscription)
+
+    # Here we return our resulting posterior marginal
+    return mθ
+end
custom_inference (generic function with 1 method)

Inference execution

Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.

θestimated = custom_inference(dataset)
Marginal(Beta{Float64}(α=9.0, β=10.0))
println("mean: ", mean(θestimated))
+println("std:  ", std(θestimated))
mean: 0.47368421052631576
+std:  0.11164843913471803
using Plots
+
+rθ = range(0, 1, length = 1000)
+
+p1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title="Prior", fillalpha=0.3, fillrange = 0, label="P(θ)", c=1,)
+p2 = plot(rθ, (x) -> pdf(θestimated, x), title="Posterior", fillalpha=0.3, fillrange = 0, label="P(θ|y)", c=3)
+
+plot(p1, p2, layout = @layout([ a; b ]))
Example block output

In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:

dataset_100   = float.(rand(rng, Bernoulli(p), 100))
+dataset_1000  = float.(rand(rng, Bernoulli(p), 1000))
+dataset_10000 = float.(rand(rng, Bernoulli(p), 10000))
θestimated_100   = custom_inference(dataset_100)
+θestimated_1000  = custom_inference(dataset_1000)
+θestimated_10000 = custom_inference(dataset_10000)
p3 = plot(title = "Posterior", legend = :topleft)
+
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_100)", c = 4)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_1000)", c = 5)
+p3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = "P(θ|y_10000)", c = 6)
+
+plot(p1, p3, layout = @layout([ a; b ]))
Example block output

With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.

println("mean: ", mean(θestimated_10000))
+println("std:  ", std(θestimated_10000))
mean: 0.7529223698671196
+std:  0.004310967761308469

Where to go next?

There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.

diff --git a/v2.16.2/manuals/inference/infer/index.html b/v2.16.2/manuals/inference/infer/index.html new file mode 100644 index 000000000..f75fbb817 --- /dev/null +++ b/v2.16.2/manuals/inference/infer/index.html @@ -0,0 +1,120 @@ + +Static vs Streamline inference · RxInfer.jl
GitHub

Automatic Inference Specification

RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors.

It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.

For details on manual inference specification, see the Manual Inference section.

RxInfer.infer — Function
infer(
+    model; 
+    data = nothing,
+    datastream = nothing,
+    autoupdates = nothing,
+    initmarginals = nothing,
+    initmessages = nothing,
+    constraints = nothing,
+    meta = nothing,
+    options = nothing,
+    returnvars = nothing, 
+    predictvars = nothing, 
+    historyvars = nothing,
+    keephistory = nothing,
+    iterations = nothing,
+    free_energy = false,
+    free_energy_diagnostics = BetheFreeEnergyDefaultChecks,
+    showprogress = false,
+    callbacks = nothing,
+    addons = nothing,
+    postprocess = DefaultPostprocess(),
+    warn = true,
+    events = nothing,
+    uselock = false,
+    autostart = true,
+    catch_exception = false
+)

This function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.

Arguments

For more information about some of the arguments, please check below.

  • model: specifies a model generator, required
  • data: NamedTuple or Dict with data, required (or datastream or predictvars)
  • datastream: A stream of NamedTuple with data, required (or data)
  • autoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates
  • initmarginals = nothing: NamedTuple or Dict with initial marginals, optional
  • initmessages = nothing: NamedTuple or Dict with initial messages, optional
  • constraints = nothing: constraints specification object, optional, see @constraints
  • meta = nothing: meta specification object, optional, may be required for some models, see @meta
  • options = nothing: model creation options, optional, see ModelInferenceOptions
  • returnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information
  • predictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)
  • historyvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)
  • keephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)
  • iterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information
  • free_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl
  • free_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.
  • showprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)
  • catch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)
  • callbacks = nothing: inference cycle callbacks, optional, see below for more info
  • addons = nothing: inject and send extra computation information along messages, see below for more info
  • postprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info
  • events = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)
  • uselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)
  • autostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)
  • warn = true: enables/disables warnings

Note on NamedTuples

When passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.

The model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:

@model function coin_toss(some_argument, some_keyword_argument = 3)
+    ...
+end
+
+result = infer(
+    model = coin_toss(some_argument; some_keyword_argument = 3)
+)

Note: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.

  • data

Either data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.

Note: The behavior of the data keyword argument depends on the inference setting (batch or streamline).

The data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.

  • streamline setting

All entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.

  • datastream

The datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.

Note: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.

For specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as

infer(...
+    initmarginals = (
+        # initialize the marginal distribution of x as a vague Normal distribution
+        # if x is a vector, then it simply uses the same value for all elements
+        # However, it is also possible to provide a vector of distributions to set each element individually 
+        x = vague(NormalMeanPrecision),  
+    ),
+)
+
+This argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.
+
+- ### `initmessages`
+
+For specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as

julia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )

  • options

  • limit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.

  • pipeline: changes the default pipeline for each factor node in the graph

  • global_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler

  • returnvars

returnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.

Batch inference:

  • Accepts a NamedTuple or Dict of return variable specifications.
  • Two specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).
  • When iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).
  • Use iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.

Example:

result = infer(
+    ...,
+    returnvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    )
+)

Shortcut for setting the same option for all variables:

result = infer(
+    ...,
+    returnvars = KeepLast()  # or KeepEach()
+)

Streamline inference:

  • For each symbol in returnvars, infer creates an observable stream of posterior updates.
  • Agents can subscribe to these updates using the Rocket.jl package.

Example:

engine = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    returnvars = (:x, :τ),
+    autostart  = false
+)
  • predictvars

predictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.

Similar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    predictvars = (
+        o = KeepLast(),
+        τ = KeepEach()
+    )
+)

Note: The predictvars argument is exclusive for batch setting.

  • historyvars

historyvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.

historyvars accepts a NamedTuple or Dict or return var specification. There are two specifications:

  • KeepLast: saves the last update for a variable, ignoring any intermediate results during iterations
  • KeepEach: saves all updates for a variable for all iterations

Example: 

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = (
+        x = KeepLast(),
+        τ = KeepEach()
+    ),
+    keephistory = 10
+)

It is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.

Example:

result = infer(
+    ...,
+    autoupdates = my_autoupdates,
+    historyvars = KeepLast(),
+    keephistory = 10
+)
  • keep_history

Specifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.

  • iterations

Specifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration.

  • free_energy

Streamline inference:

Specifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.

  • When free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.
    • engine.free_energy_history: Averaged BFE history over VMP iterations.
    • engine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.
    • engine.free_energy_raw_history: Raw BFE history.

Batch inference:

Specifies if the infer function should return Bethe Free Energy (BFE) values.

  • Optionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.

  • free_energy_diagnostics

This settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.

  • catch_exception

The catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.

  • callbacks

The inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.

result = infer(
+    ...,
+    callbacks = (
+        on_marginal_update = (model, name, update) -> println("$(name) has been updated: $(update)"),
+        after_inference    = (args...) -> println("Inference has been completed")
+    )
+)

The callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:

  • on_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)
  • before_model_creation: args: ()
  • after_model_creation: args: (model::FactorGraphModel, returnval)
  • before_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • before_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)
  • after_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)
  • after_inference: args: (model::FactorGraphModel) (exlusive for batch inference)
  • before_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)
  • after_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)

before_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.

  • addons

The addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.

  • postprocess

The postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.

source
RxInfer.InferenceResult — Type
InferenceResult

This structure is used as a return value from the infer function.

Public Fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.
  • free_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.
  • error: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.

See also: infer

source
RxInfer.start — Function
start(engine::RxInferenceEngine)

Starts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.stop

source
RxInfer.stop — Function
stop(engine::RxInferenceEngine)

Stops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.

See also: RxInfer.start

source
RxInfer.@autoupdates — Macro
@autoupdates

Creates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification.

Each line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.

For example:

@autoupdates begin 
+    x = f(q(z))
+end

This structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically.

As an example consider the following model and auto-update specification:

@model function kalman_filter()
+    x_current_mean = datavar(Float64)
+    x_current_var  = datavar(Float64)
+
+    x_current ~ Normal(mean = x_current_mean, var = x_current_var)
+
+    x_next ~ Normal(mean = x_current, var = 1.0)
+
+    y = datavar(Float64)
+    y ~ Normal(mean = x_next, var = 1.0)
+end

This model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:

autoupdates = @autoupdates begin
+    x_current_mean, x_current_var = mean_cov(q(x_next))
+end

This structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.

See also: infer

source
RxInfer.RxInferenceEngine — Type
RxInferenceEngine

The return value of the rxinference function.

Public fields

  • posteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.
  • free_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.
  • history: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.
  • free_energy_history: (optional) Free energy history, average over variational iterations
  • free_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)
  • free_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)
  • events: (optional) A stream of events send by the inference engine. See the events argument for the infer.
  • model: FactorGraphModel object reference.
  • returnval: Return value from executed @model.

Use the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.

See also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop

source
RxInfer.RxInferenceEvent — Type
RxInferenceEvent{T, D}

The RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.

The events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:

using Rocket
+
+struct MyEventListener <: Rocket.Actor{RxInferenceEvent}
+    # ... extra fields
+end
+
+function Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })
+    model, iteration = event
+    println("Iteration $(iteration) has been finished.")
+end
+
+function Rocket.on_error!(listener::MyEventListener, err)
+    # ...
+end
+
+function Rocket.on_complete!(listener::MyEventListener)
+    # ...
+end
+

and later on:

engine = infer(events = Val((:after_iteration, )), ...)
+
+subscription = subscribe!(engine.events, MyEventListener(...))

See also: infer, RxInferenceEngine

source
diff --git a/v2.16.2/manuals/inference/manual/613ac8bf.svg b/v2.16.2/manuals/inference/manual/613ac8bf.svg new file mode 100644 index 000000000..f1e899717 --- /dev/null +++ b/v2.16.2/manuals/inference/manual/613ac8bf.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/inference/manual/9a17de9d.svg b/v2.16.2/manuals/inference/manual/9a17de9d.svg new file mode 100644 index 000000000..d3b0be2a0 --- /dev/null +++ b/v2.16.2/manuals/inference/manual/9a17de9d.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/inference/manual/9a985585.svg b/v2.16.2/manuals/inference/manual/9a985585.svg new file mode 100644 index 000000000..d4ecc0bfe --- /dev/null +++ b/v2.16.2/manuals/inference/manual/9a985585.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/inference/manual/index.html b/v2.16.2/manuals/inference/manual/index.html new file mode 100644 index 000000000..901f9e780 --- /dev/null +++ b/v2.16.2/manuals/inference/manual/index.html @@ -0,0 +1,103 @@ + +Manual inference specification · RxInfer.jl
GitHub

Manual inference

For advanced use cases it is advised to use manual inference specification.

Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:

  1. Create a model with @model macro and get a references to random variables and data inputs
  2. Subscribe to random variable posterior marginal updates
  3. Subscribe to Bethe Free Energy updates (optional)
  4. Feed model with observations
  5. Unsubscribe from posterior marginal updates (optional)

It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.

Model creation

During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.

using RxInfer, Distributions, Random
+
+@model function my_model()
+    m2 ~ NormalMeanVariance(0.0, 1.0)
+    m1 ~ NormalMeanVariance(m2, 1.0)
+
+    y = datavar(Float64)
+    y ~ NormalMeanVariance(m1, 1.0)
+
+    # Return variables of interests, optional
+    return m1, y
+end

And later on we may create our model with the create_model function and obtain references for variables of interests:

model, (m1, y) = create_model(my_model())

Alternatively, it is possible to query any variable using squared brackets on model object:

model[:m1] # m1
+model[:y]  # y

@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.

Posterior marginal updates

The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.

We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:

m1_posterior_updates = getmarginal(m1)

After that we can subscribe on new updates and perform some actions based on new values:

m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin
+    println("New posterior for m1: ", new_posterior)
+end)

Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.

@model function my_model()
+    ...
+    m_n = randomvar(n)
+    ...
+    return m_n, ...
+end
+
+model, (m_n, ...) = create_model(my_model())
+
+m_n_updates = getmarginals(m_n)

Feeding observations

By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.

To feed an observation for a specific data input we use update! function:

update!(y, 0.0)
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:

update!(y, 0.0) # Observation didn't change, should result in the same posterior
New posterior for m1: Marginal(NormalWeightedMeanPrecision{Float64}(xi=0.0, w=1.5))

If y is an array of data inputs it is possible to pass an array of observation to update! function:

for i in 1:length(data)
+    update!(y[i], data[i])
+end
+# is an equivalent of
+update!(y, data)

Variational Message Passing

Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.

using RxInfer, Distributions, Random
real_mean      = -4.0
+real_precision = 0.2
+rng            = MersenneTwister(1234)
+
+n    = 100
+data = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)
@model function normal_estimation(n)
+    m ~ NormalMeanVariance(0.0, 10.0)
+    w ~ Gamma(0.1, 10.0)
+
+    y = datavar(Float64, n)
+
+    for i in 1:n
+        y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }
+    end
+
+    return m, w, y
+end

We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:

model, (m, w, y) = create_model(normal_estimation(n))
+
+# We use vague initial marginals
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))

To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:

m_marginals = []
+w_marginals = []
+
+subscriptions = subscribe!([
+    (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),
+    (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),
+])
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(subscriptions)

As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.

using Plots
+
+p1    = plot(title = "'Mean' posterior marginals")
+grid1 = -6.0:0.01:4.0
+
+for iter in [ 1, 2, 10 ]
+
+    estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = "Estimated mean after $iter VMP iterations")
+
+end
+
+plot!(p1, [ real_mean ], seriestype = :vline, label = "Real mean", color = :red4, opacity = 0.7)
Example block output
p2    = plot(title = "'Precision' posterior marginals")
+grid2 = 0.01:0.001:0.35
+
+for iter in [ 2, 3, 10 ]
+
+    estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))
+    e_pdf     = (x) -> pdf(estimated, x)
+
+    plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = "Estimated precision after $iter VMP iterations")
+
+end
+
+plot!(p2, [ real_precision ], seriestype = :vline, label = "Real precision", color = :red4, opacity = 0.7)
Example block output

Computing Bethe Free Energy

VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.

The RxInfer package exports score function for an observable of free energy values:

fe_observable = score(model, BetheFreeEnergy())
# Reset posterior marginals for `m` and `w`
+setmarginal!(m, vague(NormalMeanVariance))
+setmarginal!(w, vague(Gamma))
+
+fe_values = []
+
+fe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))
+
+vmp_iterations = 10
+
+for _ in 1:vmp_iterations
+    update!(y, data)
+end
+
+unsubscribe!(fe_subscription)
plot(fe_values, label = "Bethe Free Energy", xlabel = "Iteration #")
Example block output
diff --git a/v2.16.2/manuals/inference/overview/index.html b/v2.16.2/manuals/inference/overview/index.html new file mode 100644 index 000000000..3d8c9380c --- /dev/null +++ b/v2.16.2/manuals/inference/overview/index.html @@ -0,0 +1,2 @@ + +Overview · RxInfer.jl
GitHub

Inference execution

The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):

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.

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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.

Automatic inference specification on static datasets

RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section.

Automatic inference specification on real-time datasets

RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section.

Manual inference specification

While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.

diff --git a/v2.16.2/manuals/inference/postprocess/index.html b/v2.16.2/manuals/inference/postprocess/index.html new file mode 100644 index 000000000..c6fb806f5 --- /dev/null +++ b/v2.16.2/manuals/inference/postprocess/index.html @@ -0,0 +1,2 @@ + +Inference results postprocessing · RxInfer.jl
GitHub

Inference results postprocessing

infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:

diff --git a/v2.16.2/manuals/meta-specification/index.html b/v2.16.2/manuals/meta-specification/index.html new file mode 100644 index 000000000..5aec67eb0 --- /dev/null +++ b/v2.16.2/manuals/meta-specification/index.html @@ -0,0 +1,122 @@ + +Meta specification · RxInfer.jl
GitHub

Meta Specification

Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.

General syntax

@meta macro accepts either regular Julia function or a single begin ... end block:

@meta function MyModelMeta(arg1, arg2)
+    Node(y,x) -> MetaObject(arg1, arg2)
+end
+
+my_meta = @meta begin 
+    Node(y,x) -> MetaObject(arg1, arg2)
+end

In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order $5$ can be specified as follows:

@meta function ARmodel_meta(num_order)
+    AR() -> ARMeta(Univariate, num_order, ARsafe())
+end
+
+my_meta = ARmodel_meta(5)

In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:

num_order = 5
+
+my_meta = @meta begin 
+    AR() -> ARMeta(Multivariate, num_order, ARsafe())
+end

Both syntax variations provide the same meta specification and there is no preference given to one over the other.

Options specification

@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. 

my_meta = @meta [ warn = false ] begin 
+   ...
+end
+
+@meta [ warn = false ] function MyModelMeta()
+    ...
+end

List of available options:

  • warn::Bool - enables/disables various warnings with an incompatible model/meta specification

Meta specification

First, let's start with an example:

my_meta = @meta begin 
+    GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))
+end

This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.

You can have a list of as many meta specification entries as possible for different nodes:

my_meta = @meta begin 
+    GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))
+    AR() -> ARMeta(Multivariate, 5, ARsafe())
+    MyCustomNode() -> MyCustomMetaObject(arg1, arg2)
+end

To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:

@model function my_model(arguments...)
+   ...
+end
+
+my_meta = @meta begin 
+    ...
+end
+
+model, returnval = create_model(my_model(arguments...); meta = my_meta)

Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:

inferred_result = infer(
+    model = my_model(arguments...),
+    meta = my_meta,
+    ...
+)

Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:

@model function my_model()
+    ...
+
+    y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }
+
+    ...
+end

If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.

Create your own meta

Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:

# create your own meta structure for your custom node
+struct MyCustomMeta
+    arg1 
+    arg2 
+end
+
+# apply the new meta structure to your node
+@meta function model_meta(arg1, arg2)
+    MyCustomNode() -> MyCustomMeta(arg1,arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

or create different meta structures for a node, e.g. AR node:

# create your own meta structure for the AR node
+struct MyARMeta
+    arg1
+    arg2
+end
+
+# apply the new meta structure to the AR node
+@meta function model_meta(arg1, arg2)
+    AR() -> MyARMeta(arg1, arg2)
+end
+
+my_meta = model_meta(value_arg1, value_arg2)

Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.

Example

This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:

\[\begin{aligned} + x & \sim \mathrm{Normal}(2.5, 0.5)\\ + y & \sim \mathrm{Normal}(2*x, 2.0) +\end{aligned}\]

where $y$ is observable data and $x$ is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.

using RxInfer
+
+#create data
+y_data = 4.0
+
+#make model
+@model function gaussian_model()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+#do inference
+inference_result = infer(
+    model = gaussian_model(),
+    data = (y = y_data,)
+)
Inference results:
+  Posteriors       | available for (x)
+

However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean $m$ clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:

#create your new meta structure for Normal node
+struct MetaConstrainedMeanNormal{T}
+    lower_limit :: T
+    upper_limit :: T
+end
+
+#define rules with meta for the Normal node
+@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
+
+@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin
+    return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))
+end
#make model
+@model function gaussian_model_with_meta()
+    y = datavar(Float64)
+
+    x ~ NormalMeanVariance(2.5, 0.5)
+    y ~ NormalMeanVariance(2*x, 2.)
+end
+
+custom_meta = @meta begin
+    NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)
+end
+
+#do inference
+inference_result = inference(
+    model = gaussian_model(),
+    data = (y = y_data,),
+    meta = custom_meta
+)
Inference results:
+  Posteriors       | available for (x)
+

Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.

diff --git a/v2.16.2/manuals/model-specification/index.html b/v2.16.2/manuals/model-specification/index.html new file mode 100644 index 000000000..fe486b8ee --- /dev/null +++ b/v2.16.2/manuals/model-specification/index.html @@ -0,0 +1,117 @@ + +Model specification · RxInfer.jl
GitHub

Model Specification

The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: 

@model function model_name(model_arguments...; model_keyword_arguments...)
+    # model specification here
+    return ...
+end

Model options, model_arguments and model_keyword_arguments are optional and may be omitted:

@model function model_name()
+    # model specification here
+    return ...
+end

The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:

@model function my_model(model_arguments...)
+    # model specification here
+    # ...
+    return x, y
+end
generator = my_model(model_arguments...)

In order to create an instance of the model object we should use the create_model function:

model, (x, y) = create_model(generator)

It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.

A full example before diving in

Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:

@model function state_space_model(n_observations, noise_variance)
+
+    c = constvar(1.0)
+    x = randomvar(n_observations)
+    y = datavar(Float64, n_observations)
+
+    x[1] ~ NormalMeanVariance(0.0, 100.0)
+
+    for i in 2:n_observations
+       x[i] ~ x[i - 1] + c
+       y[i] ~ NormalMeanVariance(x[i], noise_var)
+    end
+
+    return x, y
+end

Graph variables creation

Constants

Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).

You can create a constant within a model specification macro with constvar() function. For example:

@model function model_name(...)
+    ...
+    c = constvar(1.0)
+
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0
+    end
+    ...
+end
Note

constvar() function is supposed to be used only within the @model macro.

Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:

@model function model_name(nsamples::Int, c::ConstVariable)
+    ...
+    # no need to call for a constvar() here
+    for i in 2:n
+        x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`
+    end
+    ...
+end
Note

::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.

Data variables

It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.

Examples: 

@model function model_name(...)
+    ...
+    y = datavar(Float64) # Creates a single data input with `y` as identificator
+    y = datavar(Float64, n) # Returns a vector of  `y_i` data input objects with length `n`
+    y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`
+    y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

datavar() function is supposed to be used only within the @model macro.

datavar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = datavar(Float64, n) where { allow_missing = true }
+    ...
+end

Data variables available options

  • allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.

Random variables

There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.

Examples: 

@model function model_name(...)
+    ...
+    x = randomvar() # Returns a single random variable which can be used later in the model
+    x = randomvar(n) # Returns an vector of random variables with length `n`
+    x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`
+    x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality
+    ...
+end
Note

randomvar() function is supposed to be used only within the @model macro.

randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:

@model function model_name(...)
+    ...
+    y = randomvar() where { prod_constraint = ProdGeneric() }
+    ...
+end

Random variables available options

  • prod_constraint
  • prod_strategy
  • marginal_form_constraint
  • marginal_form_check_strategy
  • messages_form_constraint
  • messages_form_check_strategy
  • pipeline

The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.

Node creation

Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables.

Distributions.jl compatibility

For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.

Note

To quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).

Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:

  1. Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.
  2. Depending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.
  3. In certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.

Tilde syntax

We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define

@model function model_name(...)
+    ...
+    m = randomvar()
+    v = randomvar()
+    y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically
+    ...
+end

Another example, but using a deterministic relation between random variables:

@model function model_name(...)
+    ...
+    a = randomvar()
+    b = randomvar()
+    c ~ a + b
+    ...
+end
Note

The RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.

The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:

noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.

It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.

Note

It is forbidden to use random variable within square brackets in the model specification.

y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.
+
+y ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.

It is also possible to return a node reference from the ~ operator. Use the following syntax:

node, y ~ NormalMeanVariance(mean, var)

Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.

Broadcasting syntax

Note

Broadcasting syntax requires at least v2.1.0 of GraphPPL.jl

GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:

y = datavar(Float64, n)
+y .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations

More complex expression are also allowed:

m ~ NormalMeanPrecision(0.0, 0.0001)
+t ~ Gamma(1.0, 1.0)
+
+y = randomvar(Float64, n)
+y .~ NormalMeanPrecision(m, t)
A = constvar(...)
+x = randomvar(n)
+y = datavar(Vector{Float64}, n)
+
+w         ~ Wishart(3, diageye(2))
+x[1]      ~ MvNormalMeanPrecision(zeros(2), diageye(2))
+x[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A
+y        .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix

Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:

# Suppose `x` is a 2-dimensional Gaussian distribution
+z .~ x .+ constvar([ 1, 1 ])
+# Which is equivalent to 
+for i in 1:n
+   z[i] ~ x[i] + constvar([ 1, 1 ])
+end

Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:

# Without explicit `constvar`
+z .~ x .+ [ 1, 1 ]
+# Which is equivalent to 
+array = [1, 1]
+for i in 1:n
+   z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian 
+end

Read more about how broadcasting machinery works in Julia in the official documentation.

Node creation options

To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q

A list of the available options specific to the ReactiveMP inference engine is presented below.

Factorisation constraint option

See also Constraints Specification section.

Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:

variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }

where RecognitionFactorisationConstraint can be the following

  1. MeanField()

Automatically specifies a mean-field factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }
  1. FullFactorisation()

Automatically specifies a full factorisation

Example:

y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }
  1. q(μ)q(v)q(out) or q(μ) * q(v) * q(out)

A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.

Examples: 

# Using interface names of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names for some node
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }
+
+# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. 
+# Call `?NormalMeanVariance` to know more about interface names aliases for some node
+# In general aliases correspond to the function names for distribution parameters
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }
+
+# Using random variables names from `~` operator expression
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }
+
+# All methods can be combined easily
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }
+y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }

Metadata option

Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.

z ~ f(x, y) where { meta = ... }
diff --git a/v2.16.2/manuals/understanding-why-to-initialize-messages/02255eda.svg b/v2.16.2/manuals/understanding-why-to-initialize-messages/02255eda.svg new file mode 100644 index 000000000..a750e401c --- /dev/null +++ b/v2.16.2/manuals/understanding-why-to-initialize-messages/02255eda.svg @@ -0,0 +1,296 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/understanding-why-to-initialize-messages/578230ab.svg b/v2.16.2/manuals/understanding-why-to-initialize-messages/578230ab.svg new file mode 100644 index 000000000..29d59c7f2 --- /dev/null +++ b/v2.16.2/manuals/understanding-why-to-initialize-messages/578230ab.svg @@ -0,0 +1,396 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/understanding-why-to-initialize-messages/aa1b032e.svg b/v2.16.2/manuals/understanding-why-to-initialize-messages/aa1b032e.svg new file mode 100644 index 000000000..cf271ceba --- /dev/null +++ b/v2.16.2/manuals/understanding-why-to-initialize-messages/aa1b032e.svg @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v2.16.2/manuals/understanding-why-to-initialize-messages/index.html b/v2.16.2/manuals/understanding-why-to-initialize-messages/index.html new file mode 100644 index 000000000..728784408 --- /dev/null +++ b/v2.16.2/manuals/understanding-why-to-initialize-messages/index.html @@ -0,0 +1,57 @@ + +Messages initialization · RxInfer.jl
GitHub

Understating why we need to initialize messages in RxInfer

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.

Part 1. Framing the problem

John has recently acquired a new car and is keenly interested in its fuel consumption rate. He holds the belief that this rate follows a linear relationship with the variable speed. To validate this hypothesis, he plans to conduct tests by driving his car on the urban roads close to his home, recording both the fuel consumption and speed data. To ascertain the fuel consumption rate, John has opted for Bayesian linear regression as his analytical method.

using Random, Plots, StableRNGs
+
+function generate_data(a, b, v, nr_samples; rng = StableRNG(1234))
+    x = float.(collect(1:nr_samples))
+    y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)
+    return x, y
+end;
+
+# For demonstration purposes we generate some fake data
+x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)
+
+scatter(x_data, y_data, title = "Dataset (City road)", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
Example block output

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:

\[\begin{aligned} +p(y_n \mid a, b) = \mathcal{N}(y_n \mid a x_n + b , 1) +\end{aligned}\]

The recorded speed is denoted as $x_n \in \mathbb{R}$ and the recorded fuel consumption as $y_n \in \mathbb{R}$. Prior beliefs on $a$ and $b$ are informed by the vehicle manual.

\[\begin{aligned} + p(a) &= \mathcal{N}(a \mid m_a, v_a) \\ + p(b) &= \mathcal{N}(b \mid m_b, v_b) +\end{aligned}\]

Together they form the probabilistic model $p(y, a, b) = p(a)p(b) \prod_{N=1}^N p(y_n \mid a, b),$ where the goal is to infer the posterior distributions $p(a \mid y)$ and $p(b\mid y)$.

In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.

using RxInfer
+
+@model function linear_regression(nr_samples)
+    a ~ Normal(mean = 0.0, variance = 1.0)
+    b ~ Normal(mean = 0.0, variance = 100.0)
+
+    x = datavar(Float64, nr_samples)
+    y = datavar(Float64, nr_samples)
+
+    y .~ Normal(mean = a .* x .+ b, variance = 1.0)
+end

Delighted with the convenience offered by the package's inference function (infer), he appreciates the time saved from building everything from the ground up. This feature allows him to effortlessly obtain the desired results for his specific road. Upon consulting the documentation, he proceeds to run the inference function.

results = infer(
+    model        = linear_regression(length(x_data)), 
+    data         = (y = y_data, x = x_data), 
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)

Oeps! Exception?

exception =
+│    Variables [ a, b ] have not been updated after an update event. 
+│    Therefore, make sure to initialize all required marginals and messages. See `initmarginals` and `initmessages` keyword arguments for the inference function. 
+│    See the function documentation for detailed information regarding the initialization.

After running the inference procedure an error appears, which prompts him to initialize all required messages and marginals. Now, John is left pondering the reason behind this requirement. Why is it necessary? Should he indeed initialize all messages and marginals? And if so, how might this impact the inference procedure?

Part 2. Why and What to initialize

Before delving too deeply into the details, it's important to understand that RxInfer constructs a factorized representation of your model using a Forney Style Factor Graph (FFG). In this structure, inference is executed through message passing.

A challenge arises when RxInfer generates the FFG representation with structural loops in certain parts of the graph. These loops indicate that a message or marginal within the loop depends not only on its prior but also on itself. Consequently, proper initialization is crucial for initiating the inference process. Two general rules of thumb guide this initialization, although the intricate details are beyond the scope of this tutorial:

1. Initiate as few messages/marginals as possible when dealing with a loop structure, it will be more efficient and accurate. 2. Prioritize initializing marginals over messages.

How to identify and handle the loops?

Identifying loops is currently a manual process, as the current version of RxInfer doesn't support a graphical representation of the created graph. As such, the manual process involves:

1. Deriving the graphical representation of the model, 2. Identifying loops and the messages or marginals that need to be initialized within the loop.

However, once you receive the message Variables [x, y, z] have not been updated after an update event, it is a good indication that there is a loop in your model. If you see this message, you should check your model for loops and try to initialize the messages and/or marginals that are part of the loop.

Deriving FFG and identifying the loops

John proceeds to derive the FFG for his problem where he identifies where the loops are:

Addons_messages

He does note that there is a loop in his model, namely all $a$ and $b$ variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:

results = infer(
+    model        = linear_regression(length(x_data)),
+    data         = (y = y_data, x = x_data),
+    initmessages = (b = NormalMeanVariance(0.0, 100.0), ),
+    returnvars   = (a = KeepLast(), b = KeepLast()),
+    iterations   = 20,
+    free_energy  = true
+)
+
+# drop first iteration, which is influenced by the `initmessages`
+plot(2:20, results.free_energy[2:end], title="Free energy", xlabel="Iteration", ylabel="Free energy [nats]", legend=false)
Example block output

Now the inference runs without the error! 🎉

as = rand(results.posteriors[:a], 100)
+bs = rand(results.posteriors[:b], 100)
+p = scatter(x_data, y_data, title = "Linear regression with more noise", legend=false)
+xlabel!("Speed")
+ylabel!("Fuel consumption")
+for (a, b) in zip(as, bs)
+    global p = plot!(p, x_data, a .* x_data .+ b, alpha = 0.05, color = :red)
+end
+plot(p, size = (900, 400))
Example block output
diff --git a/v2.16.2/search_index.js b/v2.16.2/search_index.js new file mode 100644 index 000000000..e8fc48011 --- /dev/null +++ b/v2.16.2/search_index.js @@ -0,0 +1,3 @@ +var documenterSearchIndex = {"docs": +[{"location":"manuals/delta-node/#delta-node-manual","page":"Delta node","title":"Delta node manual","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/#Features-and-Supported-Inference-Scenarios","page":"Delta node","title":"Features and Supported Inference Scenarios","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Gaussian Nodes: For delta nodes linked to strictly multivariate or univariate Gaussian distributions, the recommended methods are Linearization or Unscented transforms.\nExponential Family Nodes: For the delta node connected to nodes from the exponential family, the CVI (Conjugate Variational Inference) is the method of choice.\nStacking Delta Nodes: For scenarios where delta nodes are stacked, either Linearization or Unscented transforms are suitable.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The table below summarizes the features of the delta node in RxInfer.jl, categorized by the approximation method:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Methods Gaussian Nodes Exponential Family Nodes Stacking Delta Nodes\nLinearization ✓ ✗ ✓\nUnscented ✓ ✗ ✓\nCVI ✓ ✓ ✗","category":"page"},{"location":"manuals/delta-node/#Gaussian-Case","page":"Delta node","title":"Gaussian Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"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.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For clarity, consider the following example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=0.0, var=1.0)\n y ~ tanh(x)\n z ~ Normal(mean=y, var=1.0)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To perform inference on this model, designate the approximation method for the delta node (here, the tanh function) using the @meta specification:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> Unscented()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"For a deeper understanding of the Unscented method and its parameters, consult the docstrings.","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Given the invertibility of tanh, indicating its inverse function can optimize the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n tanh() -> DeltaMeta(method = Linearization(), inverse = atanh)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"To execute the inference procedure:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"infer(model = delta_node_example(), meta=delta_meta, data = (z = 1.0,))","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"This methodology is consistent even when the delta node is associated with multiple nodes. For instance:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"f(x, g) = x*tanh(g)","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"@model function delta_node_example()\n z = datavar(Float64)\n x ~ Normal(mean=1.0, var=1.0)\n g ~ Normal(mean=1.0, var=1.0)\n y ~ f(x, g)\n z ~ Normal(mean=y, var=0.1)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification is:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization())\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"or simply","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> Linearization()\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"If specific functions outline the backward relation of variables within the f function, you can provide a tuple of inverse functions in the order of the variables:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"delta_meta = @meta begin \n f() -> DeltaMeta(method = Linearization(), inverse=(f_back_x, f_back_g))\nend","category":"page"},{"location":"manuals/delta-node/#Exponential-Family-Case","page":"Delta node","title":"Exponential Family Case","text":"","category":"section"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"When the delta node is associated with nodes from the exponential family (excluding Gaussians), the Linearization and Unscented methods are not applicable. In such cases, the CVI (Conjugate Variational Inference) is available. Here's a modified example:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using RxInfer\n\n@model function delta_node_example1()\n z = datavar(Float64)\n x ~ Gamma(shape=1.0, rate=1.0)\n y ~ tanh(x)\n z ~ Bernoulli(y)\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"The corresponding meta specification can be represented as:","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"using StableRNGs\nusing Optimisers\n\ndelta_meta = @meta begin \n tanh() -> DeltaMeta(method = CVI(StableRNG(42), 100, 100, Optimisers.Descent(0.01)))\nend","category":"page"},{"location":"manuals/delta-node/","page":"Delta node","title":"Delta node","text":"Consult the ProdCVI docstrings for a detailed explanation of these parameters.","category":"page"},{"location":"manuals/inference/postprocess/#user-guide-inference-postprocess","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"","category":"section"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"infer allow users to postprocess the inference result with the postprocess = ... keyword argument. The inference engine operates on wrapper types to distinguish between marginals and messages. By default these wrapper types are removed from the inference results if no addons option is present. Together with the enabled addons, however, the wrapper types are preserved in the inference result output value. Use the options below to change this behaviour:","category":"page"},{"location":"manuals/inference/postprocess/","page":"Inference results postprocessing","title":"Inference results postprocessing","text":"DefaultPostprocess\nUnpackMarginalPostprocess\nNoopPostprocess","category":"page"},{"location":"manuals/inference/postprocess/#RxInfer.DefaultPostprocess","page":"Inference results postprocessing","title":"RxInfer.DefaultPostprocess","text":"DefaultPostprocess picks the most suitable postprocessing step automatically\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.UnpackMarginalPostprocess","page":"Inference results postprocessing","title":"RxInfer.UnpackMarginalPostprocess","text":"This postprocessing step removes the Marginal wrapper type from the result\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/postprocess/#RxInfer.NoopPostprocess","page":"Inference results postprocessing","title":"RxInfer.NoopPostprocess","text":"This postprocessing step does nothing\n\n\n\n\n\n","category":"type"},{"location":"manuals/understanding-why-to-initialize-messages/#Understating-why-we-need-to-initialize-messages-in-RxInfer","page":"Messages initialization","title":"Understating why we need to initialize messages in RxInfer","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"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.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Part-1.-Framing-the-problem","page":"Messages initialization","title":"Part 1. Framing the problem","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"John has recently acquired a new car and is keenly interested in its fuel consumption rate. He holds the belief that this rate follows a linear relationship with the variable speed. To validate this hypothesis, he plans to conduct tests by driving his car on the urban roads close to his home, recording both the fuel consumption and speed data. To ascertain the fuel consumption rate, John has opted for Bayesian linear regression as his analytical method.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"using Random, Plots, StableRNGs\n\nfunction generate_data(a, b, v, nr_samples; rng = StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;\n\n# For demonstration purposes we generate some fake data \nx_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Univariate-regression-with-known-noise","page":"Messages initialization","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"using RxInfer\n\n@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Delighted with the convenience offered by the package's inference function (infer), he appreciates the time saved from building everything from the ground up. This feature allows him to effortlessly obtain the desired results for his specific road. Upon consulting the documentation, he proceeds to run the inference function.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Oeps! Exception?","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"exception =\n│ Variables [ a, b ] have not been updated after an update event. \n│ Therefore, make sure to initialize all required marginals and messages. See `initmarginals` and `initmessages` keyword arguments for the inference function. \n│ See the function documentation for detailed information regarding the initialization.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"After running the inference procedure an error appears, which prompts him to initialize all required messages and marginals. Now, John is left pondering the reason behind this requirement. Why is it necessary? Should he indeed initialize all messages and marginals? And if so, how might this impact the inference procedure?","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Part-2.-Why-and-What-to-initialize","page":"Messages initialization","title":"Part 2. Why and What to initialize","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Before delving too deeply into the details, it's important to understand that RxInfer constructs a factorized representation of your model using a Forney Style Factor Graph (FFG). In this structure, inference is executed through message passing.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"A challenge arises when RxInfer generates the FFG representation with structural loops in certain parts of the graph. These loops indicate that a message or marginal within the loop depends not only on its prior but also on itself. Consequently, proper initialization is crucial for initiating the inference process. Two general rules of thumb guide this initialization, although the intricate details are beyond the scope of this tutorial:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"1.\tInitiate as few messages/marginals as possible when dealing with a loop structure, it will be more efficient and accurate. 2.\tPrioritize initializing marginals over messages.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"How to identify and handle the loops?","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Identifying loops is currently a manual process, as the current version of RxInfer doesn't support a graphical representation of the created graph. As such, the manual process involves:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"1.\tDeriving the graphical representation of the model, 2.\tIdentifying loops and the messages or marginals that need to be initialized within the loop.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"However, once you receive the message Variables [x, y, z] have not been updated after an update event, it is a good indication that there is a loop in your model. If you see this message, you should check your model for loops and try to initialize the messages and/or marginals that are part of the loop.","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/#Deriving-FFG-and-identifying-the-loops","page":"Messages initialization","title":"Deriving FFG and identifying the loops","text":"","category":"section"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"John proceeds to derive the FFG for his problem where he identifies where the loops are:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)\n\n# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"Now the inference runs without the error! 🎉","category":"page"},{"location":"manuals/understanding-why-to-initialize-messages/","page":"Messages initialization","title":"Messages initialization","text":"as = rand(results.posteriors[:a], 100)\nbs = rand(results.posteriors[:b], 100)\np = scatter(x_data, y_data, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data, a .* x_data .+ b, alpha = 0.05, color = :red)\nend\nplot(p, size = (900, 400))","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification","page":"Model specification","title":"Model Specification","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The RxInfer.jl package exports the @model macro for model specification. This @model macro accepts the model specification itself in a form of regular Julia function. For example: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Model options, model_arguments and model_keyword_arguments are optional and may be omitted:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name()\n # model specification here\n return ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro returns a regular Julia function (in this example model_name()) which can be executed as usual. It returns a so-called model generator object, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function my_model(model_arguments...)\n # model specification here\n # ...\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"generator = my_model(model_arguments...)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"In order to create an instance of the model object we should use the create_model function:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"model, (x, y) = create_model(generator)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is not necessary to return anything from the model, in that case RxInfer.jl will automatically inject return nothing to the end of the model function.","category":"page"},{"location":"manuals/model-specification/#A-full-example-before-diving-in","page":"Model specification","title":"A full example before diving in","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Before presenting the details of the model specification syntax, an example of a probabilistic model is given. Here is an example of a simple state space model with latent random variables x and noisy observations y:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function state_space_model(n_observations, noise_variance)\n\n c = constvar(1.0)\n x = randomvar(n_observations)\n y = datavar(Float64, n_observations)\n\n x[1] ~ NormalMeanVariance(0.0, 100.0)\n\n for i in 2:n_observations\n x[i] ~ x[i - 1] + c\n y[i] ~ NormalMeanVariance(x[i], noise_var)\n end\n\n return x, y\nend","category":"page"},{"location":"manuals/model-specification/#Graph-variables-creation","page":"Model specification","title":"Graph variables creation","text":"","category":"section"},{"location":"manuals/model-specification/#user-guide-model-specification-constant-variables","page":"Model specification","title":"Constants","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Even though any runtime constant passed to a model as a model argument will be automatically converted to a fixed constant, sometimes it might be useful to create constants by hand (e.g. to avoid copying large matrices across the model and to avoid extensive memory allocations).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"You can create a constant within a model specification macro with constvar() function. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n c = constvar(1.0)\n\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant 1.0\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nconstvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Additionally you can specify an extra ::ConstVariable type for some of the model arguments. In this case macro automatically converts them to a single constant using constvar() function. E.g.:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(nsamples::Int, c::ConstVariable)\n ...\n # no need to call for a constvar() here\n for i in 2:n\n x[i] ~ x[i - 1] + c # Reuse the same reference to a constant `c`\n end\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\n::ConstVariable annotation does not play role in Julia's multiple dispatch. RxInfer.jl removes this annotation and replaces it with ::Any.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-data-variables","page":"Model specification","title":"Data variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is important to have a mechanism to pass data values to the model. You can create data inputs with datavar() function. As a first argument it accepts a type specification and optional dimensionality (as additional arguments or as a tuple). User can treat datavar()s in the model as both clamped values for priors and observations.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64) # Creates a single data input with `y` as identificator\n y = datavar(Float64, n) # Returns a vector of `y_i` data input objects with length `n`\n y = datavar(Float64, n, m) # Returns a matrix of `y_i_j` data input objects with size `(n, m)`\n y = datavar(Float64, (n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\ndatavar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"datavar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = datavar(Float64, n) where { allow_missing = true }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Data-variables-available-options","page":"Model specification","title":"Data variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"allow_missing = true/false: Specifies if it is possible to pass missing object as an observation. Note however that by default the ReactiveMP inference engine does not expose any message computation rules that involve missings.","category":"page"},{"location":"manuals/model-specification/#user-guide-model-specification-random-variables","page":"Model specification","title":"Random variables","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"There are several ways to create random variables. The first one is an explicit call to randomvar() function. By default it doesn't accept any argument, creates a single random variable in the model and returns it. It is also possible to pass dimensionality arguments to randomvar() function in the same way as for the datavar() function.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n x = randomvar() # Returns a single random variable which can be used later in the model\n x = randomvar(n) # Returns an vector of random variables with length `n`\n x = randomvar(n, m) # Returns a matrix of random variables with size `(n, m)`\n x = randomvar((n, m)) # It is also possible to use a tuple for dimensionality\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nrandomvar() function is supposed to be used only within the @model macro.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"randomvar() call within @model macro supports where { options... } block for extra options specification, e.g:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n y = randomvar() where { prod_constraint = ProdGeneric() }\n ...\nend","category":"page"},{"location":"manuals/model-specification/#Random-variables-available-options","page":"Model specification","title":"Random variables available options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"prod_constraint\nprod_strategy\nmarginal_form_constraint\nmarginal_form_check_strategy\nmessages_form_constraint\nmessages_form_check_strategy\npipeline","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The second way to create a random variable is to create a node with the ~ operator. If the random variable has not yet been created before this call, it will be created automatically during the creation of the node. Read more about the ~ operator below.","category":"page"},{"location":"manuals/model-specification/#Node-creation","page":"Model specification","title":"Node creation","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Factor nodes are used to define a relationship between random variables and/or constants and data inputs. A factor node defines a probability distribution over selected random variables. ","category":"page"},{"location":"manuals/model-specification/#Distributions.jl-compatibility","page":"Model specification","title":"Distributions.jl compatibility","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"For some factor nodes we rely on the syntax from Distributions.jl to make it easy to adopt RxInfer.jl for these users. These nodes include for example the Beta and Wishart distributions. These nodes can be created using the ~ syntax with the arguments as specified in Distributions.jl. Unfortunately, we RxInfer.jl is not yet compatible with all possible distributions to be used as factor nodes. If you feel that you would like to see another node implemented, please file an issue.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Specifically for the Gaussian/Normal case we have custom implementations that yield a higher computational efficiency and improved stability in comparison to Distributions.jl as these are optimized for sampling operations. Our aliases for these distributions therefore do not correspond to the implementations from Distributions.jl. However, our model specification language is compatible with syntax from Distributions.jl for normal distributions, which will be automatically converted. RxInfer has its own implementation because of the following 3 reasons:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Distributions.jl constructs normal distributions by saving the corresponding covariance matrices in a PDMat object from PDMats.jl. This construction always computes the Cholesky decompositions of the covariance matrices, which is very convenient for sampling-based procedures. However, in RxInfer.jl we mostly base our computations on analytical expressions which do not always need to compute the Cholesky decomposition. In order to reduce the overhead that Distributions.jl introduces, we therefore have custom implementations.\nDepending on the update rules, we might favor different parameterizations of the normal distributions. ReactiveMP.jl has quite a variety in parameterizations that allow us to efficient computations where we convert between parameterizations as little as possible.\nIn certain situations we value stability a lot, especially when inverting matrices. PDMats.jl, and hence Distributions.jl, is not capable to fulfill all needs that we have here. Therefore we use PositiveFactorizations.jl to cope with the corner-cases.","category":"page"},{"location":"manuals/model-specification/#Tilde-syntax","page":"Model specification","title":"Tilde syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"We model a random variable by a probability distribution using the ~ operator. For example, to create a random variable y which is modeled by a Normal distribution, where its mean and variance are controlled by the random variables m and v respectively, we define","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n m = randomvar()\n v = randomvar()\n y ~ NormalMeanVariance(m, v) # Creates a `y` random variable automatically\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Another example, but using a deterministic relation between random variables:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"@model function model_name(...)\n ...\n a = randomvar()\n b = randomvar()\n c ~ a + b\n ...\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nThe RxInfer.jl package uses the ~ operator for modelling both stochastic and deterministic relationships between random variables.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"The @model macro automatically resolves any inner function calls into anonymous extra nodes in case this inner function call is a non-linear transformation. It will also create needed anonymous random variables. But it is important to note that the inference backend will try to optimize inner non-linear deterministic function calls in the case where all arguments are constants or data inputs. For example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"noise ~ NormalMeanVariance(mean, inv(precision)) # Will create a non-linear `inv` node in case if `precision` is a random variable. Won't create an additional non-linear node in case if `precision` is a constant or data input.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is possible to use any functional expression within the ~ operator arguments list. The only one exception is the ref expression (e.g x[i]). All reference expressions within the ~ operator arguments list are left untouched during model parsing. This means that the model parser will not create unnecessary nodes when only simple indexing is involved.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nIt is forbidden to use random variable within square brackets in the model specification.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(x[i - 1], variance) # While in principle `i - 1` is an inner function call (`-(i, 1)`) model parser will leave it untouched and won't create any anonymous nodes for `ref` expressions.\n\ny ~ NormalMeanVariance(A * x[i - 1], variance) # This example will create a `*` anonymous node (in case if x[i - 1] is a random variable) and leave `x[i - 1]` untouched.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"It is also possible to return a node reference from the ~ operator. Use the following syntax:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"node, y ~ NormalMeanVariance(mean, var)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Having a node reference can be useful in case the user wants to return it from a model and to use it later on to specify initial joint marginal distributions.","category":"page"},{"location":"manuals/model-specification/#Broadcasting-syntax","page":"Model specification","title":"Broadcasting syntax","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"note: Note\nBroadcasting syntax requires at least v2.1.0 of GraphPPL.jl ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"GraphPPL support broadcasting for ~ operator in the exact same way as Julia itself. A user is free to write an expression of the following form:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y = datavar(Float64, n)\ny .~ NormalMeanVariance(0.0, 1.0) # <- i.i.d observations","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"More complex expression are also allowed:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"m ~ NormalMeanPrecision(0.0, 0.0001)\nt ~ Gamma(1.0, 1.0)\n\ny = randomvar(Float64, n)\ny .~ NormalMeanPrecision(m, t)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A = constvar(...)\nx = randomvar(n)\ny = datavar(Vector{Float64}, n)\n\nw ~ Wishart(3, diageye(2))\nx[1] ~ MvNormalMeanPrecision(zeros(2), diageye(2))\nx[2:end] .~ A .* x[1:end-1] # <- State-space model with transition matrix A\ny .~ MvNormalMeanPrecision(x, w) # <- Observations with unknown precision matrix","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Note, however, that all variables that take part in the broadcasting operation must be defined before either with randomvar or datavar. The exception here is constants that are automatically converted to their constvar equivalent. If you want to prevent broadcasting for some constant (e.g. if you want to add a vector to a multivariate Gaussian distribution) use explicit constvar call:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Suppose `x` is a 2-dimensional Gaussian distribution\nz .~ x .+ constvar([ 1, 1 ])\n# Which is equivalent to \nfor i in 1:n\n z[i] ~ x[i] + constvar([ 1, 1 ])\nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Without explicit constvar Julia's broadcasting machinery would instead attempt to unroll for loop in the following way:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Without explicit `constvar`\nz .~ x .+ [ 1, 1 ]\n# Which is equivalent to \narray = [1, 1]\nfor i in 1:n\n z[i] ~ x[i] + array[i] # This is wrong if `x[i]` is supposed to be a multivariate Gaussian \nend","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Read more about how broadcasting machinery works in Julia in the official documentation.","category":"page"},{"location":"manuals/model-specification/#Node-creation-options","page":"Model specification","title":"Node creation options","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"To pass optional arguments to the node creation constructor the user can use the where { options... } options specification syntax.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) } # mean-field factorisation over q","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A list of the available options specific to the ReactiveMP inference engine is presented below.","category":"page"},{"location":"manuals/model-specification/#Factorisation-constraint-option","page":"Model specification","title":"Factorisation constraint option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"See also Constraints Specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Users can specify a factorisation constraint over the approximate posterior q for variational inference. The general syntax for factorisation constraints over q is the following:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"variable ~ Node(node_arguments...) where { q = RecognitionFactorisationConstraint }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"where RecognitionFactorisationConstraint can be the following","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"MeanField()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a mean-field factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = MeanField() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"FullFactorisation()","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Automatically specifies a full factorisation","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Example:","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"y ~ NormalMeanVariance(y_mean, y_var) where { q = FullFactorisation() }","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"q(μ)q(v)q(out) or q(μ) * q(v) * q(out)","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"A user can specify any factorisation he wants as the multiplication of q(interface_names...) factors. As interface names the user can use the interface names of an actual node (read node's documentation), its aliases (if available) or actual random variable names present in the ~ operator expression.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Examples: ","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"# Using interface names of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names for some node\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(v)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ, v)q(out) }\n\n# Using interface names aliases of a `NormalMeanVariance` node for factorisation constraint. \n# Call `?NormalMeanVariance` to know more about interface names aliases for some node\n# In general aliases correspond to the function names for distribution parameters\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean)q(var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(mean, var)q(out) }\n\n# Using random variables names from `~` operator expression\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean)q(y_var)q(y) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, y_var)q(y) }\n\n# All methods can be combined easily\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(μ)q(y_var)q(out) }\ny ~ NormalMeanVariance(y_mean, y_var) where { q = q(y_mean, v)q(y) }","category":"page"},{"location":"manuals/model-specification/#Metadata-option","page":"Model specification","title":"Metadata option","text":"","category":"section"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"Is is possible to pass any extra metadata to a factor node with the meta option. Metadata can be later accessed in message computation rules. See also Meta specification section.","category":"page"},{"location":"manuals/model-specification/","page":"Model specification","title":"Model specification","text":"z ~ f(x, y) where { meta = ... }","category":"page"},{"location":"examples/overview/#examples-overview","page":"Overview","title":"Examples overview","text":"","category":"section"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/overview/","page":"Overview","title":"Overview","text":"Basic examples: Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.\nAdvanced examples: Advanced examples contain more complex inference problems.\nProblem specific: Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference","page":"Manual inference specification","title":"Manual inference","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"For advanced use cases it is advised to use manual inference specification. ","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Manual inference specification with RxInfer usually consists of the same simple building blocks and designed in such a way to support both static and real-time infinite datasets:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Create a model with @model macro and get a references to random variables and data inputs\nSubscribe to random variable posterior marginal updates \nSubscribe to Bethe Free Energy updates (optional)\nFeed model with observations \nUnsubscribe from posterior marginal updates (optional)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"It is worth to note that Step 5 is optional and in case where observations come from an infinite real-time data stream (e.g. from an external source or the internet) it may be justified to never unsubscribe and perform real-time Bayesian inference in a reactive manner as soon as data arrives.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-model-creation","page":"Manual inference specification","title":"Model creation","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"During model specification stage user decides on variables of interest in a model and returns (optionally) them using a return ... statement. As an example consider that we have a simple hierarchical model in which the mean of a Normal distribution is represented by another Normal distribution whose mean is modelled by another Normal distribution.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random\n\n@model function my_model()\n m2 ~ NormalMeanVariance(0.0, 1.0)\n m1 ~ NormalMeanVariance(m2, 1.0)\n\n y = datavar(Float64)\n y ~ NormalMeanVariance(m1, 1.0)\n\n # Return variables of interests, optional\n return m1, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"And later on we may create our model with the create_model function and obtain references for variables of interests:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m1, y) = create_model(my_model())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Alternatively, it is possible to query any variable using squared brackets on model object:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model[:m1] # m1\nmodel[:y] # y\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model macro also return a reference for a factor graph as its first return value. Factor graph object (named model in previous example) contains all information about all factor nodes in a model as well as random variables and data inputs.","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-marginal-updates","page":"Manual inference specification","title":"Posterior marginal updates","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer inference engine has a reactive API and operates in terms of Observables and Actors. For detailed information about these concepts we refer to Rocket.jl documentation.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We use getmarginal function from ReactiveMP to get a posterior marginal updates observable:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_updates = getmarginal(m1)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"After that we can subscribe on new updates and perform some actions based on new values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m1_posterior_subscription = subscribe!(m1_posterior_updates, (new_posterior) -> begin\n println(\"New posterior for m1: \", new_posterior)\nend)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Sometimes it is useful to return an array of random variables from model specification, in this case we may use getmarginals() function that transform an array of observables to an observable of arrays.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function my_model()\n ...\n m_n = randomvar(n)\n ...\n return m_n, ...\nend\n\nmodel, (m_n, ...) = create_model(my_model())\n\nm_n_updates = getmarginals(m_n)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-observations","page":"Manual inference specification","title":"Feeding observations","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"By default (without any extra factorisation constraints) model specification implies Belief Propagation message passing update rules. In case of BP algorithm RxInfer package computes an exact Bayesian posteriors with a single message passing iteration. To enforce Belief Propagation message passing update rule for some specific factor node user may use where { q = FullFactorisation() } option. Read more in Model Specification section. To perform a message passing iteration we need to pass some data to all our data inputs that were created with datavar function during model specification.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To feed an observation for a specific data input we use update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As you can see after we passed a single value to our data input we got a posterior marginal update from our subscription and printed it with println function. In case of BP if observations do not change it should not affect posterior marginal results:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"update!(y, 0.0) # Observation didn't change, should result in the same posterior\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"If y is an array of data inputs it is possible to pass an array of observation to update! function:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"for i in 1:length(data)\n update!(y[i], data[i])\nend\n# is an equivalent of\nupdate!(y, data)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp","page":"Manual inference specification","title":"Variational Message Passing","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"Variational message passing (VMP) algorithms are generated much in the same way as the belief propagation algorithm we saw in the previous section. There is a major difference though: for VMP algorithm generation we need to define the factorization properties of our approximate distribution. A common approach is to assume that all random variables of the model factorize with respect to each other. This is known as the mean field assumption. In RxInfer, the specification of such factorization properties is defined during model specification stage using the where { q = ... } syntax or with the @constraints macro (see Constraints specification section for more info about the @constraints macro). Let's take a look at a simple example to see how it is used. In this model we want to learn the mean and precision of a Normal distribution, where the former is modelled with a Normal distribution and the latter with a Gamma.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"real_mean = -4.0\nreal_precision = 0.2\nrng = MersenneTwister(1234)\n\nn = 100\ndata = rand(rng, Normal(real_mean, sqrt(inv(real_precision))), n)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"@model function normal_estimation(n)\n m ~ NormalMeanVariance(0.0, 10.0)\n w ~ Gamma(0.1, 10.0)\n\n y = datavar(Float64, n)\n\n for i in 1:n\n y[i] ~ NormalMeanPrecision(m, w) where { q = MeanField() }\n end\n\n return m, w, y\nend","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"We create our model as usual, however in order to start VMP inference procedure we need to set initial posterior marginals for all random variables in the model:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"model, (m, w, y) = create_model(normal_estimation(n))\n\n# We use vague initial marginals\nsetmarginal!(m, vague(NormalMeanVariance)) \nsetmarginal!(w, vague(Gamma))\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"To perform a single VMP iteration it is enough to feed all data inputs with some values. To perform multiple VMP iterations we should feed our all data inputs with the same values multiple times:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"m_marginals = []\nw_marginals = []\n\nsubscriptions = subscribe!([\n (getmarginal(m), (marginal) -> push!(m_marginals, marginal)),\n (getmarginal(w), (marginal) -> push!(w_marginals, marginal)),\n])\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(subscriptions)\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"As we process more VMP iterations, our beliefs about the possible values of m and w converge and become more confident.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"using Plots\n\np1 = plot(title = \"'Mean' posterior marginals\")\ngrid1 = -6.0:0.01:4.0\n\nfor iter in [ 1, 2, 10 ]\n\n estimated = Normal(mean(m_marginals[iter]), std(m_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p1, grid1, e_pdf, fill = true, opacity = 0.3, label = \"Estimated mean after $iter VMP iterations\")\n\nend\n\nplot!(p1, [ real_mean ], seriestype = :vline, label = \"Real mean\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"p2 = plot(title = \"'Precision' posterior marginals\")\ngrid2 = 0.01:0.001:0.35\n\nfor iter in [ 2, 3, 10 ]\n\n estimated = Gamma(shape(w_marginals[iter]), scale(w_marginals[iter]))\n e_pdf = (x) -> pdf(estimated, x)\n\n plot!(p2, grid2, e_pdf, fill = true, opacity = 0.3, label = \"Estimated precision after $iter VMP iterations\")\n\nend\n\nplot!(p2, [ real_precision ], seriestype = :vline, label = \"Real precision\", color = :red4, opacity = 0.7)","category":"page"},{"location":"manuals/inference/manual/#user-guide-manual-inference-vmp-bfe","page":"Manual inference specification","title":"Computing Bethe Free Energy","text":"","category":"section"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"VMP inference boils down to finding the member of a family of tractable probability distributions that is closest in KL divergence to an intractable posterior distribution. This is achieved by minimizing a quantity known as Variational Free Energy. RxInfer uses Bethe Free Energy approximation to the real Variational Free Energy. Free energy is particularly useful to test for convergence of the VMP iterative procedure.","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"The RxInfer package exports score function for an observable of free energy values:","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"fe_observable = score(model, BetheFreeEnergy())\nnothing #hide","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"# Reset posterior marginals for `m` and `w`\nsetmarginal!(m, vague(NormalMeanVariance))\nsetmarginal!(w, vague(Gamma))\n\nfe_values = []\n\nfe_subscription = subscribe!(fe_observable, (v) -> push!(fe_values, v))\n\nvmp_iterations = 10\n\nfor _ in 1:vmp_iterations\n update!(y, data)\nend\n\nunsubscribe!(fe_subscription)","category":"page"},{"location":"manuals/inference/manual/","page":"Manual inference specification","title":"Manual inference specification","text":"plot(fe_values, label = \"Bethe Free Energy\", xlabel = \"Iteration #\")","category":"page"},{"location":"contributing/new-package/#Contributing-to-the-dependencies","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia programming language makes it extremely easy to create, develop and register new packages in the ecosystem.","category":"page"},{"location":"contributing/new-package/#The-benefits-of-small-packages-for-the-ecosystem","page":"Contributing to the dependencies","title":"The benefits of small packages for the ecosystem","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In the world of software development, there's often a choice to be made between creating a single monolithic package or breaking your codebase into smaller, more focused packages. While both approaches have their merits, opting for smaller packages can offer several significant benefits:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Modularity: Smaller packages focus on specific tasks, making them easier to maintain and debug.\nCollaboration: Teams can work on different packages concurrently, speeding up development.\nVersion Control: Precise versioning and fewer dependencies lead to leaner projects.\nPerformance: Smaller packages can result in faster precompilation (in Julia) and more efficient testing.\nFlexibility: Developers can select and customize packages for their needs.\nCommunity: Smaller packages attract contributors, fostering collaboration and faster feedback.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"In summary, while monolithic packages have their place, opting for smaller, focused packages can bring numerous advantages in terms of modularity, collaboration, version control, flexibility, and community engagement.","category":"page"},{"location":"contributing/new-package/#Use-[PkgTemplates](https://github.com/JuliaCI/PkgTemplates.jl)","page":"Contributing to the dependencies","title":"Use PkgTemplates","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"PkgTemplates.jl is a Julia package to create new Julia packages in an easy, repeatable, and customizable way. You can use the following template to generate a new package:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> using PkgTemplates\n\njulia> USER = \"your github user name\" # Use `reactivebayes` if developing within the ReactiveBayes organisation\n\njulia> template = Template(\n user = USER, \n plugins = [\n CompatHelper(), \n ProjectFile(), \n SrcDir(), \n Git(), \n License(), \n Readme(), \n Tests(), \n GitHubActions(), \n Codecov(), \n Documenter{GitHubActions}(), \n Formatter(style=\"blue\"), \n BlueStyleBadge(), \n PkgEvalBadge()\n])\n\njulia> template(\"MyNewCoolPackage\")","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"This template generates a standard Julia package complete with streamlined documentation, tests, code coverage, and Blue style formatting. Refer to the PkgTemplates documentation if you wish to customize certain steps in the process.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the minimum supported version of Julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"After auto-generation, the minimum supported Julia version will be set to 1.0.0. You can modify this in the Project.toml file, for example:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9.2\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Try to be conservative and set as low version of Julia as possible.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Adjust the authors of the package","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The authors field is present in the Project.toml, e.g ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"authors = [\"John Wick \", ...]","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Add requires dependencies and their [compat] bounds","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"To add new dependencies to your newly created package, start Julia in the package's folder and activate the project using one of the following methods:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"or ","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] activate .","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Then, add dependencies like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia> ] add SomeCoolDependency, SomeOtherCoolDependency","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For each new dependency, it's essential to specify the minimum compatible version in the [compat]section of the Project.toml file, otherwise the official Julia registry will not register your new package. Add the [compat] entries like this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"[compat]\njulia = \"1.9\"\nSomeCoolDependency = \"0.19.2\"\nSomeOtherCoolDependency = \"1.3.12\"","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For more details on compat bounds, check the official Julia documentation.","category":"page"},{"location":"contributing/new-package/#Adjust-README.md","page":"Contributing to the dependencies","title":"Adjust README.md","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The README.md file is the front door to your project, offering a concise introduction and guidance for users and contributors. It's a critical piece of documentation that sets the tone for your project's accessibility and success. A well-crafted README.md provides essential information, such as installation instructions, usage examples, and project goals, making it easier for others to understand, engage with, and contribute to your work. So, remember, taking the time to write a clear and informative README.md.","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"note: Note\nSome badges in the auto-generated README.md will be broken unless you register your package in the official Julia registry.","category":"page"},{"location":"contributing/new-package/#Write-code-and-tests","page":"Contributing to the dependencies","title":"Write code and tests","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The provided template generates a package with testing and test coverage enabled. Ensure to test all new functionality in the test/runtests.jl file.","category":"page"},{"location":"contributing/new-package/#Simplify-Testing-with-ReTestItems","page":"Contributing to the dependencies","title":"Simplify Testing with ReTestItems","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"You can streamline testing by using the ReTestItems package, which support VSCode UI for running tests. Refer to the ReTestItems documentation for more information.","category":"page"},{"location":"contributing/new-package/#Write-code-and-the-documentation","page":"Contributing to the dependencies","title":"Write code and the documentation","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Julia, adding documentation is straightforward with the Documenter.jl package. Add docstrings to newly created functions and update the docs/index.md ` file. To build the documentation locally, use this command (ensure you initialize and instantiate the docs environment first):","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"julia --project=docs docs/make.jl","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"For customization, refer to the Documenter.jl documentation. Also, check out the contributing guide.","category":"page"},{"location":"contributing/new-package/#Hosting-Documentation-with-GitHub-Actions","page":"Contributing to the dependencies","title":"Hosting Documentation with GitHub Actions","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The template provided generates a package with automatic documentation hosting through GitHub Actions. To make this process work, you'll need to generate a DOCUMENTER_KEY using DocumenterTools.jl and add it to your package's repository settings. You can find detailed instructions on how to do this here.","category":"page"},{"location":"contributing/new-package/#Enable-GitHub-Pages-in-Repository-Settings","page":"Contributing to the dependencies","title":"Enable GitHub Pages in Repository Settings","text":"","category":"section"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"The final step for setting up documentation hosting is to enable GitHub Pages in your package's repository settings. To do this:","category":"page"},{"location":"contributing/new-package/","page":"Contributing to the dependencies","title":"Contributing to the dependencies","text":"Navigate to the GitHub Pages settings of your repository.\nChoose the Deploy from a branch option.\nSelect the gh-pages branch.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#examples-assessing-people’s-skills","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The goal of this demo is to demonstrate the use of the @node and @rule macros, which allow the user to define custom factor nodes and associated update rules respectively. We will introduce these macros in the context of a root cause analysis on a student's test results. This demo is inspired by Chapter 2 of \"Model-Based Machine Learning\" by Winn et al.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Problem-Statement","page":"Assessing People’s Skills","title":"Problem Statement","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We consider a student who takes a test that consists of three questions. Answering each question correctly requires a combination of skill and attitude. More precisely, has the student studied for the test, and have they partied the night before?","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We model the result for question i as a continuous variable r_iin01, and skill/attitude as a binary variable s_i in 0 1, where s_1 represents whether the student has partied, and s_2 and s_3 represent whether the student has studied the chapters for the corresponding questions.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We assume the following logic:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"If the student is alert (has not partied), then they will score on the first question;\nIf the student is alert or has studied chapter two, then they will score on question two;\nIf the student can answer question two and has studied chapter three, then they will score on question three.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Definition","page":"Assessing People’s Skills","title":"Generative Model Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"To model the probability for correct answers, we assume a latent state variable t_i in 01. The dependencies between the variables can then be modeled by the following Bayesian network:","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"(s_1) (s_2) (s_3)\n | | |\n v v v\n(t_1)-->(t_2)-->(t_3)\n | | |\n v v v\n(r_1) (r_2) (r_3)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"As prior beliefs, we assume that a student is equally likely to study/party or not: s_i sim Ber(05) for all i. Next, we model the domain logic as beginaligned t_1 = s_1\n t_2 = t_1 s_2\n t_3 = t_2 s_3 endaligned For the scoring results we might not have a specific forward model in mind. However, we can define a backward mapping, from continuous results to discrete latent variables, as t_i sim Ber(s_i) for all i.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Custom-Nodes-and-Rules","page":"Assessing People’s Skills","title":"Custom Nodes and Rules","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"The backward mapping from results to latents is quite specific to our application. Moreover, it does not define a proper generative forward model. In order to still define a full generative model for our application, we can define a custom Score node and define an update rule that implements the backward mapping from scores to latents as a message.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"In RxInfer, the @node macro defines a factor node. This macro accepts the new node type, an indicator for a stochastic or deterministic relationship, and a list of interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"using RxInfer, Random\n\n# Create Score node\nstruct Score end\n\n@node Score Stochastic [out, in]","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now define the backward mapping as a sum-product message through the @rule macro. This macro accepts the node type, the (outbound) interface on which the message is sent, any relevant constraints, and the message/distribution types on the remaining (inbound) interfaces.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Adding update rule for the Score node\n@rule Score(:in, Marginalisation) (q_out::PointMass,) = begin \n return Bernoulli(mean(q_out))\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Generative-Model-Specification","page":"Assessing People’s Skills","title":"Generative Model Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"We can now build the full generative model.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# GraphPPL.jl exports the `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function skill_model()\n s = randomvar(3)\n t = randomvar(3)\n r = datavar(Float64, 3)\n\n # Priors\n for i=1:3\n s[i] ~ Bernoulli(0.5)\n end\n\n # Domain logic\n t[1] ~ ¬s[1]\n t[2] ~ t[1] || s[2]\n t[3] ~ t[2] && s[3]\n \n # Results\n for i=1:3\n r[i] ~ Score(t[i])\n end\nend","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Inference-Specification","page":"Assessing People’s Skills","title":"Inference Specification","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Let us assume that a student scored very low on all questions and set up and execute an inference algorithm.","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"test_results = [0.1, 0.1, 0.1]\ninference_result = infer(\n model = skill_model(),\n data = (r = test_results, )\n)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"Inference results:\n Posteriors | available for (s, t)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/#Results","page":"Assessing People’s Skills","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"# Inspect the results\nmap(params, inference_result.posteriors[:s])","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"3-element Vector{Tuple{Float64}}:\n (0.9872448979591837,)\n (0.06377551020408162,)\n (0.4719387755102041,)","category":"page"},{"location":"examples/advanced_examples/Assessing People Skills/","page":"Assessing People’s Skills","title":"Assessing People’s Skills","text":"These results suggest that this particular student was very likely out on the town last night.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#examples-predicting-bike-rental-demand","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using RxInfer","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Preamble:-Enabling-Predictions","page":"Predicting Bike Rental Demand","title":"Preamble: Enabling Predictions","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"RxInfer.jl facilitates predictions in two primary ways. ","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Implicit Prediction: By adding missing instances directly into the data, which are then treated as regular observations during inference. This method typically does not require model alterations.\nExplicit Prediction: By defining a separate data variable in the model. This approach doesn't necessitate passing missing instances as the data variable but does require specifying the predictvar argument in the inference function.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Example","page":"Predicting Bike Rental Demand","title":"Example","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Consider the following model:","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"@model function example_model()\n y = datavar(Float64) where {allow_missing = true}\n\n h ~ NormalMeanPrecision(0, 1.0)\n x ~ NormalMeanPrecision(h, 1.0)\n y ~ NormalMeanPrecision(x, 10.0)\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Implicit Prediction\nresult = infer(model = example_model(), data = (y = missing,))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Explicit Prediction\nresult = infer(model = example_model(), predictvars = (y = KeepLast(),))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (h, x)\n Predictions | available for (y)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Both approaches yield the same results, but the choice depends on personal preferences and the model's structure. In scenarios with a clear distinction between observed and predicted variables, the explicit method is preferable. However, our subsequent example will not differentiate between observations and predictions, as it utilizes a state space representation.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using CSV, DataFrames, Plots","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Objective","page":"Predicting Bike Rental Demand","title":"Objective","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This example aims to simultaneously learn the dynamics of the feature space and predict hourly bike rental demand through reactive message passing, a signature approach of RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Dataset-Source","page":"Predicting Bike Rental Demand","title":"Dataset Source","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Data for this example study is sourced from the Kaggle Bike Count Prediction Dataset. For the purpose of this example, the original dataset from Kaggle has been adapted by removing categorical variables such as season, holiday, and working day. Additionally we take only 500 entries. This modification allows us to focus on modeling the continuous variables without additional complexities of handling categorical data. Nevertheless, this extension is feasible within RxInfer.jl.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Load the data\ndf = CSV.read(\"../data/bike_count/modified_bicycle.csv\", DataFrame)\ndf[1:10, :]","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"10×6 DataFrame\n Row │ datetime temp atemp humidity windspeed count\n │ String31 Float64 Float64 Float64 Float64 Int64\n─────┼──────────────────────────────────────────────────────────────────\n 1 │ 2011-01-01 0:00:00 9.84 14.395 81.0 0.0 16\n 2 │ 2011-01-01 1:00:00 9.02 13.635 80.0 0.0 40\n 3 │ 2011-01-01 2:00:00 9.02 13.635 80.0 0.0 32\n 4 │ 2011-01-01 3:00:00 9.84 14.395 75.0 0.0 13\n 5 │ 2011-01-01 4:00:00 9.84 14.395 75.0 0.0 1\n 6 │ 2011-01-01 5:00:00 9.84 12.88 75.0 6.0032 1\n 7 │ 2011-01-01 6:00:00 9.02 13.635 80.0 0.0 2\n 8 │ 2011-01-01 7:00:00 8.2 12.88 86.0 0.0 3\n 9 │ 2011-01-01 8:00:00 9.84 14.395 75.0 0.0 8\n 10 │ 2011-01-01 9:00:00 13.12 17.425 76.0 0.0 14","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# we reserve few samples for prediction\nn_future = 24\n\nX = Union{Vector{Float64}, Missing}[[row[i] for i in 2:(ncol(df))-1] for row in eachrow(df)][1:end-n_future]\ny = Union{Float64, Missing}[df[:, \"count\"]...][1:end-n_future]\n\nstate_dim = length(X[1]); # dimensionality of feature space","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Generative-Model-with-Priors","page":"Predicting Bike Rental Demand","title":"Generative Model with Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"We present a generative model that delineates the latent dynamics of feature evolution, represented by mathbfh_t, and their link to the bike rental counts, mathbfy_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Equations-and-Priors","page":"Predicting Bike Rental Demand","title":"Equations and Priors","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Feature Dynamics with Prior:\nPrior: mathbfa sim mathcalN(mathbf0 mathbfI)\nDynamics: mathbfh_t sim mathcalN(mathbfA h_t-1 mathbfQ)\nmathbfA\nis the transition matrix, reshaped from the prior vector mathbfa, and mathbfQ represents process noise.\nNoisy Observations:\nmathbfx_t sim mathcalN(mathbfh_t mathbfP)\nRepresents the observed noisy state of the features.\nCount Prediction with Prior:\nPrior: boldsymboltheta sim mathcalN(mathbf0 mathbfI)\nPrediction: y_t sim mathcalN(textsoftplus(boldsymboltheta^topmathbfh_t) sigma^2)\nModels the bike rental count as influenced by a non-linear transformation of the hidden state.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Interpretation","page":"Predicting Bike Rental Demand","title":"Interpretation","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"This framework aims to simultaneously infer the transition matrix mathbfA and the regression parameters boldsymboltheta, providing a comprehensive view of the feature space dynamics and the count prediction.\nBy employing Gaussian priors on both mathbfa and boldsymboltheta, we incorporate beliefs about their distributions.\nThe inference process aims to discover these underlying dynamics, enabling predictions of both features mathbfx_t and counts y_t.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We augument the dataset with missing entries for 24 hours ahead\nappend!(X, repeat([missing], n_future))\nappend!(y, repeat([missing], n_future));","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# Function to perform the state transition in the model.\n# It reshapes vector `a` into a matrix and multiplies it with vector `x` to simulate the transition.\nfunction transition(a, x)\n nm, n = length(a), length(x)\n m = nm ÷ n # Calculate the number of rows for reshaping 'a' into a matrix\n A = reshape(a, (m, n)) \n return A * x\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"transition (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# The dotsoftplus function combines a dot product and softplus transformation.\n# While useful for ensuring positivity, it may not be the optimal choice for all scenarios,\n# especially if the data suggests other forms of relationships or distributions.\nfunction dotsoftplus(a, x)\n log(1 + exp(dot(a, x)))\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"dotsoftplus (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# model definction\n@model function bicycle_ssm(n, h0, θ0, a0, Q, P)\n\n # `h` is a sequence of hidden states\n h = randomvar(n)\n\n # `x` is a sequence of observed states (features)\n x = datavar(Vector{Float64}, n) where {allow_missing = true}\n # `y` is a sequence of \"count\" bicycles\n y = datavar(Float64, n) where {allow_missing = true}\n\n a ~ MvNormal(μ=a0, Σ=diageye(length(a0)))\n\n θ ~ MvNormal(μ=mean(θ0), Σ=cov(θ0))\n\n h_prior ~ MvNormal(μ=mean(h0), Σ=cov(h0))\n h_prev = h_prior\n \n for i in 1:n\n \n h[i] ~ MvNormal(μ=transition(a, h_prev), Σ=Q)\n \n x[i] ~ MvNormal(μ=h[i], Σ=P)\n \n y[i] ~ Normal(μ=dotsoftplus(θ, h[i]), σ²=1.0)\n \n h_prev = h[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# In this example, we opt for a basic Linearization approach for the transition and dotsoftplus functions.\n# However, alternative methods like Unscented or CVI approximations can also be considered.\ntransition_meta = @meta begin \n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Meta specification:\n transition() -> Linearization()\n dotsoftplus() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# We define rather uninformative priors \nprior_θ = MvNormalMeanCovariance(ones(state_dim), diageye(state_dim))\nprior_h = MvNormalMeanCovariance(zeros(state_dim), 1e2diageye(state_dim))\nprior_a = MvNormalMeanCovariance(zeros(state_dim^2), diageye(state_dim^2))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"MvNormalMeanCovariance(\nμ: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0\n.0, 0.0]\nΣ: [1.0 0.0 … 0.0 0.0; 0.0 1.0 … 0.0 0.0; … ; 0.0 0.0 … 1.0 0.0; 0.0 0.0 … \n0.0 1.0]\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# the deterministic relationsships (transition) and (dotsoftplus) will induce loops in the graph representation of our model, this necessiates the initialization of the messages\nimessages = ( h = prior_h, a = prior_a, θ = prior_θ,)\n\nbicycle_model = bicycle_ssm(length(y), prior_h, prior_θ, prior_a, diageye(state_dim), diageye(state_dim))\n\nresult = infer(\n model = bicycle_model,\n data = (y = y, x=X), \n options = (limit_stack_depth = 500, ), \n returnvars = KeepLast(),\n initmessages = imessages,\n meta = transition_meta,\n iterations = 20,\n showprogress=true,\n)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"Inference results:\n Posteriors | available for (a, h, h_prior, θ)\n Predictions | available for (y, x)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"# For a sake of this example, we extract only predictions\nmean_y, cov_y = mean.(result.predictions[:y]), cov.(result.predictions[:y])\nmean_x, cov_x = mean.(result.predictions[:x]), var.(result.predictions[:x])\n\nmean_x1, cov_x1 = getindex.(mean_x, 1), getindex.(cov_x, 1)\nmean_x2, cov_x2 = getindex.(mean_x, 2), getindex.(cov_x, 2)\nmean_x3, cov_x3 = getindex.(mean_x, 3), getindex.(cov_x, 3)\nmean_x4, cov_x4 = getindex.(mean_x, 4), getindex.(cov_x, 4);","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"slice = (300, length(y))\ndata = df[:, \"count\"][length(y)-n_future:length(y)]\n\np = scatter(y, \n color=:darkblue, \n markerstrokewidth=0,\n label=\"Observed Count\", \n alpha=0.6)\n\n# Plotting the mean prediction with variance ribbon\nplot!(mean_y, ribbon=sqrt.(cov_y), \n color=:orange, \n fillalpha=0.3,\n label=\"Predicted Mean ± Std Dev\")\n\n# Adding a vertical line to indicate the start of the future prediction\nvline!([length(y)-n_future], \n label=\"Prediction Start\", \n linestyle=:dash, \n linecolor=:green)\n\n# Future (unobserved) data\nplot!(length(y)-n_future:length(y), data, label=\"Future Count\")\n\n# Adjusting the limits\nxlims!(slice)\n\n# Enhancing the plot with titles and labels\ntitle!(\"Bike Rental Demand Prediction\")\nxlabel!(\"Time\")\nylabel!(\"Bike Count\")\n\n# Adjust the legend\nlegend=:topright\n\n# Show the final plot\ndisplay(p)","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"using Plots\n\n# Define a color palette\npalette = cgrad(:viridis)\n\n# Plot the hidden states with observations\np1 = plot(mean_x1, ribbon=sqrt.(cov_x1), color=palette[1], label=\"Hidden State 1\", legend=:topleft)\nplot!(df[!, :temp], color=:grey, label=\"Temperature\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Temperature vs Hidden State 1\")\n\np2 = plot(mean_x2, ribbon=sqrt.(cov_x2), color=palette[2], label=\"Hidden State 2\", legend=:topleft)\nplot!(df[!, :atemp], color=:grey, label=\"Feels-Like Temp\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Feels-Like Temp vs Hidden State 2\")\n\np3 = plot(mean_x3, ribbon=sqrt.(cov_x3), color=palette[3], label=\"Hidden State 3\", legend=:topleft)\nplot!(df[!, :humidity], color=:grey, label=\"Humidity\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Humidity vs Hidden State 3\")\n\np4 = plot(mean_x4, ribbon=sqrt.(cov_x4), color=palette[4], label=\"Hidden State 4\", legend=:topleft)\nplot!(df[!, :windspeed], color=:grey, label=\"Windspeed\")\nvline!([length(y)-n_future], linestyle=:dash, color=:red, label=\"Prediction Start\")\nxlabel!(\"Time\")\nylabel!(\"Value\")\ntitle!(\"Windspeed vs Hidden State 4\")\n\nfor p in [p1, p2, p3, p4]\n xlims!(p, first(slice), last(slice))\nend\n\nplot(p1, p2, p3, p4, layout=(2, 2), size=(800, 400))","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/#Conclusion","page":"Predicting Bike Rental Demand","title":"Conclusion","text":"","category":"section"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"While the predictions provided by our current model may not align closely with the real-world data, it's crucial to acknowledge the assumptions and simplifications that were made which could have influenced the outcomes. This model serves as a conceptual framework, demonstrating that it's possible to infer states, parameters, and predictions concurrently with a focus on the predictive aspect of the analysis.","category":"page"},{"location":"examples/basic_examples/Predicting Bike Rental Demand/","page":"Predicting Bike Rental Demand","title":"Predicting Bike Rental Demand","text":"The real power of modeling lies in iteration and refinement. We encourage the community to build upon this foundation. Through collaborative effort and shared insights, we can enhance the predictive accuracy of such models, making them not only illustrative but also practical for real-world applications.","category":"page"},{"location":"manuals/comparison/#comparison","page":"RxInfer.jl vs. Others","title":"Comparison to other packages","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"DISCLAIMER: ","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"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, and we'll be more than willing to rectify.\nThe comparison is more qualitative than quantitative, considering the intricacies of upkeeping benchmarking code for perpetually evolving packages.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Toolbox Universality Efficiency Expressiveness Debugging & Visualization Modularity Inference Engine Language Community & Ecosystem\nRxInfer.jl ~ ✓ ✓ ~ ✗ Message-passing Julia ✗\nForneyLab.jl ✗ ~ ✗ ~ ✗ Message-passing Julia ✗\nInfer.net ~ ✓ ✗ ✓ ✗ Message-passing C# ✗\nPGMax ✗ ✓ ✗ ✓ ✗ Message-passing Python ✗\nTuring.jl ✓ ✗ ✓ ~ ✗ Sampling Julia ✓\nPyMC ✓ ✗ ✓ ✓ ✗ Sampling Python ✓\nNumPyro ✓ ✓ ~ ✓ ✗ Sampling Python ✓\nTensorFlow Probability ✓ ✗ ~ ✓ ✗ Sampling Python ✓\nStan ✓ ✗ ✓ ✓ ✗ Sampling Stan ✓","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"(Date of creation: 20/10/2023)","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Legend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"✓ : Full capability or feature is present.\n~ : Partial capability or feature is present.\n✗ : No capability or feature.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Notes:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: Denotes the capability to depict a vast array of probabilistic models.\nEfficiency: Highlights computational competence. A \"–\" in this context suggests perceived slowness.\nExpressiveness: Assesses the ability to concisely formulate intricate probabilistic models.\nDebugging & Visualization: Evaluates the suite of tools for model debugging and visualization.\nModularity: Reflects the potential to create models by integrating smaller models.\nInference Engines: Pinpoints the primary inference strategy employed by the toolbox.\nLanguage: Identifies the programming language integral to the toolbox.\nCommunity & Ecosystem: Signifies the vibrancy of the ecosystem, inclusive of tools, libraries, and community backing.","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"","category":"page"},{"location":"manuals/comparison/#RxInfer.jl-breakdown","page":"RxInfer.jl vs. Others","title":"RxInfer.jl breakdown","text":"","category":"section"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Universality: RxInfer.jl shines in formulating intricate models derived from the exponential family distributions. The package encompasses not only commonly used distributions such as Gaussian or Bernoulli, but also specialized stochastic nodes that represents prevalent probabilistic models like Autoregressive models, Gamma Mixture models, among others. Furthermore, RxInfer.jl proficiently manages deterministic transformations of variables from the exponential family, see Delta node. Nevertheless, for models outside the exponential family, RxInfer.jl might not be the good choice. Such models would require the creation of novel nodes and corresponding rules, as illustrated in this section.\nEfficiency: RxInfer.jl distinguishes itself with its inference engine rooted in reactive message passing. This approach is supremely efficient, facilitating real-time propagation of updates across the system, supporting parallelization, interruptibility, and more. However, the current version of RxInfer.jl hasn't harnessed all these potentials.\nModularity: Broadly, the toolboxes in the table aren't modular in the truest sense. They don't offer the fusion of models by integrating smaller models. While RxInfer.jl currently doesn't support this, a solution is on the horizon:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"@model function inner_inner(τ, y)\n y ~ Normal(τ[1], τ[2])\nend\n\n@model function inner(θ, α)\n β ~ Normal(0, 1)\n α ~ Gamma(β, 1)\n α ~ inner_inner(τ = θ)\nend\n\n@model function outer()\n local w\n for i = 1:5\n w[i] ~ inner(θ = Gamma(1, 1))\n end\n y ~ inner(θ = w[2:3])\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Expressiveness: RxInfer.jl empowers users to elegantly and concisely craft models, closely mirroring probabilistic notation, thanks to Julia's macro capabilities. To illustrate this, let's consider the following model:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"beginaligned\n x sim mathrmNormal(00 10)\n w sim mathrmInverseGamma(10 10)\n y sim mathrmNormal(x w)\nendaligned","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"The model then is expressed in RxInfer.jl as follows:","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"using RxInfer\n\n@model function example_model()\n x ~ Normal(mean=0.0, var=1.0)\n w ~ InverseGamma(α = 1, θ = 1)\n y ~ Normal(mean = x, var = w)\nend","category":"page"},{"location":"manuals/comparison/","page":"RxInfer.jl vs. Others","title":"RxInfer.jl vs. Others","text":"Debugging & Visualization: While RxInfer.jl struggles with Julia's early-stage debugging system, it does provide a mechanism to debug the inference procedure, even though not as seamlessly as some other packages.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#examples-infinite-data-stream","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"This example shows the capabilities of RxInfer to perform Bayesian inference on real-time signals. As usual, first, we start with importing necessary packages:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"using RxInfer, Plots, Random, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"For demonstration purposes we will create a synthetic environment that has a hidden underlying signal, which we cannot observer directly. Instead, we will observe a noised realisation of this hidden signal:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"mutable struct Environment\n rng :: AbstractRNG\n current_state :: Float64\n observation_precision :: Float64\n history :: Vector{Float64}\n observations :: Vector{Float64}\n \n Environment(current_state, observation_precision; seed = 123) = begin \n return new(StableRNG(seed), current_state, observation_precision, [], [])\n end\nend\n\nfunction getnext!(environment::Environment)\n environment.current_state = environment.current_state + 1.0\n nextstate = 10sin(0.1 * environment.current_state)\n observation = rand(NormalMeanPrecision(nextstate, environment.observation_precision))\n push!(environment.history, nextstate)\n push!(environment.observations, observation)\n return observation\nend\n\nfunction gethistory(environment::Environment)\n return environment.history\nend\n\nfunction getobservations(environment::Environment)\n return environment.observations\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"getobservations (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Model-specification","page":"Infinite Data Stream","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"We assume that we don't know the shape of our signal in advance. So we try to fit a simple gaussian random walk with unknown observation noise:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"@model function kalman_filter()\n \n # Prior for the previous state\n x_prev_mean = datavar(Float64)\n x_prev_var = datavar(Float64)\n \n x_prev ~ Normal(mean = x_prev_mean, variance = x_prev_var)\n \n # Prior for the observation noise\n τ_shape = datavar(Float64)\n τ_rate = datavar(Float64)\n \n τ ~ Gamma(shape = τ_shape, rate = τ_rate)\n \n # Random walk with fixed precision\n x_current ~ Normal(mean = x_prev, precision = 1.0)\n \n # Noisy observation\n y = datavar(Float64)\n y ~ Normal(mean = x_current, precision = τ)\n \nend\n\n# We assume the following factorisation between variables \n# in the variational distribution\n@constraints function filter_constraints()\n q(x_prev, x_current, τ) = q(x_prev, x_current)q(τ)\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"filter_constraints (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Prepare-environment","page":"Infinite Data Stream","title":"Prepare environment","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"initial_state = 0.0\nobservation_precision = 0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"0.1","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"After we have created the environment we can observe how our signal behaves:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"testenvironment = Environment(initial_state, observation_precision);\n\nanimation = @animate for i in 1:100\n getnext!(testenvironment)\n \n history = gethistory(testenvironment)\n observations = getobservations(testenvironment)\n \n p = plot(size = (1000, 300))\n \n p = plot!(p, 1:i, history[1:i], label = \"Hidden signal\")\n p = scatter!(p, 1:i, observations[1:i], ms = 4, alpha = 0.7, label = \"Observation\")\nend\n\ngif(animation, \"../pics/infinite-data-stream.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-static-dataset","page":"Infinite Data Stream","title":"Filtering on static dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"RxInfer is flexible and allows for running inference both on real-time and static datasets. In the next section we show how to perform the filtering procedure on a static dataset. We also will verify our inference procedure by checking on the Bethe Free Energy values:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"n = 300\nstatic_environment = Environment(initial_state, observation_precision);\n\nfor i in 1:n\n getnext!(static_environment)\nend\n\nstatic_history = gethistory(static_environment)\nstatic_observations = getobservations(static_environment);\nstatic_datastream = from(static_observations) |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_static(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n keephistory = 10_000,\n historyvars = (x_current = KeepLast(), τ = KeepLast()),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n free_energy = true,\n autostart = true,\n )\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_static (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"result = run_static(static_environment, static_datastream);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"static_inference = @animate for i in 1:n\n estimated = result.history[:x_current]\n p = plot(1:i, mean.(estimated[1:i]), ribbon = var.(estimated[1:n]), label = \"Estimation\")\n p = plot!(static_history[1:i], label = \"Real states\") \n p = scatter!(static_observations[1:i], ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\nend\n\ngif(static_inference, \"../pics/infinite-data-stream-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"plot(result.free_energy_history, label = \"Bethe Free Energy (averaged)\")","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/#Filtering-on-realtime-dataset","page":"Infinite Data Stream","title":"Filtering on realtime dataset","text":"","category":"section"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"Next lets create a \"real\" infinite stream. We use timer() observable from Rocket.jlto emulate real-world scenario. In our example we are going to generate a new data point every ~41ms (24 data points per second). For demonstration purposes we force stop after n data points, but there is no principled limitation to run inference indefinite:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"function run_and_plot(environment, datastream)\n \n # `@autoupdates` structure specifies how to update our priors based on new posteriors\n # For example, every time we have updated a posterior over `x_current` we update our priors\n # over `x_prev`\n autoupdates = @autoupdates begin \n x_prev_mean, x_prev_var = mean_var(q(x_current))\n τ_shape = shape(q(τ))\n τ_rate = rate(q(τ))\n end\n \n posteriors = []\n \n plotfn = (q_current) -> begin \n IJulia.clear_output(true)\n \n push!(posteriors, q_current)\n\n p = plot(mean.(posteriors), ribbon = var.(posteriors), label = \"Estimation\")\n p = plot!(gethistory(environment), label = \"Real states\") \n p = scatter!(getobservations(environment), ms = 2, label = \"Observations\")\n p = plot(p, size = (1000, 300), legend = :bottomright)\n\n display(p)\n end\n \n engine = infer(\n model = kalman_filter(),\n constraints = filter_constraints(),\n datastream = datastream,\n autoupdates = autoupdates,\n returnvars = (:x_current, ),\n initmarginals = (x_current = NormalMeanVariance(0.0, 1e3), τ = GammaShapeRate(1.0, 1.0)),\n iterations = 10,\n autostart = false,\n )\n \n qsubscription = subscribe!(engine.posteriors[:x_current], plotfn)\n \n RxInfer.start(engine)\n \n return engine\nend","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"run_and_plot (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"# This example runs in our documentation pipeline, which does not support \"real-time\" execution context\n# We skip this code if run not in Jupyter notebook (see below an example with gif)\nengine = nothing \nif isdefined(Main, :IJulia)\n timegen = 41 # 41 ms\n environment = Environment(initial_state, observation_precision);\n observations = timer(timegen, timegen) |> map(Float64, (_) -> getnext!(environment)) |> take(n) # `take!` automatically stops after `n` observations\n datastream = observations |> map(NamedTuple{(:y,), Tuple{Float64}}, (d) -> (y = d, ));\n engine = run_and_plot(environment, datastream)\nend;","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"The plot above is fully interactive and we can stop and unsubscribe from our datastream before it ends:","category":"page"},{"location":"examples/advanced_examples/Infinite Data Stream/","page":"Infinite Data Stream","title":"Infinite Data Stream","text":"if !isnothing(engine) && isdefined(Main, :IJulia)\n RxInfer.stop(engine)\n IJulia.clear_output(true)\nend;","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#examples-universal-mixtures","page":"Universal Mixtures","title":"Universal Mixtures","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"using RxInfer, Distributions, Random, Plots","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane are having a coin toss competition. Before they start, they both have the feeling that something is not right. The coin is unbalanced and favors one side over the other. However, both John and Jane do not know which side is being favored. John thinks that the coin favors heads and Jane thinks tails. Coincidentally, both John and Jane have a strong mathematics background and are aware of the appropriate likelihood function for this experiment","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y_i mid theta) = mathrmBer(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where y_i in 01 are the outcomes of the coin tosses, i.e. heads or tails, and where theta is the coin parameter. They express their gut feeling about the fairness of the coin in terms of a prior distribution over the coin parameter theta, which represents the probability of the coin landing on heads. Based on their gut feeling and the support of thetain01 they come up with the prior beliefs:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJohn) = mathrmBeta(theta mid 7 2)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textJane) = mathrmBeta(theta mid 2 7)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior beliefs\")\nplot!(rθ, (x) -> pdf(Beta(7.0, 2.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) John\", c=1)\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"p(θ) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"John and Jane really want to clear the odds and decide to perform a lengthy experiment. They toss the unbalanced coin N = 10 times, because their favorite TV show is cancelled anyway and therefore they have plenty of time. ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"true_coin = Bernoulli(0.25)\nnr_throws = 10\ndataset = Int.(rand(MersenneTwister(42), true_coin, nr_throws))\nnr_heads, nr_tails = sum(dataset), nr_throws-sum(dataset)\nprintln(\"experimental outcome: \\n - heads: \", nr_heads, \"\\n - tails: \", nr_tails);","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"experimental outcome: \n - heads: 3\n - tails: 7","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"For computing the posterior beliefs p(theta mid y) about the parameter theta, they will perform probabilistic inference in the model based on Bayes' rule. Luckily everything is tractable and therefore they can resort to exact inference. They decide to outsource these tedious computations using RxInfer.jl and specify the following models:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#John's-model:","page":"Universal Mixtures","title":"John's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJohn) = p(theta mid textJohn) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_john(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's prior model over θ\n θ ~ Beta(7.0, 2.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/#Jane's-model:","page":"Universal Mixtures","title":"Jane's model:","text":"","category":"section"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta mid textJane) = p(theta mid textJane) prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_jane(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify Jane's prior model over θ\n θ ~ Beta(2.0, 7.0)\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Now it is time to figure out whose prior belief was the best and who was actually right. They perform probabilistic inference automatically and compute the Bethe free energy to compare eachothers models. For acyclic models, the Bethe free energy mathrmF_B bounds the model evidence p(y) as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"mathrmF_Bpq geq - ln p(y)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_john = infer(\n model = beta_model_john(nr_throws), \n data = (y = dataset, ),\n free_energy = true,\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[8.96366]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_jane = infer(\n model = beta_model_jane(nr_throws), \n data = (y = dataset, ),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (θ)\n Free Energy: | Real[6.63988]","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"From these results, they agree that Jane her gut feeling was right all along, as her Bethe free energy is lower and therefore her model evidence is higher. Nonetheless, after the 10 throws, they now have a better idea about the underlying theta parameter. They formulate this through the posterior distributions p(theta mid y textJohn) and p(theta mid y textJane):","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior beliefs\")\nplot!(rθ, (x) -> pdf(result_john.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) John\", c=1)\nplot!(rθ, (x) -> pdf(result_jane.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"p(θ|y) Jane\", c=3,)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"What John and Jane did not know, was that Mary, their neighbour, was overhearing their conversation. She was also curious, but could not see the coin. She did not really know how to formulate a prior distribution over theta, so instead she combined both John and Jane their prior beliefs. She had the feeling that John his assessment was more correct, as he was often going to the casino. As a result, she mixed the prior beliefs of John and Jane with proportions 0.7 and 0.3, respectively. Her model for the environment is specified as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(y theta c mid textMary) = p(c mid textMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c prod_i=1^N p(y_i mid theta)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"where c describes the probability of John being correct as ","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(c mid textMary) = mathrmBer(c mid 07)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"The predictive distribution p(theta mid textMary) for theta (similar to the prior beliefs of John and Jane) she obtained from the marginalisation over c as","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"p(theta mid textMary) = sum_cin01 p(cmidtextMary) p(theta mid textJohn)^c p(theta mid textJane)^1-c = 07 cdot p(theta mid textJohn) + 03 cdot p(theta mid textJane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"prior belief\")\nplot!(rθ, (x) -> pdf(MixtureDistribution([Beta(2.0, 7.0), Beta(7.0, 2.0)], [ 0.3, 0.7 ]), x), fillalpha=0.3, fillrange = 0, label=\"P(θ) Mary\", c=1)\nplot!(rθ, (x) -> 0.7*pdf(Beta(7.0, 2.0), x), c=3, label=\"\")\nplot!(rθ, (x) -> 0.3*pdf(Beta(2.0, 7.0), x), c=3, label=\"\")","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"She was also interested in the results and used the new Mixture node and addons in ReactiveMP.jl. She specified her model as follows and performed inference in this model:","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"@model function beta_model_mary(nr_throws)\n\n # specify experimental outcomes\n y = datavar(Int64, nr_throws)\n\n # specify John's and Jane's prior models over θ\n θ_jane ~ Beta(2.0, 7.0)\n θ_john ~ Beta(7.0, 2.0)\n\n # specify initial guess as to who is right\n john_is_right ~ Bernoulli(0.7) \n\n # specify mixture prior Distribution\n θ ~ Mixture(john_is_right, (θ_jane, θ_john))\n\n # create likelihood models\n for i in 1:nr_throws\n y[i] ~ Bernoulli(θ)\n end\n\n return y, θ\n \nend","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"This Mixture node updates the belief over c on the performance of the individual models of both John and Jane using so-called scale factors, as introduced in Nguyen et al.. The specific update rules for this node can be found here.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"result_mary = infer(\n model = beta_model_mary(nr_throws), \n data = (y = dataset, ),\n returnvars = (θ = KeepLast(), θ_john = KeepLast(), θ_jane = KeepLast(), john_is_right = KeepLast()),\n addons = AddonLogScale(),\n postprocess = UnpackMarginalPostprocess(),\n)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Inference results:\n Posteriors | available for (john_is_right, θ_john, θ, θ_jane)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"Mary was happy, with her mixture prior, she beat John in terms of performance. However, it was not the best decision to think that John was right. In fact, after the experiment there was only a minor possibility remaining that John was right. Her posterior distribution over theta also changed, and as expected the estimate from Jane was more prominent.","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"rθ = range(0, 1, length = 1000)\np = plot(title = \"posterior belief\")\nplot!(rθ, (x) -> pdf(result_mary.posteriors[:θ], x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y) Mary\", c=1)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[1] * pdf(component(result_mary.posteriors[:θ], 1), x), label=\"\", c=3)\nplot!(rθ, (x) -> result_mary.posteriors[:θ].weights[2] * pdf(component(result_mary.posteriors[:θ], 2), x), label=\"\", c=3)","category":"page"},{"location":"examples/problem_specific/Universal Mixtures/","page":"Universal Mixtures","title":"Universal Mixtures","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/overview/#examples-basic_examples-overview","page":"Overview","title":"Basic examples","text":"","category":"section"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Basic examples contain \"Hello World!\" of Bayesian inference in RxInfer.","category":"page"},{"location":"examples/basic_examples/overview/","page":"Overview","title":"Overview","text":"Coin toss model (Beta-Bernoulli): An example of Bayesian inference in Beta-Bernoulli model with IID observations.\nBayesian Linear Regression Tutorial: An extensive tutorial on Bayesian linear regression with RxInfer with a lot of examples, including multivariate and hierarchical linear regression.\nKalman filtering and smoothing: In this demo, we are interested in Bayesian state estimation in different types of State-Space Models, including linear, nonlinear, and cases with missing observations\nPredicting Bike Rental Demand: An illustrative guide to implementing prediction mechanisms within RxInfer.jl, using bike rental demand forecasting as a contextual example.\nHow to train your Hidden Markov Model: An example of structured variational Bayesian inference in Hidden Markov Model with unknown transition and observational matrices.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#examples-global-parameter-optimisation","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"This notebook demonstrates how to optimize parameters in state space models using external optimization packages, such as Optim.jl and Flux.jl. We utilize RxInfer.jl, a powerful package for inference in probabilistic models.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By the end of this notebook, you will have practical knowledge of global parameter optimization in state space models. You will learn how to optimize parameters in both univariate and multivariate state space models, and harness the power of external optimization packages such as Optim.jl and Flux.jl.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Univariate-State-Space-Model","page":"Global Parameter Optimisation","title":"Univariate State Space Model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us try use the following simple state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n x_t = x_t-1 + c \n y_t sim mathcalNleft(x_t p right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Our goal is to optimize parameters c and m_x_0.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function smoothing(n, x0, c::ConstVariable, P::ConstVariable)\n \n x_prior ~ NormalMeanVariance(mean(x0), cov(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n)\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ x_prev + c\n y[i] ~ NormalMeanVariance(x[i], P)\n \n x_prev = x[i]\n end\n\n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"rng = MersenneTwister(42)\n\nP = 1.0\nn = 250\nc_real = -5.0\ndata = c_real .+ collect(1:n) + rand(rng, Normal(0.0, sqrt(P)), n);","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# c[1] is C\n# c[2] is μ0\nfunction f(c)\n x0_prior = NormalMeanVariance(c[2], 100.0)\n result = infer(\n model = smoothing(n, x0_prior, c[1], P), \n data = (y = data,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using Optim","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, ones(2), GradientDescent(), Optim.Options(g_tol = 1e-3, iterations = 100, store_trace = true, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 3.651509e+02 1.001412e+03\n * time: 0.023805856704711914\n * Status: success\n\n * Candidate solution\n Final objective value: 3.645772e+02\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.18e-06 ≰ 0.0e+00\n |x - x'|/|x'| = 2.30e-07 ≰ 0.0e+00\n |f(x) - f(x')| = 9.13e-07 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 2.51e-09 ≰ 0.0e+00\n |g(x)| = 2.56e-06 ≤ 1.0e-03\n\n * Work counters\n Seconds run: 6 (vs limit Inf)\n Iterations: 9\n f(x) calls: 67\n ∇f(x) calls: 67","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res.minimizer # Real values are indeed (c = 1.0 and μ0 = -5.0)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"2-element Vector{Float64}:\n 1.0007749243942134\n -5.14368311177876","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", [ 1.0, c_real ])\nprintln(\"Optimized: \", res.minimizer)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: [1.0, -5.0]\nOptimized: [1.0007749243942134, -5.14368311177876]","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Multivariate-state-space-model","page":"Global Parameter Optimisation","title":"Multivariate state space model","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Let us consider the multivariate state space model:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\n mathbfx_t sim mathcalNleft(mathbfAx_t-1 mathbfQ right) \n mathbfy_t sim mathcalNleft(mathbfx_t mathbfP right) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"with prior ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfx_0 sim mathcalN(mathbfm_x_0 mathbfV_x_0)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"and transition matrix ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nmathbfA = beginbmatrix costheta -sintheta sintheta costheta endbmatrix\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Covariance matrices mathbfV_x_0, mathbfP and mathbfQ are known. Our goal is to optimize parameters mathbfm_x_0 and theta.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"@model function rotate_ssm(n, θ, x0, Q::ConstVariable, P::ConstVariable)\n \n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n \n x_prev = x_prior\n \n A = constvar([ cos(θ) -sin(θ); sin(θ) cos(θ) ])\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(A * x_prev, Q)\n y[i] ~ MvNormalMeanCovariance(x[i], P)\n \n x_prev = x[i]\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Generate data\nfunction generate_rotate_ssm_data()\n rng = MersenneTwister(1234)\n\n θ = π / 8\n A = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\n Q = Matrix(Diagonal(1.0 * ones(2)))\n P = Matrix(Diagonal(1.0 * ones(2)))\n\n n = 300\n\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n \n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(x[i], Q))\n \n x_prev = x[i]\n end\n\n return θ, A, Q, P, n, x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"generate_rotate_ssm_data (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"θ, A, Q, P, n, x, y = generate_rotate_ssm_data();","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function f(θ)\n x0 = MvNormalMeanCovariance([ θ[2], θ[3] ], Matrix(Diagonal(0.01 * ones(2))))\n result = infer(\n model = rotate_ssm(n, θ[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n )\n return result.free_energy[end]\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"f (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"res = optimize(f, zeros(3), LBFGS(), Optim.Options(f_tol = 1e-14, g_tol = 1e-12, show_trace = true, show_every = 10))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Iter Function value Gradient norm \n 0 2.192003e+04 9.032537e+04\n * time: 5.1975250244140625e-5\n * Status: success\n\n * Candidate solution\n Final objective value: 1.161372e+03\n\n * Found with\n Algorithm: L-BFGS\n\n * Convergence measures\n |x - x'| = 5.09e-09 ≰ 0.0e+00\n |x - x'|/|x'| = 4.48e-10 ≰ 0.0e+00\n |f(x) - f(x')| = 0.00e+00 ≤ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 0.00e+00 ≤ 1.0e-14\n |g(x)| = 5.63e-07 ≰ 1.0e-12\n\n * Work counters\n Seconds run: 19 (vs limit Inf)\n Iterations: 9\n f(x) calls: 58\n ∇f(x) calls: 58","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"println(\"Real value vs Optimized\")\nprintln(\"Real: \", θ)\nprintln(\"Optimized: \", res.minimizer[1])\n\n@show sin(θ), sin(res.minimizer[1])\n@show cos(θ), cos(res.minimizer[1])","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Real value vs Optimized\nReal: 0.39269908169872414\nOptimized: 0.3929332481380117\n(sin(θ), sin(res.minimizer[1])) = (0.3826834323650898, 0.3828997634515549)\n(cos(θ), cos(res.minimizer[1])) = (0.9238795325112867, 0.9237898955654058)\n(0.9238795325112867, 0.9237898955654058)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"x0 = MvNormalMeanCovariance([ res.minimizer[2], res.minimizer[3] ], Matrix(Diagonal(100.0 * ones(2))))\n\nresult = infer(\n model = rotate_ssm(n, res.minimizer[1], x0, Q, P), \n data = (y = y,), \n free_energy = true\n)\n\nxmarginals = result.posteriors[:x]\n\npx = plot()\n\npx = plot!(px, getindex.(x, 1), ribbon = diag(Q)[1] .|> sqrt, fillalpha = 0.2, label = \"real₁\")\npx = plot!(px, getindex.(x, 2), ribbon = diag(Q)[2] .|> sqrt, fillalpha = 0.2, label = \"real₂\")\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"inf₁\")\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"inf₂\")\n\nplot(px, size = (1200, 450))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Learning-Kalman-filter-with-LSTM-driven-dynamic","page":"Global Parameter Optimisation","title":"Learning Kalman filter with LSTM driven dynamic","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this example, our focus is on Bayesian state estimation in a Nonlinear State-Space Model. Specifically, we will utilize the time series generated by the Lorenz system as an example. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Our objective is to compute the marginal posterior distribution of the latent (hidden) state x_k at each time step k, considering the history of measurements up to that time step:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"\np(x_k y_1k)\n\n\nThe above expression represents the probability distribution of the latent state x_k given the measurements y_1k up to time step k\n\njulia\nusing RxInfer BenchmarkTools Flux ReverseDiff Random Plots LinearAlgebra ProgressMeter JLD StableRNGs\n\n\n\n\n Generate data\n\njulia\n Lorenz system equations to be used to generate dataset\nBasekwdef mutable struct Lorenz\n dtFloat64\n σFloat64\n ρFloat64\n βFloat64\n xFloat64\n yFloat64\n zFloat64\nend\n\nfunction step(lLorenz)\n dx = lσ * (ly - lx) lx += ldt * dx\n dy = lx * (lρ - lz) - ly ly += ldt * dy\n dz = lx * ly - lβ * lz lz += ldt * dz\nend\n\n\n\n\njulia\n Dataset\nrng = StableRNG(999)\n\nordered_dataset = \nordered_parameters = \nfor σ = 1115\n for ρ = 2327\n for β_nom = 69\n attractor = Lorenz(002 σ ρ β_nom30 1 1 1)\n noise_free_data = 10 10 10\n for i=199\n step(attractor)\n push(noise_free_data attractorx attractory attractorz)\n end\n push(ordered_dataset noise_free_data)\n push(ordered_parameters σ ρ β_nom30)\n end\n end\nend\n\nnew_order = collect(1100)\nshuffle(rngnew_order)\n\ndataset = noisy dataset\nnoise_free_dataset = noise free dataset\nlorenz_parameters = \n\nfor i in new_order\n local data = \n push(noise_free_dataset ordered_dataseti)\n push(lorenz_parameters ordered_parametersi)\n for nfd in ordered_dataseti\n push(datanfd+randn(rng3))\n end\n push(dataset data)\nend\n\ntrainset = dataset160\nvalidset = dataset6180\ntestset = dataset81end\n\nnoise_free_trainset = noise_free_dataset160\nnoise_free_validset = noise_free_dataset6180\nnoise_free_testset = noise_free_dataset81end\n\n\n\n\n\n Data visualization\n\njulia\none_nonoise=noise_free_trainset1\none=trainset1\ngx gy gz = zeros(100) zeros(100) zeros(100)\nrx ry rz = zeros(100) zeros(100) zeros(100)\nfor i=1100\n rxi ryi rzi = onei1 onei2 onei3\n gxi gyi gzi = one_nonoisei1 one_nonoisei2 one_nonoisei3\nend\np1=plot(rxrylabel=Noise observations)\np1=plot(gxgylabel=True state)\nxlabel(x)\nylabel(y)\np2=plot(rxrzlabel=Noise observations)\np2=plot(gxgzlabel=True state)\nxlabel(x)\nylabel(z)\np3=plot(ryrzlabel=Noise observations)\np3=plot(gygzlabel=True state)\nxlabel(y)\nylabel(z)\nplot(p1 p2 p3 size = (800 200)layout=(13))\n\n\n(assetsexamplesGlobal Parameter Optimisation_22_1png)\n\n\n Inference\n\n\nWe use the following state-space model representation\n\nbeginaligned\nx_k sim p(x_k x_k-1) \ny_k sim p(y_k x_k)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where x_k sim p(x_k x_k-1) represents the hidden dynamics of our system. The hidden dynamics of the Lorenz system exhibit nonlinearities and hence cannot be solved in the closed form. One manner of solving this problem is by introducing a neural network to approximate the transition matrix of the Lorenz system. ","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k-1=NN(y_k-1) \np(x_k x_k-1)=mathcalN(x_k A_k-1x_k-1 Q) \np(y_k x_k)=mathcalN(y_k Bx_k R)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"where NN is the neural network. The input is the observation y_k-1, and output is the trasition matrix A_k-1. B denote distortion or measurment matrix. Q and R are covariance matrices. Note that the hidden state x_k comprises three coordinates, i.e. x_k = (rx_k ry_k rz_k)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"By employing this state-space model representation and utilizing the neural network approximation, we can estimate the hidden dynamics and perform inference in the Lorenz system.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Neural Network model\nmutable struct NN\n InputLayer\n OutputLater\n g\n params\n function NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n InputLayer = Dense(W1, b1, relu)\n Lstm = LSTM(W2_1,W2_2,b2,s2_1)\n OutputLayer = Dense(W3, b3)\n g = Chain(InputLayer, OutputLayer);\n new(InputLayer, OutputLayer, g, (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3))\n end\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Model-specification","page":"Global Parameter Optimisation","title":"Model specification","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Note that we treat the trasition matrix A_k-1 as time-varying.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#State Space Model\n@model function ssm(n, As, Q::ConstVariable, B::ConstVariable, R::ConstVariable)\n x = randomvar(n)\n y = datavar(Vector{Float64}, n)\n \n x_prior_mean = zeros(3)\n x_prior_cov = Matrix(Diagonal(ones(3)))\n \n x[1] ~ MvNormalMeanCovariance(x_prior_mean, x_prior_cov)\n y[1] ~ MvNormalMeanCovariance(B * x[1], R) where { q = q(mean)q(out)q(cov) }\n \n for i in 2:n\n x[i] ~ MvNormalMeanCovariance(As[i - 1] * x[i - 1], Q) where { q = q(mean, out)q(cov) }\n y[i] ~ MvNormalMeanCovariance(B * x[i], R) where { q = q(mean)q(out)q(cov) }\n end\n \n return x, y\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We set distortion matrix B and the covariance matrices Q and R as identity matrix.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Q = Matrix(Diagonal(ones(3)))*2\nB = Matrix(Diagonal(ones(3)))\nR = Matrix(Diagonal(ones(3)))\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We use the inference function in the RxInfer.jl. Before that, we need to bulid a function to get the matrix A output by the neural network. And the A is treated as a datavar in the inference function.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"function get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n n = length(data)\n neural = NN(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), data[1:end-1])\n return As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"get_matrix_AS (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"The weights of neural network NN are initialized as follows:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Initial model parameters\nW1, b1 = randn(5, 3)./100, randn(5)./100\nW2_1, W2_2, b2, s2_1, s2_2 = randn(5 * 4, 5) ./ 100, randn(5 * 4, 5) ./ 100, randn(5*4) ./ 100, zeros(5), zeros(5)\nW3, b3 = randn(3, 5) ./ 100, randn(3) ./ 100\n;","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Before network training, we show the inference results for the hidden states:","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset before training\nindex = 1\ndata=testset[index]\nn=length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training-network","page":"Global Parameter Optimisation","title":"Training network","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In this part, we use the Free Energy as the objective function to optimize the weights of network.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# free energy objective to be optimized during training\nfunction fe_tot_est(W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n fe_ = 0\n for train_instance in trainset\n result = infer(\n model = ssm(n, get_matrix_AS(train_instance,W1,b1,W2_1,W2_2,b2,s2_1,W3,b3),Q,B,R), \n data = (y = train_instance, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n )\n fe_ += result.free_energy[end]\n end\n return fe_\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"fe_tot_est (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Training","page":"Global Parameter Optimisation","title":"Training","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Training is a computationally expensive procedure, for the sake of an example we load pre-trained weights\n# Uncomment the following code to train the network manually\n# opt = Flux.Optimise.RMSProp(0.006, 0.95)\n# params = (W1,b1,W2_1,W2_2,b2,s2_1,W3,b3)\n# @showprogress for epoch in 1:800\n# grads = ReverseDiff.gradient(fe_tot_est, params);\n# for i=1:length(params)\n# Flux.Optimise.update!(opt,params[i],grads[i])\n# end\n# end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Test","page":"Global Parameter Optimisation","title":"Test","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"Import the weights of neural network that we have trained.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"W1a, b1a, W2_1a, W2_2a, b2a, s2_1a, W3, b3a = load(\"../data/nn_prediction/weights.jld\")[\"data\"];","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Performance on an instance from the testset after training\nindex = 1\ndata = testset[index]\nn = length(data)\nresult = infer(\n model = ssm(n, get_matrix_AS(data,W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a),Q,B,R), \n data = (y = data, ), \n returnvars = (x = KeepLast(), ),\n free_energy = true\n)\nx_est=result.posteriors[:x]\n\ngx, gy, gz = zeros(100), zeros(100), zeros(100)\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\n\nfor i=1:100\n gx[i], gy[i], gz[i] = noise_free_testset[index][i][1], noise_free_testset[index][i][2], noise_free_testset[index][i][3]\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\n\np1 = plot(rx,label=\"Hidden state rx\")\np1 = plot!(rx_est_m,label=\"Inferred states\", ribbon=rx_est_var)\np1 = scatter!(first.(testset[index]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Hidden state ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Hidden state rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index]), label=\"Observations\", markersize=1.0)\n\nplot(p1, p2, p3, size = (1000, 300))","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/#Prediction","page":"Global Parameter Optimisation","title":"Prediction","text":"","category":"section"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"In the above instances, the observations during whole time are available. For prediction task, we can only access to the observations untill k and estimate the future state at time k+1, k+2, dots,k+T.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"We can still solve this problem by the trained neural network to approximate the transition matrix. And we can get the one-step prediction in the future. Then, the predicted results are feed into the neural network to generate the transition matrix for the next step, and roll into the future to get the multi-step prediction.","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"beginaligned\nA_k=NN(x_k) \np(x_k+1 x_k)=mathcalN(x_k+1 A_kx_k Q) \nendaligned","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"#Define the prediction function\nmultiplyGaussian(A,m,V) = (A * m, A * V * transpose(A))\nsumGaussians(m1,m2,V1,V2) = (m1 + m2, V1 + V2)\n\nfunction runForward(A,B,Q,R,mh_old,Vh_old)\n mh_1, Vh_1 = multiplyGaussian(A,mh_old,Vh_old)\n mh_pred, Vh_pred = sumGaussians(mh_1, zeros(length(mh_old)), Vh_1, Q)\nend\n\nfunction g_predict(mh_old,Vh_old,Q)\n neural = NN(W1a,b1a,W2_1a,W2_2a,b2a,s2_1a,W3,b3a)\n # Flux.reset!(neural)\n As = map((d) -> Matrix(Diagonal(neural.g(d))), [mh_old])\n As = As[1]\n return runForward(As,B,Q,R,mh_old,Vh_old), As\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"g_predict (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"After k=75, the observations are not available, and we predict the future state from k=76 to the end","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"tt = 75\nmh = mean(x_est[tt])\nVh = cov(x_est[tt])\nmo_list, Vo_list, A_list = [], [], [] \ninv_Q = inv(Q)\nfor t=1:100-tt\n (mo, Vo), A_t = g_predict(mh,Vh,inv_Q)\n push!(mo_list, mo)\n push!(Vo_list, Vh)\n push!(A_list, A_t)\n global mh = mo\n global Vh = Vo\nend","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"# Prediction visualization\nrx, ry, rz = zeros(100), zeros(100), zeros(100)\nrx_est_m, ry_est_m, rz_est_m = zeros(100), zeros(100), zeros(100)\nrx_est_var, ry_est_var, rz_est_var = zeros(100), zeros(100), zeros(100)\nfor i=1:tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mean(x_est[i])[1], mean(x_est[i])[2], mean(x_est[i])[3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = var(x_est[i])[1], var(x_est[i])[2], var(x_est[i])[3]\nend\nfor i=tt+1:100\n ii=i-tt\n rx[i], ry[i], rz[i] = testset[index][i][1], testset[index][i][2], testset[index][i][3]\n rx_est_m[i], ry_est_m[i], rz_est_m[i] = mo_list[ii][1], mo_list[ii][2], mo_list[ii][3]\n rx_est_var[i], ry_est_var[i], rz_est_var[i] = Vo_list[ii][1,1], Vo_list[ii][2,2], Vo_list[ii][3,3]\nend\np1 = plot(rx,label=\"Ground truth rx\")\np1 = plot!(rx_est_m,label=\"Inffered state rx\",ribbon=rx_est_var)\np1 = scatter!(first.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\np2 = plot(ry,label=\"Ground truth ry\")\np2 = plot!(ry_est_m,label=\"Inferred states\", ribbon=ry_est_var)\np2 = scatter!(getindex.(testset[index][1:tt], 2), label=\"Observations\", markersize=1.0)\n\np3 = plot(rz,label=\"Ground truth rz\")\np3 = plot!(rz_est_m,label=\"Inferred states\", ribbon=rz_est_var)\np3 = scatter!(last.(testset[index][1:tt]), label=\"Observations\", markersize=1.0)\n\n\nplot(p1, p2, p3, size = (1000, 300),legend=:bottomleft)","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Global Parameter Optimisation/","page":"Global Parameter Optimisation","title":"Global Parameter Optimisation","text":"","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#examples-autoregressive-models","page":"Autoregressive Models","title":"Autoregressive Models","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this example we are going to perform an automated Variational Bayesian Inference for a latent autoregressive model that can be represented as following:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\np(gamma) = mathrmGamma(gammaa b)\np(mathbftheta) = mathcalN(mathbfthetamathbfmu Sigma)\np(x_tmathbfx_t-1t-k) = mathcalN(x_tmathbftheta^Tmathbfx_t-1t-k gamma^-1)\np(y_tx_t) = mathcalN(y_tx_t tau^-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where x_t is a current state of our system, mathbfx_t-1t-k is a sequence of k previous states, k is an order of autoregression process, mathbftheta is a vector of transition coefficients, gamma is a precision of state transition process, y_k is a noisy observation of x_k with precision tau.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"For a more rigorous introduction to Bayesian inference in Autoregressive models we refer to Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"using RxInfer, Distributions, LinearAlgebra, Random, Plots, BenchmarkTools, Parameters","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's generate some synthetic dataset, we use a predefined sets of coeffcients for k = 1, 3 and 5 respectively:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The following coefficients correspond to stable poles\ncoefs_ar_1 = [-0.27002517200218096]\ncoefs_ar_2 = [0.4511170798064709, -0.05740081602446657]\ncoefs_ar_5 = [0.10699399235785655, -0.5237303489793305, 0.3068897071844715, -0.17232255282458891, 0.13323964347539288];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"function generate_ar_data(rng, n, θ, γ, τ)\n order = length(θ)\n states = Vector{Vector{Float64}}(undef, n + 3order)\n observations = Vector{Float64}(undef, n + 3order)\n \n γ_std = sqrt(inv(γ))\n τ_std = sqrt(inv(τ))\n \n states[1] = randn(rng, order)\n \n for i in 2:(n + 3order)\n states[i] = vcat(rand(rng, Normal(dot(θ, states[i - 1]), γ_std)), states[i-1][1:end-1])\n observations[i] = rand(rng, Normal(states[i][1], τ_std))\n end\n \n return states[1+3order:end], observations[1+3order:end]\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"generate_ar_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Seed for reproducibility\nseed = 123\nrng = MersenneTwister(seed)\n\n# Number of observations in synthetic dataset\nn = 500\n\n# AR process parameters\nreal_γ = 1.0\nreal_τ = 0.5\nreal_θ = coefs_ar_5\n\nstates, observations = generate_ar_data(rng, n, real_θ, real_γ, real_τ);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's plot our synthetic dataset:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(first.(states), label = \"Hidden states\")\nscatter!(observations, label = \"Observations\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Next step is to specify probabilistic model, inference constraints and run inference procedure with RxInfer. We will specify two different models for Multivariate AR with order k > 1 and for Univariate AR (reduces to simple State-Space-Model) with order k = 1.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function lar_model(T::Type, n, order, c, τ)\n \n \n # We create a sequence of random variables for hidden states\n x = randomvar(n)\n # As well a sequence of observartions\n y = datavar(Float64, n)\n \n ct = constvar(c)\n # We assume observation noise to be known\n cτ = constvar(τ)\n \n γ = randomvar()\n θ = randomvar()\n x0 = randomvar()\n \n # Prior for first state\n if T === Multivariate\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n x0 ~ MvNormal(μ = zeros(order), Λ = diageye(order))\n else\n γ ~ Gamma(α = 1.0, β = 1.0)\n θ ~ Normal(μ = 0.0, γ = 1.0)\n x0 ~ Normal(μ = 0.0, γ = 1.0)\n end\n \n x_prev = x0\n \n for i in 1:n\n \n x[i] ~ AR(x_prev, θ, γ) \n \n if T === Multivariate\n y[i] ~ Normal(μ = dot(ct, x[i]), γ = cτ)\n else\n y[i] ~ Normal(μ = ct * x[i], γ = cτ)\n end\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@constraints function ar_constraints() \n q(x0, x, θ, γ) = q(x0, x)q(θ)q(γ)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_constraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@meta function ar_meta(artype, order, stype)\n AR() -> ARMeta(artype, order, stype)\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"ar_meta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"morder = 5\nmartype = Multivariate\nmc = ReactiveMP.ar_unit(martype, morder)\nmconstraints = ar_constraints()\nmmeta = ar_meta(martype, morder, ARsafe())\n\nmoptions = (limit_stack_depth = 100, )\n\nmmodel = lar_model(martype, length(observations), morder, mc, real_τ)\nmdata = (y = observations, )\nminitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = MvNormalMeanPrecision(zeros(morder), diageye(morder)))\nmreturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\n# First execution is slow due to Julia's initial compilation \n# Subsequent runs will be faster (benchmarks are below)\nmresult = infer(\n model = mmodel, \n data = mdata,\n constraints = mconstraints,\n meta = mmeta,\n options = moptions,\n initmarginals = minitmarginals,\n returnvars = mreturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@unpack x, γ, θ = mresult.posteriors","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Dict{Symbol, Vector} with 3 entries:\n :γ => GammaShapeRate{Float64}[GammaShapeRate{Float64}(a=251.0, b=47.5918)\n, Ga…\n :θ => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…\n :x => MvNormalWeightedMeanPrecision{Float64, Vector{Float64}, Matrix{Floa\nt64}…","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We will use different initial marginals depending on type of our AR process","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p1 = plot(first.(states), label=\"Hidden state\")\np1 = scatter!(p1, observations, label=\"Observations\")\np1 = plot!(p1, first.(mean.(x)), ribbon = first.(std.(x)), label=\"Inferred states\", legend = :bottomright)\n\np2 = plot(mean.(γ), ribbon = std.(γ), label = \"Inferred transition precision\", legend = :topright)\np2 = plot!([ real_γ ], seriestype = :hline, label = \"Real transition precision\")\n\np3 = plot(mresult.free_energy, label = \"Bethe Free Energy\")\n\nplot(p1, p2, p3, layout = @layout([ a; b c ]))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Let's also plot a subrange of our results:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"subrange = div(n,5):(div(n, 5) + div(n, 5))\n\nplot(subrange, first.(states)[subrange], label=\"Hidden state\")\nscatter!(subrange, observations[subrange], label=\"Observations\")\nplot!(subrange, first.(mean.(x))[subrange], ribbon = sqrt.(first.(var.(x)))[subrange], label=\"Inferred states\", legend = :bottomright)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"It is also interesting to see where our AR coefficients converge to:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"let\n pθ = plot()\n\n θms = mean.(θ)\n θvs = var.(θ)\n \n l = length(θms)\n\n edim(e) = (a) -> map(r -> r[e], a)\n\n for i in 1:length(first(θms))\n pθ = plot!(pθ, θms |> edim(i), ribbon = θvs |> edim(i) .|> sqrt, label = \"Estimated θ[$i]\")\n end\n \n for i in 1:length(real_θ)\n pθ = plot!(pθ, [ real_θ[i] ], seriestype = :hline, label = \"Real θ[$i]\")\n end\n \n plot(pθ, legend = :outertopright, size = (800, 300))\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"$(length(real_θ))-order AR inference Bethe Free Energy: \", last(mresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"5-order AR inference Bethe Free Energy: 1024.0775661298358","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can also run a 1-order AR inference on 5-order AR data:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"uorder = 1\nuartype = Univariate\nuc = ReactiveMP.ar_unit(uartype, uorder)\nuconstraints = ar_constraints()\numeta = ar_meta(uartype, uorder, ARsafe())\n\nuoptions = (limit_stack_depth = 100, )\n\numodel = lar_model(uartype, length(observations), uorder, uc, real_τ)\nudata = (y = observations, )\nuinitmarginals = (γ = GammaShapeRate(1.0, 1.0), θ = NormalMeanPrecision(0.0, 1.0))\nureturnvars = (x = KeepLast(), γ = KeepEach(), θ = KeepEach())\n\nuresult = infer(\n model = umodel, \n data = udata,\n meta = umeta,\n constraints = uconstraints,\n initmarginals = uinitmarginals,\n returnvars = ureturnvars,\n free_energy = true,\n iterations = 50, \n showprogress = false\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"println(\"1-order AR inference Bethe Free Energy: \", last(uresult.free_energy))","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1-order AR inference Bethe Free Energy: 1025.8792949319954","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"if uresult.free_energy[end] > mresult.free_energy[end]\n println(\"We can see that, according to final Bethe Free Energy value, in this example 5-order AR process can describe data better than 1-order AR.\")\nelse\n error(\"AR-1 performs better than AR-5...\") \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"We can see that, according to final Bethe Free Energy value, in this exampl\ne 5-order AR process can describe data better than 1-order AR.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Autoregressive-Moving-Average-Model","page":"Autoregressive Models","title":"Autoregressive Moving Average Model","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Bayesian ARMA model can be effectively implemeted in RxInfer.jl. For theoretical details on Varitional Inference for ARMA model, we refer the reader to the following paper. The Bayesian ARMA model can be written as follows:","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\ne_t sim mathcalN(0 gamma^-1) quad\ntheta sim mathcalMN(mathbf0 mathbfI) quad\neta sim mathcalMN(mathbf0 mathbfI) \nmathbfh_0 sim mathcalMNleft(beginbmatrix\ne_-1 \ne_-2\nendbmatrix mathbfIright) \nmathbfh_t = mathbfSmathbfh_t-1 + mathbfc e_t-1 \nmathbfx_t = boldsymboltheta^topmathbfx_t-1 + boldsymboleta^topmathbfh_t + e_t \nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"where shift matrix mathbfS is","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfS = beginpmatrix\n0 0 \n1 0 \nendpmatrix\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"and unit vector mathbfc: ","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"beginaligned\nmathbfc=1 0\nendaligned","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"when MA order is 2","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In this way, mathbfh_t containing errors e_t can be viewed as hidden state.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"In short, the Bayesian ARMA model has two intractabilities: (1) induced by the multiplication of two Gaussian RVs, i.e., boldsymboleta^topmathbfh_t, (2) induced by errors e_t that prevents analytical update of precision parameter gamma (this can be easily seen when constructing the Factor Graph, i.e. there is a loop). Both problems can be easily resolved in RxInfer.jl, by creating a hybrid inference algorithm based on Loopy Variational Message Passing.","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Load packages\nusing RxInfer, LinearAlgebra, CSV, DataFrames, Plots","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Define shift function\nfunction shift(dim)\n S = Matrix{Float64}(I, dim, dim)\n for i in dim:-1:2\n S[i,:] = S[i-1, :]\n end\n S[1, :] = zeros(dim)\n return S\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"shift (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"@model function ARMA(n, x_prev, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p, q)\n \n c = zeros(p); c[1] = 1.0; # AR\n b = zeros(q); b[1] = 1.0; # MA\n S = shift(q); # MA\n \n # initialize variables\n h = randomvar(n-1)\n e = randomvar(n)\n z = randomvar(n)\n \n x = datavar(Float64, n) where { allow_missing = true }\n \n # priors\n γ ~ Gamma(shape = shape(γ_prior), rate = rate(γ_prior))\n η ~ MvNormal(mean = mean(η_prior), precision = precision(η_prior))\n θ ~ MvNormal(mean = mean(θ_prior), precision = precision(θ_prior))\n τ ~ Gamma(shape = shape(τ_prior), rate = rate(τ_prior))\n \n # initial\n h_0 ~ MvNormal(mean = mean(h_prior), precision = precision(h_prior))\n z[1] ~ AR(h_0, η, τ)\n e[1] ~ Normal(mean = 0.0, precision = γ)\n\n x[1] ~ dot(b, z[1]) + dot(θ, x_prev[1]) + e[1]\n \n h_prev = h_0\n for t in 1:n-1\n \n e[t+1] ~ Normal(mean = 0.0, precision = γ)\n h[t] ~ S*h_prev + b*e[t]\n z[t+1] ~ AR(h[t], η, τ)\n x[t+1] ~ dot(z[t+1], b) + dot(θ, x_prev[t]) + e[t+1]\n h_prev = h[t]\n end\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"To validate our model and inference, we will use American Airlines stock data downloaded from Kaggle","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"x_df = CSV.read(\"../data/arma/aal_stock.csv\", DataFrame)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"1259×7 DataFrame\n Row │ date open high low close volume Name\n │ Date Float64 Float64 Float64 Float64 Int64 String3\n──────┼───────────────────────────────────────────────────────────────────\n 1 │ 2013-02-08 15.07 15.12 14.63 14.75 8407500 AAL\n 2 │ 2013-02-11 14.89 15.01 14.26 14.46 8882000 AAL\n 3 │ 2013-02-12 14.45 14.51 14.1 14.27 8126000 AAL\n 4 │ 2013-02-13 14.3 14.94 14.25 14.66 10259500 AAL\n 5 │ 2013-02-14 14.94 14.96 13.16 13.99 31879900 AAL\n 6 │ 2013-02-15 13.93 14.61 13.93 14.5 15628000 AAL\n 7 │ 2013-02-19 14.33 14.56 14.08 14.26 11354400 AAL\n 8 │ 2013-02-20 14.17 14.26 13.15 13.33 14725200 AAL\n ⋮ │ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮ ⋮\n 1253 │ 2018-01-30 52.45 53.05 52.36 52.59 4741808 AAL\n 1254 │ 2018-01-31 53.08 54.71 53.0 54.32 5962937 AAL\n 1255 │ 2018-02-01 54.0 54.64 53.59 53.88 3623078 AAL\n 1256 │ 2018-02-02 53.49 53.99 52.03 52.1 5109361 AAL\n 1257 │ 2018-02-05 51.99 52.39 49.75 49.76 6878284 AAL\n 1258 │ 2018-02-06 49.32 51.5 48.79 51.18 6782480 AAL\n 1259 │ 2018-02-07 50.91 51.98 50.89 51.4 4845831 AAL\n 1244 rows omitted","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# we will use \"close\" column\nx_data = filter(!ismissing, x_df[:, 5]);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Plot data\nplot(x_data, xlabel=\"day\", ylabel=\"price\", label=false)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"p_order = 10 # AR\nq_order = 4 # MA","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"4","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Training set\ntrain_size = 1000\nx_prev_train = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][1:train_size]\nx_train = Float64.(x_data[p_order+1:end])[1:train_size];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Test set\nx_prev_test = [Float64.(x_data[i+p_order-1:-1:i]) for i in 1:length(x_data)-p_order][train_size+1:end]\nx_test = Float64.(x_data[p_order+1:end])[train_size+1:end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Inference","page":"Autoregressive Models","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Constraints are needed for performing VMP\narma_constraints = @constraints begin\n q(z, h_0, h, η, τ, γ,e) = q(h_0)q(z, h)q(η)q(τ)q(γ)q(e)\nend;","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# This cell defines prior knowledge for model parameters\nh_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nγ_prior = GammaShapeRate(1e4, 1.0)\nτ_prior = GammaShapeRate(1e2, 1.0)\nη_prior = MvNormalMeanPrecision(zeros(q_order), diageye(q_order))\nθ_prior = MvNormalMeanPrecision(zeros(p_order), diageye(p_order));","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# Model's graph has structural loops, hence, it requires pre-initialisation\narma_imarginals = (h_0 = h_prior, h = h_prior, γ = γ_prior, τ = τ_prior, η = η_prior, θ = θ_prior);\narma_imessages = (h_0 = h_prior, h = h_prior);\narma_meta = ar_meta(Multivariate, q_order, ARsafe());","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"result = infer(\n model = ARMA(length(x_train), x_prev_train, h_prior, γ_prior, τ_prior, η_prior, θ_prior, p_order, q_order), \n data = (x = x_train, ),\n initmarginals = arma_imarginals,\n initmessages = arma_imessages,\n constraints = arma_constraints,\n meta = arma_meta,\n iterations = 50,\n options = (limit_stack_depth = 400, ),\n);","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(mean.(result.posteriors[:e][end]), ribbon = var.(result.posteriors[:e][end]), label = \"eₜ\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# extract posteriors\nh_posterior = result.posteriors[:h][end][end]\nγ_posterior = result.posteriors[:γ][end]\nτ_posterior = result.posteriors[:τ][end]\nη_posterior = result.posteriors[:η][end]\nθ_posterior = result.posteriors[:θ][end];","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/#Prediction","page":"Autoregressive Models","title":"Prediction","text":"","category":"section"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"Here we are going to use our inference results in order to predict the dataset itself","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"# The prediction function is aimed at approximating the predictive posterior distribution\n# It triggers the rules in the generative order (in future, RxInfer.jl will provide this function out of the box)\nfunction prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p, q)\n h_out = MvNormalMeanPrecision(mean(h_posterior), precision(h_posterior))\n ar_out = @call_rule AR(:y, Marginalisation) (m_x=h_out, q_θ=η_posterior, q_γ=τ_posterior, meta=ARMeta(Multivariate, p, ARsafe()))\n c = zeros(p); c[1] = 1.0\n b = zeros(q); b[1] = 1.0\n ar_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(b), m_in2=ar_out)\n θ_out = MvNormalMeanPrecision(mean(θ_posterior), precision(θ_posterior))\n ma_dot_out = @call_rule typeof(dot)(:out, Marginalisation) (m_in1=PointMass(x_prev), m_in2=θ_out)\n e_out = @call_rule NormalMeanPrecision(:out, Marginalisation) (q_μ=PointMass(0.0), q_τ=mean(γ_posterior))\n ar_ma = @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_dot_out, m_in2=ma_dot_out) \n @call_rule typeof(+)(:out, Marginalisation) (m_in1=ar_ma, m_in2=e_out) \nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"prediction (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"predictions = []\nfor x_prev in x_prev_test\n push!(predictions, prediction(x_prev, h_posterior, γ_posterior, τ_posterior, η_posterior, θ_posterior, p_order, q_order))\n # after every new prediction we can actually \"retrain\" the model to use the power of Bayesian approach\n # we will skip this part at this notebook\nend","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"plot(x_test, label=\"test data\", legend=:topleft)\nplot!(mean.(predictions)[1:end], ribbon=std.(predictions)[1:end], label=\"predicted\", xlabel=\"day\", ylabel=\"price\")","category":"page"},{"location":"examples/problem_specific/Autoregressive Models/","page":"Autoregressive Models","title":"Autoregressive Models","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/#examples-how-to-train-your-hidden-markov-model","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"","category":"section"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate()\n;","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In this example, we'll be tracking a Roomba as it moves throughout a 3-bedroom apartment consisting of a bathroom, a master bedroom, and a living room. It's important to keep track of your AI's, so we want to make sure we can keep tabs on it whenever we leave the apartment. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"First, in order to track the Roomba's movements using RxInfer, we need to come up with a model. Since we have a discrete set of rooms in the apartment, we can use a categorical distribution to represent the Roomba's position. There are three rooms in the apartment, meaning we need three states in our categorical distribution. At time t, let's call the estimate of the Roomba's position s_t.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"However, we also know that some rooms are more accessible than others, meaning the Roomba is more likely to move between these rooms - for example, it's rare to have a door directly between the bathroom and the master bedroom. We can encode this information using a transition matrix, which we will call A.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Our Roomba is equipped with a small camera that tracks the surface it is moving over. We will use this camera to obtain our observations since we know that there is a carpet in the living room, tiles in the bathroom, and hardwood floors in the master bedroom. However, this method is not foolproof, and sometimes the Roomba will make mistakes and mistake the hardwood floor for tiles or the carpet for hardwood. Don't be too hard on the little guy, it's just a Roomba after all.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"At time t, we will call our observations x_t and encode the mapping from the Roomba's position to the observations in a matrix we call B. B also encodes the likelihood that the Roomba will make a mistake and get the wrong observation. This leaves us with the following model specification:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"beginaligned\n s_t sim mathcalCat(A s_t-1)\n x_t sim mathcalCat(B s_t)\nendaligned","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"This type of discrete state space model is known as a Hidden Markov Model or HMM for short. Our goal is to learn the matrices A and B so we can use them to track the whereabouts of our little cleaning agent.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"using RxInfer, Random, BenchmarkTools, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"In order to generate data to mimic the observations of the Roomba, we need to specify two things: the actual transition probabilities between the states (i.e., how likely is the Roomba to move from one room to another), and the observation distribution (i.e., what type of texture will the Roomba encounter in each room). We can then use these specifications to generate observations from our hidden Markov model (HMM).","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"To generate our observation data, we'll follow these steps:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Assume an initial state for the Roomba. For example, we can start the Roomba in the bedroom.\nDetermine where the Roomba went next by drawing from a Categorical distribution with the transition probabilities between the different rooms.\nDetermine the observation encountered in this room by drawing from a Categorical distribution with the corresponding observation probabilities.\nRepeat steps 2-3 for as many samples as we want.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"The following code implements this process and generates our observation data:","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"\"\"\"\n rand_vec(rng, distribution::Categorical)\n\nThis function returns a one-hot encoding of a random sample from a categorical distribution. The sample is drawn with the `rng` random number generator.\n\"\"\"\nfunction rand_vec(rng, distribution::Categorical) \n k = ncategories(distribution)\n s = zeros(k)\n drawn_category = rand(rng, distribution)\n s[drawn_category] = 1.0\n return s\nend\n\nfunction generate_data(n_samples; seed = 42)\n \n rng = MersenneTwister(seed)\n \n # Transition probabilities \n state_transition_matrix = [0.9 0.0 0.1;\n 0.0 0.9 0.1; \n 0.05 0.05 0.9] \n # Observation noise\n observation_distribution_matrix = [0.9 0.05 0.05;\n 0.05 0.9 0.05;\n 0.05 0.05 0.9] \n # Initial state\n s_initial = [1.0, 0.0, 0.0] \n \n states = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the states\n observations = Vector{Vector{Float64}}(undef, n_samples) # one-hot encoding of the observations\n \n s_prev = s_initial\n \n for t = 1:n_samples\n s_probvec = state_transition_matrix * s_prev\n states[t] = rand_vec(rng, Categorical(s_probvec ./ sum(s_probvec)))\n obs_probvec = observation_distribution_matrix * states[t]\n observations[t] = rand_vec(rng, Categorical(obs_probvec ./ sum(obs_probvec)))\n s_prev = states[t]\n end\n \n return observations, states\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We will generate 100 data points to simulate 100 ticks of the Roomba moving through the apartment. x_data will contain the Roomba's measurements of the floor it's currently on, and s_data will contain information on the room the Roomba was actually in.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Test data\nN = 100\nx_data, s_data = generate_data(N);\n\nscatter(argmax.(s_data), leg=false, xlabel=\"Time\",yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it is time to build our model. As mentioned earlier, we will use Categorical distributions for the states and observations. To learn the A and B matrices we can use MatrixDirichlet priors. For the A-matrix, since we have no apriori idea how the roomba is actually going to move we will assume that it moves randomly. We can represent this by filling our MatrixDirichlet prior on A with ones. Remember that this will get updated once we start learning, so it's fine if our initial guess is not quite accurate. As for the observations, we have good reason to trust our Roomba's measurements. To represent this, we will add large values to the diagonal of our prior on B. However, we also acknowledge that the Roomba is not infallible, so we will add some noise on the off-diagonal entries.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we will use Variational Inference, we also have to specify inference constraints. We will use a structured variational approximation to the true posterior distribution, where we decouple the variational posterior over the states (q(s_0, s)) from the posteriors over the transition matrices (q(A) and q(B)). This dependency decoupling in the approximate posterior distribution ensures that inference is tractable. Let's build the model!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"# Model specification\n@model function hidden_markov_model(n)\n \n A ~ MatrixDirichlet(ones(3,3))\n B ~ MatrixDirichlet([ 10.0 1.0 1.0; \n 1.0 10.0 1.0; \n 1.0 1.0 10.0 ])\n \n s_0 ~ Categorical(fill(1.0 / 3.0, 3))\n \n s = randomvar(n)\n x = datavar(Vector{Float64}, n)\n \n s_prev = s_0\n \n for t in 1:n\n s[t] ~ Transition(s_prev, A) \n x[t] ~ Transition(s[t], B)\n s_prev = s[t]\n end\n \nend\n\n# Constraints specification\n@constraints function hidden_markov_model_constraints()\n q(s_0, s, A, B) = q(s_0, s)q(A)q(B)\nend","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"hidden_markov_model_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Now it's time to perform inference and find out where the Roomba went in our absence. Did it remember to clean the bathroom?","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"We'll be using Variational Inference to perform inference, which means we need to set some initial marginals as a starting point. RxInfer makes this easy with the vague function, which provides an uninformative guess. If you have better ideas, you can try a different initial guess and see what happens.","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Since we're only interested in the final result - the best guess about the Roomba's position - we'll only keep the last results. Let's start the inference process!","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"imodel = hidden_markov_model(N)\nidata = (x = x_data,)\n\nimarginals = (\n A = vague(MatrixDirichlet, 3, 3), \n B = vague(MatrixDirichlet, 3, 3), \n s = vague(Categorical, 3)\n)\n\nireturnvars = (\n A = KeepLast(),\n B = KeepLast(),\n s = KeepLast()\n)\n\nresult = infer(\n model = imodel, \n data = idata,\n constraints = hidden_markov_model_constraints(),\n initmarginals = imarginals, \n returnvars = ireturnvars, \n iterations = 20, \n free_energy = true\n);","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"That was fast! Let's take a look at our results. If we're successful, we should have a good idea about the actual layout of the apartment (a good posterior marginal over A) and about the uncertainty in the roombas observations (A good posterior over B). Let's see if it worked","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for A:\")\nmean(result.posteriors[:A])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for A:\n3×3 Matrix{Float64}:\n 0.871955 0.0290008 0.0572283\n 0.0349989 0.817591 0.135675\n 0.0930457 0.153408 0.807097","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"println(\"Posterior Marginal for B:\")\nmean(result.posteriors[:B])","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Posterior Marginal for B:\n3×3 Matrix{Float64}:\n 0.949636 0.0974741 0.0518997\n 0.0244903 0.833632 0.0277884\n 0.0258734 0.0688939 0.920312","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Finally, we can check if we were successful in keeping tabs on our Roomba's whereabouts. We can also check if our model has converged by looking at the Free Energy. ","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"p1 = scatter(argmax.(s_data), \n title=\"Inference results\", \n label = \"Real\", \n ms = 6, \n legend=:right,\n xlabel=\"Time\" ,\n yticks= ([1,2,3],[\"Bedroom\",\"Living room\",\"Bathroom\"]),\n size=(900,550)\n )\n\np1 = scatter!(p1, argmax.(ReactiveMP.probvec.(result.posteriors[:s])),\n label = \"Inferred\",\n ms = 3\n )\n\np2 = plot(result.free_energy, \n label=\"Free energy\",\n xlabel=\"Iteration Number\"\n )\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Hidden Markov Model/","page":"How to train your Hidden Markov Model","title":"How to train your Hidden Markov Model","text":"Neat! Now you know how to track a Roomba if you ever need to. You also learned how to fit a Hidden Markov Model using RxInfer in the process.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#examples-rts-vs-bifm-smoothing","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"___Credits to Martin de Quincey___","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"This notebook performs Kalman smoothing on a factor graph using message passing, based on the BIFM Kalman smoother. This notebook is based on:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"F. Wadehn, “State Space Methods with Applications in Biomedical Signal Processing,” ETH Zurich, 2019. Accessed: Jun. 16, 2021. [Online]. Available: https://www.research-collection.ethz.ch/handle/20.500.11850/344762\nH. Loeliger, L. Bruderer, H. Malmberg, F. Wadehn, and N. Zalmai, “On sparsity by NUV-EM, Gaussian message passing, and Kalman smoothing,” in 2016 Information Theory and Applications Workshop (ITA), Jan. 2016, pp. 1–10. doi: 10.1109/ITA.2016.7888168.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"We perform Kalman smoothing in the linear state space model, represented by:","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n Z_k+1 = A Z_k + B U_k \n Y_k = C Z_k + W_k\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"with observations Y_k, latent states Z_k and inputs U_k. W_k is the observation noise. A in mathrmR^n times n, B in mathrmR^n times m and C in mathrmR^d times n are the transition matrices in the model. Here n, m and d denote the dimensionality of the latent, input and output dimension, respectively.","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"The corresponding probabilistic model can be represented as ","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"beginaligned\n p(y z u)\n = p(z_0) prod_k=1^N p(y_k mid z_k) p(z_kmid z_k-1 u_k-1) p(u_k-1) \n = mathcalN(z_0 mid mu_z_0 Sigma_z_0) left( prod_k=1^N mathcalN(y_k mid C z_k Sigma_W) delta(z_k - (Az_k-1 + Bu_k-1)) mathcalN(u_k-1 mid mu_i_k-1 Sigma_u_k-1) right)\nendaligned","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Import-packages","page":"RTS vs BIFM Smoothing","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"using RxInfer, Random, LinearAlgebra, BenchmarkTools, ProgressMeter, Plots, StableRNGs","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Data-generation","page":"RTS vs BIFM Smoothing","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_parameters(dim_out::Int64, dim_in::Int64, dim_lat::Int64; seed::Int64 = 123)\n \n # define noise levels\n input_noise = 500.0\n output_noise = 50.0\n\n # create random generator for reproducibility\n rng = MersenneTwister(seed)\n\n # generate matrices, input statistics and noise matrices\n A = diagm(0.8 .* ones(dim_lat) .+ 0.2 * rand(rng, dim_lat)) # size (dim_lat x dim_lat)\n B = rand(dim_lat, dim_in) # size (dim_lat x dim_in)\n C = rand(dim_out, dim_lat) # size (dim_out x dim_lat)\n μu = rand(dim_in) .* collect(1:dim_in) # size (dim_in x 1)\n Σu = input_noise .* collect(Hermitian(randn(rng, dim_in, dim_in) + diagm(10 .+ 10*rand(dim_in)))) # size (dim_in x dim_in)\n Σy = output_noise .* collect(Hermitian(randn(rng, dim_out, dim_out) + diagm(10 .+ 10*rand(dim_out)))) # size (dim_out x dim_out)\n Wu = inv(Σu)\n Wy = inv(Σy)\n \n # return parameters\n return A, B, C, μu, Σu, Σy, Wu, Wy\n\nend;","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function generate_data(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Σu::Array{Float64,2}, Σy::Array{Float64,2}; seed::Int64 = 123)\n \n # create random data generator\n rng = StableRNG(seed)\n \n # preallocate space for variables\n z = Vector{Vector{Float64}}(undef, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n u = rand(rng, MvNormal(μu, Σu), nr_samples)'\n \n # set initial value of latent states\n z_prev = zeros(size(A,1))\n \n # generate data\n for i in 1:nr_samples\n\n # generate new latent state\n z[i] = A * z_prev + B * u[i,:]\n\n # generate new observation\n y[i] = C * z[i] + rand(rng, MvNormal(zeros(dim_out), Σy))\n \n # generate new observation\n z_prev .= z[i]\n \n end\n \n # return generated data\n return z, y, u\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# specify settings\nnr_samples = 200\ndim_out = 3\ndim_in = 3\ndim_lat = 25\n\n# generate parameters\nA, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(dim_out, dim_in, dim_lat);\n \n# generate data\ndata_z, data_y, data_u = generate_data(nr_samples, A, B, C, μu, Σu, Σy);\n\n# visualise data\np = Plots.plot(xlabel = \"sample\", ylabel = \"observations\")\n# plot each dimension independently\nfor i in 1:dim_out\n Plots.scatter!(p, getindex.(data_y, i), label = \"y_$i\", alpha = 0.5, ms = 2)\nend\np","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Model-specification","page":"RTS vs BIFM Smoothing","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function RTS_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n \n # fetch dimensionality\n dim_lat = size(A, 1)\n dim_out = size(C, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # hidden states (random variable)\n u = randomvar(nr_samples) # inputs (random variable)\n y = datavar(Vector{Float64}, nr_samples) # outputs (observed variables)\n \n # set initial hidden state\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n \n # update last/previous hidden state\n z_prev = z_prior\n\n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n \n # specify updated hidden state\n z[i] ~ A * z_prev + B * u[i]\n \n # specify observation\n y[i] ~ MvNormalMeanPrecision(C * z[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"@model function BIFM_smoother(nr_samples::Int64, A::Array{Float64,2}, B::Array{Float64,2}, C::Array{Float64,2}, μu::Array{Float64,1}, Wu::Array{Float64,2}, Wy::Array{Float64,2})\n\n # fetch dimensionality\n dim_lat = size(A, 1)\n \n # initialize variables\n z = randomvar(nr_samples) # latent states\n yt = randomvar(nr_samples) # latent observations\n y = datavar(Vector{Float64}, nr_samples) # actual observations\n u = randomvar(nr_samples) # inputs\n \n # set priors\n z_prior ~ MvNormalMeanPrecision(zeros(dim_lat), 1e-5*diagm(ones(dim_lat)))\n z_tmp ~ BIFMHelper(z_prior) where { q = MeanField() }\n \n # update last/previous hidden state\n z_prev = z_tmp\n \n # loop through observations\n for i in 1:nr_samples\n\n # specify input as random variable\n u[i] ~ MvNormalMeanPrecision(μu, Wu)\n\n # specify observation\n yt[i] ~ BIFM(u[i], z_prev, z[i]) where { meta = BIFMMeta(A, B, C) }\n y[i] ~ MvNormalMeanPrecision(yt[i], Wy)\n \n # update last/previous hidden state\n z_prev = z[i]\n\n end\n \n # set final value\n z[nr_samples] ~ MvNormalMeanPrecision(zeros(dim_lat), zeros(dim_lat, dim_lat))\n \nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Probabilistic-inference","page":"RTS vs BIFM Smoothing","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_RTS(data_y, A, B, C, μu, Wu, Wy)\n \n # In this task the inference is unstable and can diverge\n meta = @meta begin \n *() -> ReactiveMP.MatrixCorrectionTools.ClampSingularValues(tiny, Inf)\n end\n \n result = infer(\n model = RTS_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast()),\n meta = meta\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_RTS (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"function inference_BIFM(data_y, A, B, C, μu, Wu, Wy)\n result = infer(\n model = BIFM_smoother(length(data_y), A, B, C, μu, Wu, Wy),\n data = (y = data_y, ),\n returnvars = (z = KeepLast(), u = KeepLast())\n )\n qs = result.posteriors\n return (qs[:z], qs[:u])\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"inference_BIFM (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Experiments-for-200-observations","page":"RTS vs BIFM Smoothing","title":"Experiments for 200 observations","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"z_RTS, u_RTS = inference_RTS(data_y, A, B, C, μu, Wu, Wy)\nz_BIFM, u_BIFM = inference_BIFM(data_y, A, B, C, μu, Wu, Wy);","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state z\")\n\nmz_RTS = mean.(z_RTS)\nmz_BIFM = mean.(z_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:5\n Plots.scatter!(ax1, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mz_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(data_z, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mz_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"ax1 = Plots.plot(title = \"RTS smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\nax2 = Plots.plot(title = \"BIFM smoother\", xlabel = \"sample\", ylabel = \"latent state u\")\n\nrdata_u = collect(eachrow(data_u))\nmu_RTS = mean.(u_RTS)\nmu_BIFM = mean.(u_BIFM)\n\n# Do not plot all latent states, otherwise the output is just too cluttered\n# The main idea here is to check that both algorithms return the (approximately) same output\nfor i in 1:1\n Plots.scatter!(ax1, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing)\n Plots.plot!(ax1, getindex.(mu_RTS, i), label = nothing)\n Plots.scatter!(ax2, getindex.(rdata_u, i), alpha = 0.1, ms = 2, color = :blue, label = nothing) \n Plots.plot!(ax2, getindex.(mu_BIFM, i), label = nothing)\nend\n\nPlots.plot(ax1, ax2, layout = @layout([ a; b ]))","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/#Benchmark","page":"RTS vs BIFM Smoothing","title":"Benchmark","text":"","category":"section"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"# This example runs in our documentation pipeline, benchmark executes approximatelly in 20 minutes so we bypass it in the documentation\n# For those who are interested in exact benchmark numbers clone this example and set `run_benchmark = true`\nrun_benchmark = false\n\nif run_benchmark\n trials_range = 30\n trials_n = 500\n trials_RTS = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n trials_BIFM = Array{BenchmarkTools.Trial, 1}(undef, trials_range)\n\n\n @showprogress for k = 1 : trials_range\n\n # generate parameters\n local A, B, C, μu, Σu, Σy, Wu, Wy = generate_parameters(3, 3, k);\n \n # generate data|\n local data_z, data_y, data_u = generate_data(trials_n, A, B, C, μu, Σu, Σy);\n\n # run inference\n trials_RTS[k] = @benchmark inference_RTS($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n trials_BIFM[k] = @benchmark inference_BIFM($data_y, $A, $B, $C, $μu, $Wu, $Wy)\n\n end\n\n m_RTS = [median(trials_RTS[k].times) for k=1:trials_range] ./ 1e9\n q1_RTS = [quantile(trials_RTS[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_RTS = [quantile(trials_RTS[k].times, 0.75) for k=1:trials_range] ./ 1e9\n m_BIFM = [median(trials_BIFM[k].times) for k=1:trials_range] ./ 1e9\n q1_BIFM = [quantile(trials_BIFM[k].times, 0.25) for k=1:trials_range] ./ 1e9\n q3_BIFM = [quantile(trials_BIFM[k].times, 0.75) for k=1:trials_range] ./ 1e9;\n\n p = Plots.plot(ylabel = \"duration [sec]\", xlabel = \"latent state dimension\", title = \"Benchmark\", yscale = :log)\n p = Plots.plot!(p, m_RTS, ribbon = ((q1_RTS .- q3_RTS) ./ 2), color = \"blue\", label = \"mean (RTS)\")\n p = Plots.plot!(p, 1:trials_range, m_BIFM, ribbon = ((q1_BIFM .- q3_BIFM) ./ 2), color = \"orange\", label = \"mean (BIFM)\")\n Plots.savefig(p, \"../pics/rts_bifm_benchmark.png\")\n p\nend","category":"page"},{"location":"examples/problem_specific/RTS vs BIFM Smoothing/","page":"RTS vs BIFM Smoothing","title":"RTS vs BIFM Smoothing","text":"(Image: )","category":"page"},{"location":"manuals/meta-specification/#user-guide-meta-specification","page":"Meta specification","title":"Meta Specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Some nodes in the RxInfer.jl inference engine require a meta structure that may be used to either provide additional information to the nodes or customise the inference procedure or the way the nodes compute outbound messages. For instance, the AR node, modeling the Auto-Regressive process, necessitates knowledge of the order of the AR process, or the GCV node (Gaussian Controlled Variance) needs an approximation method to handle non-conjugate relationships between variables in this node. To facilitate these requirements, RxInfer.jl exports @meta macro to specify node-specific meta and contextual information.","category":"page"},{"location":"manuals/meta-specification/#General-syntax","page":"Meta specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts either regular Julia function or a single begin ... end block:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function MyModelMeta(arg1, arg2)\n Node(y,x) -> MetaObject(arg1, arg2)\nend\n\nmy_meta = @meta begin \n Node(y,x) -> MetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the first case it returns a function that returns meta upon calling. For example, the meta for the AR node of order 5 can be specified as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta function ARmodel_meta(num_order)\n AR() -> ARMeta(Univariate, num_order, ARsafe())\nend\n\nmy_meta = ARmodel_meta(5)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"In the second case it returns the meta object directly. For example, the same meta for the AR node can also be defined as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"num_order = 5\n\nmy_meta = @meta begin \n AR() -> ARMeta(Multivariate, num_order, ARsafe())\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Both syntax variations provide the same meta specification and there is no preference given to one over the other. ","category":"page"},{"location":"manuals/meta-specification/#Options-specification","page":"Meta specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@meta macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta [ warn = false ] begin \n ...\nend\n\n@meta [ warn = false ] function MyModelMeta()\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"List of available options:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/meta specification","category":"page"},{"location":"manuals/meta-specification/#Meta-specification","page":"Meta specification","title":"Meta specification","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"First, let's start with an example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x, k, w) -> GCVMetadata(GaussHermiteCubature(20))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This meta specification indicates that for every GCV node in the model with x, k and w as connected variables should use the GCVMetadata(GaussHermiteCubature(20)) meta object.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"You can have a list of as many meta specification entries as possible for different nodes:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"my_meta = @meta begin \n GCV(x1, k1, w1) -> GCVMetadata(GaussHermiteCubature(20))\n AR() -> ARMeta(Multivariate, 5, ARsafe())\n MyCustomNode() -> MyCustomMetaObject(arg1, arg2)\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"To create a model with meta structures the user may pass an optional meta keyword argument for the create_model function:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model(arguments...)\n ...\nend\n\nmy_meta = @meta begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); meta = my_meta)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Alternatively, it is possible to use meta directly in the automatic infer function that accepts meta keyword argument:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"inferred_result = infer(\n model = my_model(arguments...),\n meta = my_meta,\n ...\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: You can also specify metadata for your nodes directly inside @model, without the need to use @meta. For example:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"@model function my_model()\n ...\n\n y ~ AR(x, θ, γ) where { meta = ARMeta(Multivariate, 5, ARsafe()) }\n\n ...\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"If you add node-specific meta to your model this way, then you do not need to use the meta keyword argument in the infer function.","category":"page"},{"location":"manuals/meta-specification/#Create-your-own-meta","page":"Meta specification","title":"Create your own meta","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Although some nodes in RxInfer.jl already come with their own meta structure, you have the flexibility to define different meta structures for those nodes and also for your custorm ones. A meta structure is created by using the struct statement in Julia. For example, the following snippet of code illustrates how you can create your own meta structures for your custom node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for your custom node\nstruct MyCustomMeta\n arg1 \n arg2 \nend\n\n# apply the new meta structure to your node\n@meta function model_meta(arg1, arg2)\n MyCustomNode() -> MyCustomMeta(arg1,arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"or create different meta structures for a node, e.g. AR node:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"# create your own meta structure for the AR node\nstruct MyARMeta\n arg1\n arg2\nend\n\n# apply the new meta structure to the AR node\n@meta function model_meta(arg1, arg2)\n AR() -> MyARMeta(arg1, arg2)\nend\n\nmy_meta = model_meta(value_arg1, value_arg2)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Note: When you define a meta structure for a node, keep in mind that you must define message update rules with the meta for that node. See node manual for more details of how to define rules for a node.","category":"page"},{"location":"manuals/meta-specification/#Example","page":"Meta specification","title":"Example","text":"","category":"section"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"This section provides a concrete example of how to create and use meta in RxInfer.jl. Suppose that we have the following Gaussian model:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"beginaligned\n x sim mathrmNormal(25 05)\n y sim mathrmNormal(2*x 20)\nendaligned","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"where y is observable data and x is a latent variable. In RxInfer.jl, the inference procedure for this model is well defined without the need of specifying any meta data for the Normal node.","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"using RxInfer\n\n#create data\ny_data = 4.0 \n\n#make model\n@model function gaussian_model()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\n#do inference\ninference_result = infer(\n model = gaussian_model(),\n data = (y = y_data,)\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"However, let's say we would like to experiment with message update rules and define a new inference procedure by introducing a meta structure to the Normal node that always yields a Normal distribution with mean m clamped between lower_limit and upper_limit for the outbound messages of the node. This is done as follows:","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#create your new meta structure for Normal node\nstruct MetaConstrainedMeanNormal{T}\n lower_limit :: T\n upper_limit :: T\nend\n\n#define rules with meta for the Normal node\n@rule NormalMeanVariance(:out, Marginalisation) (q_μ::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_μ), meta.lower_limit, meta.upper_limit), mean(q_v))\nend\n\n@rule NormalMeanVariance(:μ, Marginalisation) (q_out::Any, q_v::Any, meta::MetaConstrainedMeanNormal) = begin\n return NormalMeanVariance(clamp(mean(q_out), meta.lower_limit, meta.upper_limit), mean(q_v))\nend","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"#make model\n@model function gaussian_model_with_meta()\n y = datavar(Float64)\n\n x ~ NormalMeanVariance(2.5, 0.5)\n y ~ NormalMeanVariance(2*x, 2.)\nend\n\ncustom_meta = @meta begin\n NormalMeanVariance(y,x) -> MetaConstrainedMeanNormal(-1, 1)\nend\n\n#do inference\ninference_result = inference(\n model = gaussian_model(),\n data = (y = y_data,),\n meta = custom_meta\n)","category":"page"},{"location":"manuals/meta-specification/","page":"Meta specification","title":"Meta specification","text":"Disclaimer: The above example is not mathematically correct. It is only used to show how we can work with @meta as well as how to create a meta structure for a node in RxInfer.jl.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution","page":"Overview","title":"Inference execution","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"The RxInfer inference API supports different types of message-passing algorithms (including hybrid algorithms combining several different types):","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"Belief Propagation\nVariational Message Passing","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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.","category":"page"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"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 by using where { q = ... } syntax or with the help of the @constraints macro. Different factorisation constraints lead to a different message passing update rules. See more documentation about constraints specification in the corresponding section.","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-static","page":"Overview","title":"Automatic inference specification on static datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer exports the infer function to quickly run and test you model with static datasets. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-automatic-specification-realtime","page":"Overview","title":"Automatic inference specification on real-time datasets","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"RxInfer supports running inference the with dynamic and potentially real-time datasets with enabled autoupdates keyword. See more information about the infer function on the separate documentation section. ","category":"page"},{"location":"manuals/inference/overview/#user-guide-inference-execution-manual-specification","page":"Overview","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/inference/overview/","page":"Overview","title":"Overview","text":"While infer uses most of the RxInfer inference engine capabilities in some situations it might be beneficial to write inference code manually. The Manual inference documentation section explains how to write your custom inference routines.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#examples-chance-constrained-active-inference","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"This notebook applies reactive message passing for active inference in the context of chance-constraints. The implementation is based on (van de Laar et al., 2021, \"Chance-constrained active inference\") and discussion with John Boik.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a 1-D agent that tries to elevate itself above ground level. Instead of a goal prior, we impose a chance constraint on future states, such that the agent prefers to avoid the ground with a preset probability (chance) level. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"using Plots, Distributions, StatsFuns, RxInfer","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Chance-Constraint-Node-Definition","page":"Chance-Constrained Active Inference","title":"Chance-Constraint Node Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"A chance-constraint is meant to constraint a marginal distribution to abide by certain properties. In this case, a (posterior) probability distribution should not \"overflow\" a given region by more than a certain probability mass. This constraint then affects adjacent beliefs and ultimately the controls to (hopefully) account for the imposed constraint.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"In order to enforce this constraint on a marginal distribution, an auxiliary chance-constraint node is included in the graphical model. This node then sends messages that enforce the marginal to abide by the preset conditions. In other words, the (chance) constraint on the (posterior) marginal, is converted to a prior constraint on the generative model that sends an adaptive message. We start by defining this chance-constraint node and its message.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"struct ChanceConstraint end \n\n# Node definition with safe region limits (lo, hi), overflow chance epsilon and tolerance atol\n@node ChanceConstraint Stochastic [out, lo, hi, epsilon, atol]","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Function to compute normalizing constant and central moments of a truncated Gaussian distribution\nfunction truncatedGaussianMoments(m::Float64, V::Float64, a::Float64, b::Float64)\n V = clamp(V, tiny, huge)\n StdG = Distributions.Normal(m, sqrt(V))\n TrG = Distributions.Truncated(StdG, a, b)\n \n Z = Distributions.cdf(StdG, b) - Distributions.cdf(StdG, a) # safe mass for standard Gaussian\n \n if Z < tiny\n # Invalid region; return undefined mean and variance of truncated distribution\n Z = 0.0\n m_tr = 0.0\n V_tr = 0.0\n else\n m_tr = Distributions.mean(TrG)\n V_tr = Distributions.var(TrG)\n end\n \n return (Z, m_tr, V_tr)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@rule ChanceConstraint(:out, Marginalisation) (\n m_out::UnivariateNormalDistributionsFamily, # Require inbound message\n q_lo::PointMass, \n q_hi::PointMass, \n q_epsilon::PointMass, \n q_atol::PointMass) = begin \n\n # Extract parameters\n lo = mean(q_lo)\n hi = mean(q_hi)\n epsilon = mean(q_epsilon)\n atol = mean(q_atol)\n \n (m_bw, V_bw) = mean_var(m_out)\n (xi_bw, W_bw) = (m_bw, 1. /V_bw) # check division by zero\n (m_tilde, V_tilde) = (m_bw, V_bw)\n \n # Compute statistics (and normalizing constant) of q in safe region G\n # Phi_G is called the \"safe mass\" \n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_bw, V_bw, lo, hi)\n\n xi_fw = xi_bw\n W_fw = W_bw\n if epsilon <= 1.0 - Phi_G # If constraint is active\n # Initialize statistics of uncorrected belief\n m_tilde = m_bw\n V_tilde = V_bw\n for i = 1:100 # Iterate at most this many times\n (Phi_lG, m_lG, V_lG) = truncatedGaussianMoments(m_tilde, V_tilde, -Inf, lo) # Statistics for q in region left of G\n (Phi_rG, m_rG, V_rG) = truncatedGaussianMoments(m_tilde, V_tilde, hi, Inf) # Statistics for q in region right of G\n\n # Compute moments of non-G region as a mixture of left and right truncations\n Phi_nG = Phi_lG + Phi_rG\n m_nG = Phi_lG / Phi_nG * m_lG + Phi_rG / Phi_nG * m_rG\n V_nG = Phi_lG / Phi_nG * (V_lG + m_lG^2) + Phi_rG/Phi_nG * (V_rG + m_rG^2) - m_nG^2\n\n # Compute moments of corrected belief as a mixture of G and non-G regions\n m_tilde = (1.0 - epsilon) * m_G + epsilon * m_nG\n V_tilde = (1.0 - epsilon) * (V_G + m_G^2) + epsilon * (V_nG + m_nG^2) - m_tilde^2\n # Re-compute statistics (and normalizing constant) of corrected belief\n (Phi_G, m_G, V_G) = truncatedGaussianMoments(m_tilde, V_tilde, lo, hi)\n if (1.0 - Phi_G) < (1.0 + atol)*epsilon\n break # Break the loop if the belief is sufficiently corrected\n end\n end\n \n # Convert moments of corrected belief to canonical form\n W_tilde = inv(V_tilde)\n xi_tilde = W_tilde * m_tilde\n\n # Compute canonical parameters of forward message\n xi_fw = xi_tilde - xi_bw\n W_fw = W_tilde - W_bw\n end\n\n return NormalWeightedMeanPrecision(xi_fw, W_fw)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Definition-of-the-Environment","page":"Chance-Constrained Active Inference","title":"Definition of the Environment","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider an environment where the agent has an elevation level, and where the agent directly controls its vertical velocity. After some time, an unexpected and sudden gust of wind tries to push the agent to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"wind(t::Int64) = -0.1*(60 <= t < 100) # Time-dependent wind profile\n\nfunction initializeWorld()\n x_0 = 0.0 # Initial elevation\n \n x_t_last = x_0\n function execute(t::Int64, a_t::Float64)\n x_t = x_t_last + a_t + wind(t) # Update elevation\n \n x_t_last = x_t # Reset state\n \n return x_t\n end\n\n x_t = x_0 # Predefine outcome variable\n observe() = x_t # State is fully observed\n\n return (execute, observe)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Generative-Model-for-Regulator","page":"Chance-Constrained Active Inference","title":"Generative Model for Regulator","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"We consider a fully observed Markov decision process, where the agent directly observes the true state (elevation) of the world. In this case we only need to define a chance-constrained generative model of future states. Inference for controls on this model then derives our controller.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"@model function regulator_model(; T, lo, hi, epsilon, atol)\n # Fully observed state\n x_t = datavar(Float64)\n\n # Control prior statistics\n m_u = datavar(Float64, T)\n v_u = datavar(Float64, T) \n \n # Random variables\n u = randomvar(T) # Control\n x = randomvar(T) # Elevation\n \n # Loop over horizon\n x_k_last = x_t\n for k = 1:T\n u[k] ~ NormalMeanVariance(m_u[k], v_u[k]) # Control prior\n x[k] ~ x_k_last + u[k] # Transition model\n x[k] ~ ChanceConstraint(lo, hi, epsilon, atol) where { # Simultaneous constraint on state\n pipeline = RequireMessage(out = NormalWeightedMeanPrecision(0, 0.01))} # Predefine inbound message to break circular dependency\n x_k_last = x[k]\n end\n \n return (u, x)\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Reactive-Agent-Definition","page":"Chance-Constrained Active Inference","title":"Reactive Agent Definition","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"function initializeAgent()\n # Set control prior statistics\n m_u = zeros(T)\n v_u = lambda^(-1)*ones(T)\n \n function compute(x_t::Float64)\n model_t = regulator_model(; T=T, lo=lo, hi=hi, epsilon=epsilon, atol=atol)\n data_t = (m_u = m_u, v_u = v_u, x_t = x_t)\n \n result = infer(\n model = model_t, \n data = data_t,\n iterations = n_its)\n\n # Extract policy from inference results\n pol = mode.(result.posteriors[:u][end])\n\n return pol\n end\n\n pol = zeros(T) # Predefine policy variable\n act() = pol[1]\n\n return (compute, act)\nend;","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Action-Perception-Cycle","page":"Chance-Constrained Active Inference","title":"Action-Perception Cycle","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Next we define and execute the action-perception cycle. Because the state is fully observed, these is no slide (estimator) step in the cycle. ","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"# Simulation parameters\nN = 160 # Total simulation time\nT = 1 # Lookahead time horizon\nlambda = 1.0 # Control prior precision\nlo = 1.0 # Chance region lower bound\nhi = Inf # Chance region upper bound\nepsilon = 0.01 # Allowed chance violation\natol = 0.01 # Convergence tolerance for chance constraints\nn_its = 10; # Number of inference iterations","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(execute, observe) = initializeWorld() # Let there be a world\n(compute, act) = initializeAgent() # Let there be an agent\n\na = Vector{Float64}(undef, N) # Actions\nx = Vector{Float64}(undef, N) # States\nfor t = 1:N\n a[t] = act()\n execute(t, a[t])\n x[t] = observe()\n compute(x[t])\nend","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/#Results","page":"Chance-Constrained Active Inference","title":"Results","text":"","category":"section"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"Results show that the agent does not allow the wind to push it all the way to the ground.","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"p1 = plot(1:N, wind.(1:N), color=\"blue\", label=\"Wind\", ylabel=\"Velocity\", lw=2)\nplot!(p1, 1:N, a, color=\"red\", label=\"Control\", lw=2)\np2 = plot(1:N, x, color=\"black\", lw=2, label=\"Agent\", ylabel=\"Elevation\")\nplot(p1, p2, layout=(2,1))","category":"page"},{"location":"examples/advanced_examples/Chance Constraints/","page":"Chance-Constrained Active Inference","title":"Chance-Constrained Active Inference","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#examples-gamma-mixture-model","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"This notebook implements one of the experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/.","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Load-packages","page":"Gamma Mixture Model","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"using RxInfer, Random, StatsPlots","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# create custom structure for model parameters for simplicity\nstruct GammaMixtureModelParameters\n nmixtures # number of mixtures\n priors_as # tuple of priors for variable a\n priors_bs # tuple of priors for variable b\n prior_s # prior of variable s\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/#Model-specification","page":"Gamma Mixture Model","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"@model function gamma_mixture_model(nobservations, parameters::GammaMixtureModelParameters)\n\n # fetch information from struct\n nmixtures = parameters.nmixtures\n priors_as = parameters.priors_as\n priors_bs = parameters.priors_bs\n prior_s = parameters.prior_s\n\n # set prior on global selection variable\n s ~ Dirichlet(probvec(prior_s))\n\n # allocate vectors of random variables\n as = randomvar(nmixtures)\n bs = randomvar(nmixtures)\n\n # set priors on variables of mixtures\n for i in 1:nmixtures\n as[i] ~ Gamma(shape = shape(priors_as[i]), rate = rate(priors_as[i]))\n bs[i] ~ Gamma(shape = shape(priors_bs[i]), rate = rate(priors_bs[i]))\n end\n\n # introduce random variables for local selection variables and data\n z = randomvar(nobservations)\n y = datavar(Float64, nobservations)\n\n # convert vector to tuples for proper functioning of GammaMixture node\n tas = tuple(as...)\n tbs = tuple(bs...)\n\n # specify local selection variable and data generating process\n for i in 1:nobservations\n z[i] ~ Categorical(s)\n y[i] ~ GammaMixture(z[i], tas, tbs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"constraints = @constraints begin \n\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n\n q(as) = q(as[begin])..q(as[end])\n q(bs) = q(bs[begin])..q(bs[end])\n \n q(as) :: PointMass(starting_point = (args...) -> [ 1.0 ])\nend","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Constraints:\n marginals form:\n q(as) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(z, as, bs, s) = q(z)q(as)q(bs)q(s)\n q(as) = q(as[(begin)..(end)])\n q(bs) = q(bs[(begin)..(end)])\nOptions:\n warn = true","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify seed and number of data points\nrng = MersenneTwister(43)\nn_samples = 2500\n\n# specify parameters of mixture model that generates the data\n# Note that mixture components have exactly the same means\nmixtures = [ Gamma(9.0, inv(27.0)), Gamma(90.0, inv(270.0)) ]\nnmixtures = length(mixtures)\nmixing = rand(rng, nmixtures)\nmixing = mixing ./ sum(mixing)\nmixture = MixtureModel(mixtures, mixing)\n\n# generate data set\ndataset = rand(rng, mixture, n_samples);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# specify priors of probabilistic model\n# NOTE: As the means of the mixtures \"collide\", we specify informative prior for selector variable\nnmixtures = 2\ngpriors = GammaMixtureModelParameters(\n nmixtures, # number of mixtures\n [ Gamma(1.0, 0.1), Gamma(1.0, 1.0) ], # priors on variables a\n [ GammaShapeRate(10.0, 2.0), GammaShapeRate(1.0, 3.0) ], # priors on variables b\n Dirichlet(1e3*mixing) # prior on variable s\n)\n\ngmodel = gamma_mixture_model(length(dataset), gpriors)\ngdata = (y = dataset, )\nginitmarginals = (s = gpriors.prior_s, z = vague(Categorical, gpriors.nmixtures), bs = GammaShapeRate(1.0, 1.0))\ngreturnvars = (s = KeepLast(), z = KeepLast(), as = KeepEach(), bs = KeepEach())\n\ngoptions = (\n \n default_factorisation = MeanField() # Mixture models require Mean-Field assumption currently\n)\n\ngresult = infer(\n model = gmodel, \n data = gdata,\n constraints = constraints,\n options = (limit_stack_depth = 100,),\n initmarginals = ginitmarginals,\n returnvars = greturnvars,\n free_energy = true,\n iterations = 250, \n showprogress = true\n);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# extract inferred parameters\n_as, _bs = mean.(gresult.posteriors[:as][end]), mean.(gresult.posteriors[:bs][end])\n_dists = map(g -> Gamma(g[1], inv(g[2])), zip(_as, _bs))\n_mixing = mean(gresult.posteriors[:s])\n\n# create model from inferred parameters\n_mixture = MixtureModel(_dists, _mixing);","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# report on outcome of inference\nprintln(\"Generated means: $(mean(mixtures[1])) and $(mean(mixtures[2]))\")\nprintln(\"Inferred means: $(mean(_dists[1])) and $(mean(_dists[2]))\")\nprintln(\"========\")\nprintln(\"Generated mixing: $(mixing)\")\nprintln(\"Inferred mixing: $(_mixing)\")","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"Generated means: 0.3333333333333333 and 0.33333333333333337\nInferred means: 0.33822470398804994 and 0.33305534672666653\n========\nGenerated mixing: [0.18923488676601088, 0.8107651132339891]\nInferred mixing: [0.11395888467453213, 0.8860411153254679]","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"# plot results\np1 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np1 = plot!(mixture, label=false, title=\"Generated mixtures\", linewidth=3.0)\n\np2 = histogram(dataset, ylim = (0, 13), xlim = (0, 1), normalize=:pdf, label=\"data\", opacity=0.3)\np2 = plot!(_mixture, label=false, title=\"Inferred mixtures\", linewidth=3.0)\n\n# evaluate the convergence of the algorithm by monitoring the BFE\np3 = plot(gresult.free_energy, label=false, xlabel=\"iterations\", title=\"Bethe FE\")\n\nplot(plot(p1, p2, layout = @layout([ a; b ])), plot(p3), layout = @layout([ a b ]), size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gamma Mixture/","page":"Gamma Mixture Model","title":"Gamma Mixture Model","text":"","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#examples-gaussian-mixture","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"This notebook illustrates how to use the NormalMixture node in RxInfer.jl for both univariate and multivariate observations.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Load-packages","page":"Gaussian Mixture","title":"Load packages","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"using RxInfer, Plots, Random, LinearAlgebra, StableRNGs, LaTeXStrings","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Univariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Univariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Consider the data set of length N observed below.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_univariate_data(nr_samples; rng = MersenneTwister(123))\n\n # data generating parameters\n class = [1/3, 2/3]\n mean1, mean2 = -10, 10\n precision = 1.777\n\n # generate data\n z = rand(rng, Categorical(class), nr_samples)\n y = zeros(nr_samples)\n for k in 1:nr_samples\n y[k] = rand(rng, Normal(z[k] == 1 ? mean1 : mean2, 1/sqrt(precision)))\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_univariate = generate_univariate_data(100)\nhistogram(data_univariate, bins=50, label=\"data\", normed=true)\nxlims!(minimum(data_univariate), maximum(data_univariate))\nylims!(0, Inf)\nylabel!(\"relative occurrence [%]\")\nxlabel!(\"y\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m w z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(w_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmBeta(s mid alpha_s beta_s) \n p(m_k) = mathcalN(m_k mid mu_k sigma_k^2) p(w_k) = Gamma(w_k mid alpha_k beta_k) \n p(z_n mid s) = mathrmBer(z_n mid s) \n p(y_n mid m w z_n) = prod_k=1^K mathcalNleft(y_n mid m_k w_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions w = w_1 w_2 ldots w_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Here we implement the following model with uninformative values for the hyperparameters as","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function univariate_gaussian_mixture_model(nr_samples)\n \n s ~ Beta(1.0, 1.0)\n \n m1 ~ Normal(mean = -2.0, var = 1e3)\n w1 ~ Gamma(shape = 0.01, rate = 0.01)\n \n m2 ~ Normal(mean = 2.0, var = 1e3)\n w2 ~ Gamma(shape = 0.01, rate = 0.01)\n \n z = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n \n for n in 1:nr_samples\n z[n] ~ Bernoulli(s)\n y[n] ~ NormalMixture(z[n], (m1, m2), (w1, w2))\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m w mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m w mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(w_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmBeta(s mid hatalpha_s hatbeta_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatsigma^2_k) \n q(w_k) = Gamma (w_k mid hatalpha_k hatbeta_k) \n q(z_n) = mathrmBer(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"results_univariate = infer(\n model = univariate_gaussian_mixture_model(length(data_univariate)), \n constraints = MeanField(),\n data = (y = data_univariate,), \n initmarginals = (\n s = vague(Beta), \n m1 = NormalMeanVariance(-2.0, 1e3), \n m2 = NormalMeanVariance(2.0, 1e3), \n w1 = vague(GammaShapeRate), \n w2 = vague(GammaShapeRate)\n ), \n iterations = 10, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m2, m1, s, w2, w1, z)\n Free Energy: | Real[360.857, 226.858, 161.566, 135.301, 135.277, 135.\n277, 135.277, 135.277, 135.277, 135.277]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen as a function of the iterations","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"mp = plot(mean.(results_univariate.posteriors[:m1]), ribbon = std.(results_univariate.posteriors[:m1]) .|> sqrt, label = L\"posterior $m_1$\")\nmp = plot!(mean.(results_univariate.posteriors[:m2]), ribbon = std.(results_univariate.posteriors[:m2]) .|> sqrt, label = L\"posterior $m_2$\")\nmp = plot!(mp, [ -10 ], seriestype = :hline, label = L\"true $m_1$\")\nmp = plot!(mp, [ 10 ], seriestype = :hline, label = L\"true $m_2$\")\n\nwp = plot(mean.(results_univariate.posteriors[:w1]), ribbon = std.(results_univariate.posteriors[:w1]) .|> sqrt, label = L\"posterior $w_1$\", legend = :bottomright, ylim = (-1, 3))\nwp = plot!(wp, mean.(results_univariate.posteriors[:w2]), ribbon = std.(results_univariate.posteriors[:w2]) .|> sqrt, label = L\"posterior $w_2$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_1$\")\nwp = plot!(wp, [ 1.777 ], seriestype = :hline, label = L\"true $w_2$\")\n\nswp = plot(mean.(results_univariate.posteriors[:s]), ribbon = std.(results_univariate.posteriors[:s]) .|> sqrt, label = L\"posterior $s$\")\nswp = plot!(swp, [ 2/3 ], seriestype = :hline, label = L\"true $s$\")\n\nfep = plot(results_univariate.free_energy, label = \"Free Energy\", legend = :topright)\n\nplot(mp, wp, swp, fep, layout = @layout([ a b; c d ]), size = (800, 400))\nxlabel!(\"iteration\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Multivariate-Gaussian-Mixture-Model","page":"Gaussian Mixture","title":"Multivariate Gaussian Mixture Model","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The above example can also be extended to the multivariate case. Consider the data set below","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"function generate_multivariate_data(nr_samples; rng = MersenneTwister(123))\n\n L = 50.0\n nr_mixtures = 6\n\n probvec = normalize!(ones(nr_mixtures), 1)\n\n switch = Categorical(probvec)\n\n gaussians = map(1:nr_mixtures) do index\n angle = 2π / nr_mixtures * (index - 1)\n basis_v = L * [ 1.0, 0.0 ]\n R = [ cos(angle) -sin(angle); sin(angle) cos(angle) ]\n mean = R * basis_v \n covariance = Matrix(Hermitian(R * [ 10.0 0.0; 0.0 20.0 ] * transpose(R)))\n return MvNormal(mean, covariance)\n end\n\n z = rand(rng, switch, nr_samples)\n y = Vector{Vector{Float64}}(undef, nr_samples)\n\n for n in 1:nr_samples\n y[n] = rand(rng, gaussians[z[n]])\n end\n\n return y\n\nend;","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"data_multivariate = generate_multivariate_data(500)\n\nsdim(n) = (a) -> map(d -> d[n], a) # helper function\nscatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, size = (600, 400), legend=false)\nxlabel!(L\"y_1\")\nylabel!(L\"y_2\")","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Model-specification-2","page":"Gaussian Mixture","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The goal here is to create a model for the data set above. In this case a Gaussian mixture model with K components seems to suite the situation well. We specify the factorized model as p(y z s m w) = prod_n=1^N bigg(p(y_n mid m W z_n) p(z_n mid s) bigg)prod_k=1^K bigg(p(m_k) p(W_k) bigg) p(s) where the individual terms are specified as beginaligned p(s) = mathrmDir(s mid alpha_s) \n p(m_k) = mathcalN(m_k mid mu_k Sigma_k) p(W_k) = mathcalW(W_k mid V_k nu_k) \n p(z_n mid s) = mathrmCat(z_n mid s) \n p(y_n mid m W z_n) = prod_k=1^K mathcalNleft(y_n mid m_k W_kright)^z_nk endaligned","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"The set of observations y = y_1 y_2 ldots y_N is modeled by a mixture of Gaussian distributions, parameterized by means m = m_1 m_2 ldots m_K and precisions W = W_1 W_2 ldots W_K, where k denotes the component index. This component is selected per observation by the indicator variable z_n, which is a one-of-K encoded vector satisfying sum_k=1^K z_nk = 1 and z_nk in 0 1 forall k. We put a hyperprior on these variables, termed s, which represents the relative occurrence of the different realizations of z_n.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"@model function multivariate_gaussian_mixture_model(nr_mixtures, nr_samples, priors_mean, priors_cov)\n \n z = randomvar(nr_samples)\n m = randomvar(nr_mixtures)\n w = randomvar(nr_mixtures)\n y = datavar(Vector{Float64}, nr_samples)\n \n for k in 1:nr_mixtures \n m[k] ~ MvNormal(μ = priors_mean[k], Σ = priors_cov[k])\n w[k] ~ Wishart(3, 1e2*diagm(ones(2)))\n end\n \n s ~ Dirichlet(ones(nr_mixtures))\n \n means = tuple(m...)\n precs = tuple(w...)\n \n for n in 1:nr_samples\n z[n] ~ Categorical(s) \n y[n] ~ NormalMixture(z[n], means, precs)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Probabilistic-inference-2","page":"Gaussian Mixture","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"In order to fit the model to the data, we are interested in computing the posterior distribution p(z s m W mid y) However, computation of this term is intractable. Therefore, it is approximated by a naive mean-field approximation, specified as p(z s m W mid y) approx prod_n=1^N q(z_n) prod_k=1^K bigg(q(m_k) q(W_k)bigg) q(s) with the functional forms beginaligned q(s) = mathrmDir(s mid hatalpha_s) \n q(m_k) = mathcalN(m_k mid hatmu_k hatSigma_k) \n q(w_k) = mathcalW(W_k mid hatV_k hatnu_k) \n q(z_n) = mathrmCat(z_n mid hatp_n) endaligned In order to get the inference procedure started, these marginal distribution need to be initialized.","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"rng = MersenneTwister(121)\nm = [[cos(k*2π/6), sin(k*2π/6)] for k in 1:6]\nresults_multivariate = infer(\n model = multivariate_gaussian_mixture_model(\n 6, \n length(data_multivariate), \n m,\n [diagm(1e2 * ones(2)) for k in 1:6]\n ), \n data = (y = data_multivariate,), \n constraints = MeanField(),\n initmarginals = (\n s = vague(Dirichlet, 6), \n m = [MvNormalMeanCovariance(m[k], diagm(1e2 * ones(2))) for k in 1:6], \n w = Wishart(3, diagm(1e2 * ones(2)))\n ), \n iterations = 50, \n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Inference results:\n Posteriors | available for (m, w, s, z)\n Free Energy: | Real[4166.93, 4025.27, 3908.18, 3894.5, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49 … 3894.49, 3894.49, 3894.49, 3894.\n49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49, 3894.49]","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/#Results-2","page":"Gaussian Mixture","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"Below the inference results can be seen","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"p_data = scatter(data_multivariate |> sdim(1), data_multivariate |> sdim(2), ms = 2, alpha = 0.4, legend=false, title=\"Data\", xlims=(-75, 75), ylims=(-75, 75))\np_result = plot(xlims = (-75, 75), ylims = (-75, 75), title=\"Inference result\", legend=false, colorbar = false)\nfor (e_m, e_w) in zip(results_multivariate.posteriors[:m][end], results_multivariate.posteriors[:w][end])\n gaussian = MvNormal(mean(e_m), Matrix(Hermitian(mean(inv, e_w))))\n global p_result = contour!(p_result, range(-75, 75, step = 0.25), range(-75, 75, step = 0.25), (x, y) -> pdf(gaussian, [ x, y ]), title=\"Inference result\", legend=false, levels = 7, colorbar = false)\nend\np_fe = plot(results_multivariate.free_energy, label = \"Free Energy\")\n\nplot(p_data, p_result, p_fe, layout = @layout([ a b; c ]))","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Gaussian Mixture/","page":"Gaussian Mixture","title":"Gaussian Mixture","text":"","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#examples-kalman-filtering-and-smoothing","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In the following set of examples the goal is to estimate hidden states of a Dynamical process where all hidden states are Gaussians.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We start our journey with a simple multivariate Linear Gaussian State Space Model (LGSSM), which can be solved analytically.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We then solve an identification problem which does not have an analytical solution.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Utimately, we show how RxInfer.jl can deal with missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Gaussian-Linear-Dynamical-System","page":"Kalman filtering and smoothing","title":"Gaussian Linear Dynamical System","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"LGSSM can be described with the following equations:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n p(x_ix_i - 1) = mathcalN(x_iA * x_i - 1 mathcalP)\n p(y_ix_i) = mathcalN(y_iB * x_i mathcalQ)\nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"where x_i are hidden states, y_i are noisy observations, A, B are state transition and observational matrices, mathcalP and mathcalQ are state transition noise and observation noise covariance matrices. For a more rigorous introduction to Linear Gaussian Dynamical systems we refer to Simo Sarkka, Bayesian Filtering and Smoothing book.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, BenchmarkTools, Random, LinearAlgebra, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(rng, A, B, Q, P)\n x_prev = [ 10.0, -10.0 ]\n\n x = Vector{Vector{Float64}}(undef, n)\n y = Vector{Vector{Float64}}(undef, n)\n\n for i in 1:n\n x[i] = rand(rng, MvNormal(A * x_prev, Q))\n y[i] = rand(rng, MvNormal(B * x[i], P))\n x_prev = x[i]\n end\n \n return x, y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Seed for reproducibility\nseed = 1234\n\nrng = MersenneTwister(1234)\n\n# We will model 2-dimensional observations with rotation matrix `A`\n# To avoid clutter we also assume that matrices `A`, `B`, `P` and `Q`\n# are known and fixed for all time-steps\nθ = π / 35\nA = [ cos(θ) -sin(θ); sin(θ) cos(θ) ]\nB = diageye(2)\nQ = diageye(2)\nP = 25.0 .* diageye(2)\n\n# Number of observations\nn = 300;","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x, y = generate_data(rng, A, B, Q, P);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations, which are represented as dots.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = scatter!(px, getindex.(y, 1), label = false, markersize = 2, color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\npx = scatter!(px, getindex.(y, 2), label = false, markersize = 2, color = :green)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To create a model we use GraphPPL package and @model macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rotate_ssm(n, x0, A, B, Q, P)\n \n # We create constvar references for better efficiency\n cA = constvar(A)\n cB = constvar(B)\n cQ = constvar(Q)\n cP = constvar(P)\n \n # `x` is a sequence of hidden states\n x = randomvar(n)\n # `y` is a sequence of \"clamped\" observations\n y = datavar(Vector{Float64}, n)\n \n x_prior ~ MvNormalMeanCovariance(mean(x0), cov(x0))\n x_prev = x_prior\n \n for i in 1:n\n x[i] ~ MvNormalMeanCovariance(cA * x_prev, cQ)\n y[i] ~ MvNormalMeanCovariance(cB * x[i], cP)\n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference we also specify prior for out first hidden state:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0 = MvNormalMeanCovariance(zeros(2), 100.0 * diageye(2));","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# For large number of observations you need to use `limit_stack_depth = 100` option during model creation, e.g. \n# infer(..., options = (limit_stack_depth = 500, ))`\nresult = infer(\n model = rotate_ssm(length(y), x0, A, B, Q, P), \n data = (y = y,),\n free_energy = true\n);\n\nxmarginals = result.posteriors[:x]\nlogevidence = -result.free_energy; # given the analytical solution, free energy will be equal to the negative log evidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px = plot()\n\npx = plot!(px, getindex.(x, 1), label = \"Hidden Signal (dim-1)\", color = :orange)\npx = plot!(px, getindex.(x, 2), label = \"Hidden Signal (dim-2)\", color = :green)\n\npx = plot!(px, getindex.(mean.(xmarginals), 1), ribbon = getindex.(var.(xmarginals), 1) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :teal)\npx = plot!(px, getindex.(mean.(xmarginals), 2), ribbon = getindex.(var.(xmarginals), 2) .|> sqrt, fillalpha = 0.5, label = \"Estimated Signal (dim-1)\", color = :violet)\n\nplot(px)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the value for minus log evidence:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"logevidence","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"1-element Vector{Float64}:\n -1882.2434870099778","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We may be also interested in performance of our resulting Belief Propagation algorithm:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@benchmark infer(\n model = rotate_ssm(length($y), $x0, $A, $B, $Q, $P), \n data = (y = $y,)\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"BenchmarkTools.Trial: 138 samples with 1 evaluation.\n Range (min … max): 27.959 ms … 101.209 ms ┊ GC (min … max): 0.00% … 0.00\n%\n Time (median): 32.419 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 36.402 ms ± 10.555 ms ┊ GC (mean ± σ): 5.16% ± 9.59\n%\n\n █▆ \n ▃▁▅██▇▅▁▁▁▃▃▃▄▃▁▃▃▃▂▃▁▁▁▁▁▂▁▁▁▁▂▁▂▁▁▁▁▁▁▁▁▁▂▁▁▁▂▁▁▁▁▁▁▁▁▁▁▁▂ ▂\n 28 ms Histogram: frequency by time 89.5 ms <\n\n Memory estimate: 9.73 MiB, allocs estimate: 226250.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#System-Identification-Problem","page":"Kalman filtering and smoothing","title":"System Identification Problem","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we are going to attempt to run Bayesian inference and decouple two random-walk signals, which were combined into a single single through some deterministic function f. We do not have access to the real values of these signals, but only to their combination. First, we create the generate_data function that accepts f as an argument:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Distributions, StableRNGs, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"function generate_data(f, n; seed = 123, x_i_min = -20.0, w_i_min = 20.0, noise = 20.0, real_x_τ = 0.1, real_w_τ = 1.0)\n\n rng = StableRNG(seed)\n\n real_x = Vector{Float64}(undef, n)\n real_w = Vector{Float64}(undef, n)\n real_y = Vector{Float64}(undef, n)\n\n for i in 1:n\n real_x[i] = rand(rng, Normal(x_i_min, sqrt(1.0 / real_x_τ)))\n real_w[i] = rand(rng, Normal(w_i_min, sqrt(1.0 / real_w_τ)))\n real_y[i] = rand(rng, Normal(f(real_x[i], real_w[i]), sqrt(noise)))\n\n x_i_min = real_x[i]\n w_i_min = real_w[i]\n end\n \n return real_x, real_w, real_y\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"generate_data (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The function returns the real signals real_x and real_w for later comparison (we are not going to use them during inference) and their combined version real_y (we are going to use it as our observations during the inference). We also assume that real_y is corrupted with some measurement noise.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-1:-y-x-w","page":"Kalman filtering and smoothing","title":"Combination 1: y = x + w","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In our first example, we are going to use a simple addition (+) as the function f. In general, it is impossible to decouple the signals x and w without strong priors, but we can try and see how good an inference can be. The + operation on two random variables also has a special meaning in the probabilistic inference, namely the convolution of pdf's of the two random variables, and RxInfer treats it specially with many precomputed analytical rules, which may make the inference task easier. First, let us create a test dataset:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 250\nreal_x, real_w, real_y = generate_data(+, n);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, real_x, label = \"x\")\npl = plot!(pl, real_w, label = \"w\")\n\npr = plot(title = \"Combined y = x + w\")\npr = scatter!(pr, real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"To run inference, we need to create a probabilistic model: our beliefs about how our data could have been generated. For this we can use the @model macro from RxInfer.jl:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function identification_problem(f, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x = randomvar(n)\n w = randomvar(n)\n s = randomvar(n)\n y = datavar(Float64, n)\n \n x_i_min = x0\n w_i_min = w0\n \n for i in 1:n\n x[i] ~ Normal(mean = x_i_min, precision = τ_x)\n w[i] ~ Normal(mean = w_i_min, precision = τ_w)\n s[i] ~ f(x[i], w[i])\n y[i] ~ Normal(mean = s[i], precision = τ_y)\n \n x_i_min = x[i]\n w_i_min = w[i]\n end\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer runs Bayesian inference as a variational optimisation procedure between the real solution and its variational proxy q. In our model specification we assumed noise components to be unknown, thus, we need to enforce a structured mean-field assumption for the variational family of distributions q. This inevitably reduces the accuracy of the result, but makes the task easier and allows for fast and analytical message passing-based variational inference:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin \n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, w0, x, w, τ_x, τ_w, τ_y, s) = q(x, x0, w, w0, s)q(τ_w)q(τ_x)q(τ_y\n)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The next step is to assign priors, initialise needed messages and marginals and call the inference function:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"m_x_0, τ_x_0 = -20.0, 1.0\nm_w_0, τ_w_0 = 20.0, 1.0\n\n# We set relatively strong priors for random walk noise components\n# and sort of vague prior for the noise of the observations\na_x, b_x = 0.01, 0.01var(real_x)\na_w, b_w = 0.01, 0.01var(real_w)\na_y, b_y = 1.0, 1.0\n\n# We set relatively strong priors for messages\nxinit = map(r -> NormalMeanPrecision(r, τ_x_0), reverse(range(-60, -20, length = n)))\nwinit = map(r -> NormalMeanPrecision(r, τ_w_0), range(20, 60, length = n))\n\nimessages = (x = xinit, w = winit)\nimarginals = (τ_x = GammaShapeRate(a_x, b_x), τ_w = GammaShapeRate(a_w, b_w), τ_y = GammaShapeRate(a_y, b_y))\n\nresult = infer(\n model = identification_problem(+, n, m_x_0, τ_x_0, a_x, b_x, m_w_0, τ_w_0, a_w, b_w, a_y, b_y),\n data = (y = real_y,), \n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = imessages, \n initmarginals = imarginals, \n iterations = 50\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let's examine our inference results:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"τ_x_marginals = result.posteriors[:τ_x]\nτ_w_marginals = result.posteriors[:τ_w]\nτ_y_marginals = result.posteriors[:τ_y]\n\nsmarginals = result.posteriors[:s]\nxmarginals = result.posteriors[:x]\nwmarginals = result.posteriors[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(xmarginals[end]), ribbon = var.(xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(wmarginals[end]), ribbon = var.(wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(smarginals[end]), ribbon = std.(smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The inference results are not so bad, even though RxInfer missed the correct values of the signals between 100 and 150.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Combination-2:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Combination 2: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"In this example we use a slightly more complex function, for which RxInfer does not have precomputed analytical message update rules. We are going to attempt to run Bayesian inference with min as a combination function. Note, however, that directly using min may cause problems for the built-in approximation methods as it has zero partial derviates with respect to all but one of the variables. We generate data with the min function directly however we model it with a somewhat smoothed version:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"# Smoothed version of `min` without zero-ed derivatives\nfunction smooth_min(x, y) \n if x < y\n return x + 1e-4 * y\n else\n return y + 1e-4 * x\n end\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"smooth_min (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInfer supports arbitrary nonlinear functions, but it requires an explicit approximation method specification. That can be achieved with the built-in @meta macro:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_meta = @meta begin \n # In this example we are going to use a simple `Linearization` method\n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 200\nmin_real_x, min_real_w, min_real_y = generate_data(min, n, seed = 1, x_i_min = 0.0, w_i_min = 0.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, min_real_x, label = \"x\")\npl = plot!(pl, min_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, min_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_m_x_0, min_τ_x_0 = -1.0, 1.0\nmin_m_w_0, min_τ_w_0 = 1.0, 1.0\n\nmin_a_x, min_b_x = 1.0, 1.0\nmin_a_w, min_b_w = 1.0, 1.0\nmin_a_y, min_b_y = 1.0, 1.0\n\nmin_imessages = (x = NormalMeanPrecision(min_m_x_0, min_τ_x_0), w = NormalMeanPrecision(min_m_w_0, min_τ_w_0))\nmin_imarginals = (τ_x = GammaShapeRate(min_a_x, min_b_x), τ_w = GammaShapeRate(min_a_w, min_b_w), τ_y = GammaShapeRate(min_a_y, min_b_y))\n\nmin_result = infer(\n model = identification_problem(smooth_min, n, min_m_x_0, min_τ_x_0, min_a_x, min_b_x, min_m_w_0, min_τ_w_0, min_a_w, min_b_w, min_a_y, min_b_y),\n data = (y = min_real_y,), \n meta = min_meta,\n options = (limit_stack_depth = 500, ), \n constraints = constraints, \n initmessages = min_imessages, \n initmarginals = min_imarginals, \n iterations = 100\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Inference results:\n Posteriors | available for (w0, w, x0, s, τ_x, τ_w, τ_y, x)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"min_τ_x_marginals = min_result.posteriors[:τ_x]\nmin_τ_w_marginals = min_result.posteriors[:τ_w]\nmin_τ_y_marginals = min_result.posteriors[:τ_y]\n\nmin_smarginals = min_result.posteriors[:s]\nmin_xmarginals = min_result.posteriors[:x]\nmin_wmarginals = min_result.posteriors[:w]\n\npx1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, min_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(min_xmarginals[end]), ribbon = var.(min_xmarginals[end]), label = \"Estimated X\")\n\npx1 = plot!(px1, min_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(min_wmarginals[end]), ribbon = var.(min_wmarginals[end]), label = \"Estimated W\")\n\npx2 = scatter!(px2, min_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(min_smarginals[end]), ribbon = std.(min_smarginals[end]), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As we can see inference with the min function is significantly harder. Even though the combined signal has been inferred with high precision the underlying x and w signals are barely inferred. This may be expected, since the min function essentially destroy the information about one of the signals, thus, making it impossible to decouple two seemingly identical random walk signals. The only one inferred signal is the one which is lower and we have no inference information about the signal which is above. It might be possible to infer the states, however, with more informative priors and structural information about two different signals (e.g. if these are not random walks). ","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Online-(filtering)-identification:-y-min(x,-w)","page":"Kalman filtering and smoothing","title":"Online (filtering) identification: y = min(x, w)","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Another way to approach to this problem is to use online (filtering) inference procedure from RxInfer, but for that we also need to modify our model specification a bit:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function rx_identification(f)\n \n # We are going to continuosly update our priors\n # based on new posteriors\n m_x_0 = datavar(Float64) \n τ_x_0 = datavar(Float64)\n m_w_0 = datavar(Float64) \n τ_w_0 = datavar(Float64)\n a_x = datavar(Float64) \n b_x = datavar(Float64)\n a_y = datavar(Float64) \n b_y = datavar(Float64)\n a_w = datavar(Float64) \n b_w = datavar(Float64)\n s = randomvar()\n y = datavar(Float64)\n \n x0 ~ Normal(mean = m_x_0, precision = τ_x_0)\n τ_x ~ Gamma(shape = a_x, rate = b_x)\n w0 ~ Normal(mean = m_w_0, precision = τ_w_0)\n τ_w ~ Gamma(shape = a_w, rate = b_w)\n τ_y ~ Gamma(shape = a_y, rate = b_y)\n \n x ~ Normal(mean = x0, precision = τ_x)\n w ~ Normal(mean = w0, precision = τ_w)\n\n s ~ f(x, w)\n y ~ Normal(mean = s, precision = τ_y)\n \nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We impose structured mean-field assumption for this model as well:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_constraints = @constraints begin \n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ_y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x0, x, w0, w, τ_x, τ_w, τ_y, s) = q(x0, x)q(w, w0)q(τ_w)q(τ_x)q(s)q(τ\n_y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Online inference in the RxInfer supports the @autoupdates specification, which tells inference procedure how to update priors based on new computed posteriors:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"autoupdates = @autoupdates begin \n m_x_0, τ_x_0 = mean_precision(q(x))\n m_w_0, τ_w_0 = mean_precision(q(w))\n a_x = shape(q(τ_x)) \n b_x = rate(q(τ_x))\n a_y = shape(q(τ_y))\n b_y = rate(q(τ_y))\n a_w = shape(q(τ_w)) \n b_w = rate(q(τ_w))\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(m_x_0,τ_x_0 = mean_precision(q(x)), m_w_0,τ_w_0 = mean_precision(q(w)), a_\nx = shape(q(τ_x)), b_x = rate(q(τ_x)), a_y = shape(q(τ_y)), b_y = rate(q(τ_\ny)), a_w = shape(q(τ_w)), b_w = rate(q(τ_w)))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"As previously we need to define the @meta structure that specifies the approximation method for the nonlinear function smooth_min (f in the model specification):","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_meta = @meta begin \n smooth_min() -> Linearization()\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Meta specification:\n smooth_min() -> Linearization()\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Next step is to generate our dataset and to run the actual inference procedure! For that we use the infer function with autoupdates keyword:","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"n = 300\nrx_real_x, rx_real_w, rx_real_y = generate_data(min, n, seed = 1, x_i_min = 1.0, w_i_min = -1.0, noise = 1.0, real_x_τ = 1.0, real_w_τ = 1.0);\n\npl = plot(title = \"Underlying signals\")\npl = plot!(pl, rx_real_x, label = \"x\")\npl = plot!(pl, rx_real_w, label = \"w\")\n\npr = plot(title = \"Combined y = min(x, w)\")\npr = scatter!(pr, rx_real_y, ms = 3, color = :red, label = \"y\")\n\nplot(pl, pr, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"engine = infer(\n model = rx_identification(smooth_min),\n constraints = rx_constraints,\n data = (y = rx_real_y,),\n autoupdates = autoupdates,\n meta = rx_meta,\n returnvars = (:x, :w, :τ_x, :τ_w, :τ_y, :s),\n keephistory = 1000,\n historyvars = KeepLast(),\n initmarginals = (w = NormalMeanVariance(-2.0, 1.0), x = NormalMeanVariance(2.0, 1.0), τ_x = GammaShapeRate(1.0, 1.0), τ_w = GammaShapeRate(1.0, 1.0), τ_y = GammaShapeRate(1.0, 20.0)),\n iterations = 10,\n free_energy = true, \n free_energy_diagnostics = nothing,\n autostart = true,\n)","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"RxInferenceEngine:\n Posteriors stream | enabled for (w, s, τ_x, τ_w, τ_y, x)\n Free Energy stream | enabled\n Posteriors history | available for (x, w, x0, s, τ_x, τ_w, τ_y, w0)\n Free Energy history | available\n Enabled events | [ ]","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"rx_smarginals = engine.history[:s]\nrx_xmarginals = engine.history[:x]\nrx_wmarginals = engine.history[:w];","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"px1 = plot(legend = :bottomleft, title = \"Estimated hidden signals\")\npx2 = plot(legend = :bottomright, title = \"Estimated combined signals\")\n\npx1 = plot!(px1, rx_real_x, label = \"Real hidden X\")\npx1 = plot!(px1, mean.(rx_xmarginals), ribbon = var.(rx_xmarginals), label = \"Estimated X\")\n\npx1 = plot!(px1, rx_real_w, label = \"Real hidden W\")\npx1 = plot!(px1, mean.(rx_wmarginals), ribbon = var.(rx_wmarginals), label = \"Estimated W\")\n\npx2 = scatter!(px2, rx_real_y, label = \"Observations\", ms = 2, alpha = 0.5, color = :red)\npx2 = plot!(px2, mean.(rx_smarginals), ribbon = std.(rx_smarginals), label = \"Combined estimated signal\", color = :green)\n\nplot(px1, px2, size = (800, 300))","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"The results are quite similar to the smoothing case and, as we can see, one of the random walk is again in the \"disabled\" state, does not infer anything and simply increases its variance (which is expected for the random walk).","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/#Handling-Missing-Data","page":"Kalman filtering and smoothing","title":"Handling Missing Data","text":"","category":"section"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"An interesting case in filtering and smoothing problems is the processing of missing data. It can happen that sometimes your reading devices failt to acquire the data leading to missing observation.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Let us assume that the following model generates the data","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"beginaligned\n x_t sim mathcalNleft(x_t-1 10right) \n y_t sim mathcalNleft(x_t P right) \nendaligned","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"with prior x_0 sim mathcalN(m_x_0 v_x_0). Suppose that our measurement device fails to acquire data from time to time. In this case, instead of scalar observation haty_t in mathrmR we sometimes will catch missing observations.","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"using RxInfer, Plots","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"@model function smoothing(n, x0)\n \n P ~ Gamma(shape = 0.001, scale = 0.001)\n x_prior ~ Normal(mean = mean(x0), var = var(x0)) \n\n x = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n\n x_prev = x_prior\n\n for i in 1:n\n x[i] ~ Normal(mean = x_prev, precision = 1.0)\n y[i] ~ Normal(mean = x[i], precision = P)\n \n x_prev = x[i]\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"We need to manually extend the set of rules to support ::Missing values","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"P = 1.0\nn = 250\n\nreal_signal = map(e -> sin(0.05 * e), collect(1:n))\nnoisy_data = real_signal + rand(Normal(0.0, sqrt(P)), n);\nmissing_indices = 100:125\nmissing_data = similar(noisy_data, Union{Float64, Missing}, )\n\ncopyto!(missing_data, noisy_data)\n\nfor index in missing_indices\n missing_data[index] = missing\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"constraints = @constraints begin\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nend","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(x_prior, x, y, P) = q(x_prior, x)q(P)q(y)\nOptions:\n warn = true","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"x0_prior = NormalMeanVariance(0.0, 1000.0)\n\nresult = infer(\n model = smoothing(n, x0_prior), \n data = (y = missing_data,), \n constraints = constraints,\n initmarginals = (P = Gamma(0.001, 0.001), ),\n returnvars = (x = KeepLast(),),\n iterations = 20\n);","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"plot(real_signal, label = \"Noisy signal\", legend = :bottomright)\nscatter!(missing_indices, real_signal[missing_indices], ms = 2, opacity = 0.75, label = \"Missing region\")\nplot!(mean.(result.posteriors[:x]), ribbon = var.(result.posteriors[:x]), label = \"Estimated hidden state\")","category":"page"},{"location":"examples/basic_examples/Kalman filtering and smoothing/","page":"Kalman filtering and smoothing","title":"Kalman filtering and smoothing","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#examples-conjugate-computational-variational-message-passing-(cvi)","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"using RxInfer, Random, LinearAlgebra, Plots, Optimisers, Plots, StableRNGs, SpecialFunctions","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In this notebook, the usage of Conjugate-NonConjugate Variational Inference (CVI) will be described. The implementation of CVI follows the paper Probabilistic programming with stochastic variational message passing.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This notebook will first describe an example in which CVI is used, then it discusses several limitations, followed by an explanation on how to extend upon CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#An-example:-nonlinear-dynamical-system","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"An example: nonlinear dynamical system","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"A group of researchers is performing a tracking experiment on some moving object along a 1-dimensional trajectory. The object is moving at a constant velocity, meaning that its position increases constantly over time. However, the researchers do not have access to the absolute position z_t at time t. Instead they have access to the observed squared distance y_t between the object and some reference point s. Because of budget cuts, the servo moving the object and the measurement devices are quite outdated and therefore lead to noisy measurements:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# data generating process\nnr_observations = 50\nreference_point = 53\nhidden_location = collect(1:nr_observations) + rand(StableRNG(124), NormalMeanVariance(0.0, sqrt(5)), nr_observations)\nmeasurements = (hidden_location .- reference_point).^2 + rand(MersenneTwister(124), NormalMeanVariance(0.0, 5), nr_observations);","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot hidden location and reference frame\np1 = plot(1:nr_observations, hidden_location, linewidth=3, legend=:topleft, label=\"hidden location\")\nhline!([reference_point], linewidth=3, label=\"reference point\")\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot measurements\np2 = scatter(1:nr_observations, measurements, linewidth=3, label=\"measurements\")\nxlabel!(\"time [sec]\"), ylabel!(\"squared distance [cm2]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers are interested in quantifying this noise and in tracking the unobserved location of the object. As a result of this uncertainty, the researchers employ a probabilistic modeling approach. They formulate the probabilistic model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"beginaligned\n p(tau) = Gamma(tau mid alpha_tau beta_tau)\n p(gamma) = Gamma(gamma mid alpha_gamma beta_gamma)\n p(z_t mid z_t - 1 tau) = mathcalN(z_t mid z_t - 1 + 1 tau^-1)\n p(y_t mid z_t gamma) = mathcalN(y_t mid (z_t - s)^2 gamma^-1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"where the researchers put priors on the process and measurement noise parameters, tau and gamma, respectively. They do this, because they do not know the accuracy of their devices.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The researchers have recently heard of this cool probabilistic programming package RxInfer.jl. They decided to give it a try and create the above model as follows:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"function compute_squared_distance(z)\n (z - reference_point)^2\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function measurement_model(nr_observations)\n\n # allocate random variables and observations\n z = randomvar(nr_observations)\n y = datavar(Float64, nr_observations)\n\n # set priors on precision parameters\n τ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n γ ~ Gamma(shape = 1.0, rate = 1.0e-12)\n \n # specify estimate of initial location\n z[1] ~ Normal(mean = 0, precision = τ)\n y[1] ~ Normal(mean = compute_squared_distance(z[1]), precision = γ)\n\n # loop over observations\n for t in 2:nr_observations\n\n # specify state transition model\n z[t] ~ Normal(mean = z[t-1] + 1, precision = τ)\n\n # specify non-linear observation model\n y[t] ~ Normal(mean = compute_squared_distance(z[t]), precision = γ)\n \n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"But here is the problem, our compute_squared_distance function is already compelx enough such that the exact Bayesian inference is intractable in this model. But the researchers knew that the RxInfer.jl supports a various collection of approximation methods for exactly such cases. One of these approximations is called CVI. CVI allows us to perform probabilistic inference around the non-linear measurement function. In general, for any (non-)linear relationship y = f(x1, x2, ..., xN) CVI can be employed, by specifying the function f and by adding this relationship inside the @model macro as y ~ f(x1, x2, ...,xN). The @model macro will generate a factor node with node function p(y | x1, x2, ..., xN) = δ(y - f(x1, x2, ...,xN)).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The use of this non-linearity requires us to specify that we would like to use CVI. This can be done by specifying the metadata using the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function measurement_meta(rng, nr_samples, nr_iterations, optimizer)\n compute_squared_distance() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In general, for any (non-)linear function f(), CVI can be enabled with the @meta macro as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@meta function model_meta(...)\n f() -> CVI(args...)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"See ?CVI for more information about the args....","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In our model, the z variables are connected to the non-linear node function. So in order to run probabilstic inference with CVI we need to enforce a constraint on the joint posterior distribution. Specifically, we need to create a factorization in which the variables that are directly connected to non-linearities are assumed to be independent from the rest of the variables.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In the above example, we will assume the following posterior factorization:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function measurement_constraints()\n q(z, τ, γ) = q(z)q(τ)q(γ)\nend;","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"This constraint can be explained by the set of two constraints, one for getting CVI to run, and one for assuming a mean-field factorization around the normal node as ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@constraints function posterior_constraints() begin\n q(z, γ) = q(z)q(γ) # CVI\n q(z, τ) = q(z)q(τ) # the mean-field assumption around normal node\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Because the engineers are using RxInfer.jl, they can automate the inference procedure. They track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"results = infer(\n model = measurement_model(nr_observations),\n data = (y = measurements,),\n iterations = 5,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = measurement_constraints(),\n meta = measurement_meta(StableRNG(42), 100, 200, Optimisers.Descent(0.01)),\n initmessages = (z = NormalMeanVariance(0, 5),),\n initmarginals = (z = NormalMeanVariance(0, 5), τ = GammaShapeRate(1.0, 1.0e-12), γ = GammaShapeRate(1.0, 1.0e-12),),\n)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Inference results:\n Posteriors | available for (z)\n Free Energy: | Real[1241.91, 429.933, 376.869, 365.774, 362.879]","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# plot estimates for location\np1 = plot(collect(1:nr_observations), hidden_location, label = \"hidden location\", legend=:topleft, linewidth=3, color = :red)\nplot!(map(mean, results.posteriors[:z]), label = \"estimated location (±2σ)\", ribbon = map(x -> 2*std(x), results.posteriors[:z]), fillalpha=0.5, linewidth=3, color = :orange)\nxlabel!(\"time [sec]\"), ylabel!(\"location [cm]\")\n\n# plot Bethe free energy\np2 = plot(results.free_energy, linewidth=3, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size = (1200, 500))","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Requirements","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Requirements","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"There are several main requirements for the CVI procedure to satisfy:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The out interface of the non-linearity must be independently factorized with respect to other variables in the model.\nThe messages on input interfaces (x1, x2, ..., xN) are required to be from the exponential family of distributions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"In RxInfer, you can satisfy the first requirement by using appropriate factor nodes (Normal, Gamma, Bernoulli, etc) and second requirement by specifying the @constraints macro. In general you can specify this procedure as","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"@model function model(...)\n ...\n y ~ f(x1, x2, ..., xN)\n ... ~ Node2(z1,..., y, zM) # some node that is using the out interface of the non-linearity\n ... \nend\n\n@constraints function constraints_meta() begin\n q(y, z1, ..., zn) = q(y)q(z1,...,zM)\n ...\nend;\n\n@meta function model_meta(...)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer))\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note that not all exponential family distributions are implemented.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Extensions","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Extensions","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/#Using-a-custom-optimizer","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Using a custom optimizer","text":"","category":"section"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"CVI only supports Optimisers optimizers out of the box.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Below an explanation on how to extend to it to a custom optimizer.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Suppose we have CustomDescent structure which we want to use inside CVI for optimization.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"To do so, we need to implement ReactiveMP.cvi_update!(opt::CustomDescent, λ, ∇).","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"ReactiveMP.cvi_update! incapsulates the gradient step:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"opt is used to select your optimizer structure\nλ is the current value\n∇ is a gradient value computed inside CVI.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"struct CustomDescent \n learning_rate::Float64\nend\n\n# Must return an optimizer and its initial state\nfunction ReactiveMP.cvi_setup(opt::CustomDescent, q)\n return (opt, nothing)\nend\n\n# Must return an updated (opt, state) and an updated λ (can use new_λ for inplace operation)\nfunction ReactiveMP.cvi_update!(opt_and_state::Tuple{CustomDescent, Nothing}, new_λ, λ, ∇)\n opt, _ = opt_and_state\n λ̂ = vec(λ) - (opt.learning_rate .* vec(∇))\n copyto!(new_λ, λ̂)\n return opt_and_state, new_λ\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's try to apply it to a model: beginaligned p(x) = mathcalN(0 1)\n p(y_imid x) = mathcalN(y_i mid x^2 1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Let's generate some synthetic data for the model","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# generate data\ny = rand(StableRNG(123), NormalMeanVariance(19^2, 1), 1000)\nhistogram(y)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Again we can create the corresponding model as:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"# specify non-linearity\nf(x) = x ^ 2\n\n# specify model\n@model function normal_square_model(nr_observations)\n\n # allocate observations\n y = datavar(Float64, nr_observations)\n\n # describe prior on latent state\n x ~ NormalMeanPrecision(0, 100)\n\n # transform latent state\n mean ~ f(x)\n\n # observation model\n y .~ NormalMeanVariance(mean, 1)\n\nend\n\n# specify meta\n@meta function normal_square_meta(rng, nr_samples, nr_iterations, optimizer)\n f() -> CVI(rng, nr_samples, nr_iterations, optimizer)\nend","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"normal_square_meta (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"We will use the inference function from ReactiveMP to run inference, where we provide an instance of the CustomDescent structure in our meta macro function:","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Side note: To run the inference for this model, we do not need to init the message for x but with this initialization, the inference procedure is more stable.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"res = infer(\n model = normal_square_model(1000),\n data = (y = y,),\n iterations = 10,\n free_energy = true,\n initmessages = (x = NormalMeanVariance(0, 100),),\n meta = normal_square_meta(StableRNG(123), 100, 100, CustomDescent(0.1))\n)\n\nmean(res.posteriors[:x][end])","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"-18.998075156688632","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"The mean inferred value of x is indeed close to 19, which was used to generate the data. Inference is working! ","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"Note: x^2 can not be inverted; the sign information can be lost: -19 and 19 are both equally good solutions.","category":"page"},{"location":"examples/advanced_examples/Conjugate-Computational Variational Message Passing/","page":"Conjugate-Computational Variational Message Passing (CVI)","title":"Conjugate-Computational Variational Message Passing (CVI)","text":"","category":"page"},{"location":"library/functional-forms/#lib-forms","page":"Built-in functional form constraints","title":"Built-in Functional Forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"This section describes built-in functional forms that can be used for posterior marginal and/or messages form constraints specification. Read more information about constraints specification syntax in the Constraints Specification section.","category":"page"},{"location":"library/functional-forms/#lib-forms-custom-constraints","page":"Built-in functional form constraints","title":"Custom functional forms","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"See the ReactiveMP.jl library documentation for more information about defining novel custom functional forms that are compatible with ReactiveMP inference backend.","category":"page"},{"location":"library/functional-forms/#lib-forms-unspecified-constraint","page":"Built-in functional form constraints","title":"UnspecifiedFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Unspecified functional form constraint is used by default and uses only analytical update rules for computing posterior marginals. Throws an error if a product of two colliding messages cannot be computed analytically.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: Nothing # This is the default setting\nend","category":"page"},{"location":"library/functional-forms/#lib-forms-point-mass-constraint","page":"Built-in functional form constraints","title":"PointMassFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"The most basic form of posterior marginal approximation is the PointMass function. In a few words PointMass represents delta function. In the context of functional form constraints PointMass approximation corresponds to the MAP estimate. For a given distribution d - PointMass functional form simply finds the argmax of the logpdf(d, x) by default. ","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: PointMass # Materializes to the `PointMassFormConstraint` object\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.PointMassFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.PointMassFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.PointMassFormConstraint","text":"PointMassFormConstraint\n\nOne of the form constraint objects. Constraint a message to be in a form of dirac's delta point mass. By default uses Optim.jl package to find argmin of -logpdf(x). Accepts custom optimizer callback which might be used to customise optimisation procedure with different packages or different arguments for Optim.jl package.\n\nKeyword arguments\n\noptimizer: specifies a callback function for logpdf optimisation. See also: ReactiveMP.default_point_mass_form_constraint_optimizer\nstarting_point: specifies a callback function for initial optimisation point: See also: ReactiveMP.default_point_mass_form_constraint_starting_point\nboundaries: specifies a callback function for determining optimisation boundaries: See also: ReactiveMP.default_point_mass_form_constraint_boundaries\n\nCustom optimizer callback interface\n\n# This is an example of the `custom_optimizer` interface\nfunction custom_optimizer(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # should return argmin of the -logpdf(distribution)\nend\n\nCustom starting point callback interface\n\n# This is an example of the `custom_starting_point` interface\nfunction custom_starting_point(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # built-in optimizer expects an array, even for a univariate distribution\n return [ 0.0 ] \nend\n\nCustom boundaries callback interface\n\n# This is an example of the `custom_boundaries` interface\nfunction custom_boundaries(::Type{ Univariate }, ::Type{ Continuous }, constraint::PointMassFormConstraint, distribution)\n # returns a tuple of `lower` and `upper` boundaries\n return (-Inf, Inf)\nend\n\nTraits\n\nis_point_mass_form_constraint = true\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = PointMass (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-sample-list-constraint","page":"Built-in functional form constraints","title":"SampleListFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"SampleListFormConstraints approximates the resulting posterior marginal (product of two colliding messages) as a list of weighted samples. Hence, it requires one of the arguments to be a proper distribution (or at least be able to sample from it). This setting is controlled with LeftProposal(), RightProposal() or AutoProposal() objects. It also accepts an optional method object, but the only one available sampling method currently is the BootstrapImportanceSampling.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000)\n # or \n q(y) :: SampleList(1000, LeftProposal())\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.SampleListFormConstraint\nRxInfer.AutoProposal\nRxInfer.LeftProposal\nRxInfer.RightProposal","category":"page"},{"location":"library/functional-forms/#RxInfer.SampleListFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.SampleListFormConstraint","text":"SampleListFormConstraint(rng, strategy, method)\n\nOne of the form constraint objects. Approximates DistProduct with a SampleList object. \n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = SampleList (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.AutoProposal","page":"Built-in functional form constraints","title":"RxInfer.AutoProposal","text":"Tries to determine the proposal distribution in the SampleList approximation automatically.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.LeftProposal","page":"Built-in functional form constraints","title":"RxInfer.LeftProposal","text":"Uses the left argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#RxInfer.RightProposal","page":"Built-in functional form constraints","title":"RxInfer.RightProposal","text":"Uses the right argument in the prod call as the proposal distribution in the SampleList approximation.\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-fixed-marginal-constraint","page":"Built-in functional form constraints","title":"FixedMarginalFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"Fixed marginal form constraint replaces the resulting posterior marginal obtained during the inference procedure with the prespecified one. Worth to note that the inference backend still tries to compute real posterior marginal and may fail during this process. Might be useful for debugging purposes. If nothing is passed then the computed posterior marginal is returned.","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints function block_updates(x_posterior = nothing) \n # `nothing` returns the computed posterior marginal\n q(x) :: Marginal(x_posterior)\nend","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"RxInfer.FixedMarginalFormConstraint","category":"page"},{"location":"library/functional-forms/#RxInfer.FixedMarginalFormConstraint","page":"Built-in functional form constraints","title":"RxInfer.FixedMarginalFormConstraint","text":"FixedMarginalFormConstraint\n\nOne of the form constraint objects. Provides a constraint on the marginal distribution such that it remains fixed during inference. Can be viewed as blocking of updates of a specific edge associated with the marginal. If nothing is passed then the computed posterior marginal is returned.\n\nTraits\n\nis_point_mass_form_constraint = false\ndefault_form_check_strategy = FormConstraintCheckLast()\ndefault_prod_constraint = GenericProd()\nmake_form_constraint = Marginal (for use in @constraints macro)\n\n\n\n\n\n","category":"type"},{"location":"library/functional-forms/#lib-forms-composite-constraint","page":"Built-in functional form constraints","title":"CompositeFormConstraint","text":"","category":"section"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"It is possible to create a composite functional form constraint with either + operator or using @constraints macro, e.g:","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"form_constraint = SampleListFormConstraint(1000) + PointMassFormConstraint()","category":"page"},{"location":"library/functional-forms/","page":"Built-in functional form constraints","title":"Built-in functional form constraints","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass()\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/#examples-hierarchical-gaussian-filter","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"","category":"section"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this demo the goal is to perform approximate variational Bayesian Inference for Univariate Hierarchical Gaussian Filter (HGF).","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Simple HGF model can be defined as:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n x^(j)_k sim mathcalN(x^(j)_k - 1 f_k(x^(j - 1)_k)) \n y_k sim mathcalN(x^(j)_k tau_k)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"where j is an index of layer in hierarchy, k is a time step and f_k is a variance activation function. RxInfer.jl export Gaussian Controlled Variance (GCV) node with f_k = exp(kappa x + omega) variance activation function. By default the node uses Gauss-Hermite cubature with a prespecified number of approximation points in the cubature. In this demo we also show how we can change the hyperparameters in different approximation methods (iin this case Gauss-Hermite cubature) with the help of metadata structures. Here how our model will look like with the GCV node:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"beginaligned\n z_k sim mathcalN(z_k - 1 mathcaltau_z) \n x_k sim mathcalN(x_k - 1 exp(kappa z_k + omega)) \n y_k sim mathcalN(x_k mathcaltau_y)\nendaligned","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"In this experiment we will create a single time step of the graph and perform variational message passing filtering alrogithm to estimate hidden states of the system. For a more rigorous introduction to Hierarchical Gaussian Filter we refer to Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter paper.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"For simplicity we will consider tau_z, tau_y, kappa and omega known and fixed, but there are no principled limitations to make them random variables too.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To model this process in RxInfer, first, we start with importing all needed packages:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"using RxInfer, BenchmarkTools, Random, Plots","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Next step, is to generate some synthetic data:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function generate_data(rng, k, w, zv, yv)\n z_prev = 0.0\n x_prev = 0.0\n\n z = Vector{Float64}(undef, n)\n v = Vector{Float64}(undef, n)\n x = Vector{Float64}(undef, n)\n y = Vector{Float64}(undef, n)\n\n for i in 1:n\n z[i] = rand(rng, Normal(z_prev, sqrt(zv)))\n v[i] = exp(k * z[i] + w)\n x[i] = rand(rng, Normal(x_prev, sqrt(v[i])))\n y[i] = rand(rng, Normal(x[i], sqrt(yv)))\n\n z_prev = z[i]\n x_prev = x[i]\n end \n \n return z, x, y\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"generate_data (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# Seed for reproducibility\nseed = 42\n\nrng = MersenneTwister(seed)\n\n# Parameters of HGF process\nreal_k = 1.0\nreal_w = 0.0\nz_variance = abs2(0.2)\ny_variance = abs2(0.1)\n\n# Number of observations\nn = 300\n\nz, x, y = generate_data(rng, real_k, real_w, z_variance, y_variance);","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"Let's plot our synthetic dataset. Lines represent our hidden states we want to estimate using noisy observations.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n scatter!(px, 1:n, y, label = \"y_i\", color = :red, ms = 2, alpha = 0.2)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"To create a model we use the @model macro:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"# We create a single-time step of corresponding state-space process to\n# perform online learning (filtering)\n@model function hgf(real_k, real_w, z_variance, y_variance)\n \n # Priors from previous time step for `z`\n zt_min_mean = datavar(Float64)\n zt_min_var = datavar(Float64)\n \n # Priors from previous time step for `x`\n xt_min_mean = datavar(Float64)\n xt_min_var = datavar(Float64)\n\n zt_min ~ NormalMeanVariance(zt_min_mean, zt_min_var)\n xt_min ~ NormalMeanVariance(xt_min_mean, xt_min_var)\n\n # Higher layer is modelled as a random walk \n zt ~ NormalMeanVariance(zt_min, z_variance)\n \n # Lower layer is modelled with `GCV` node\n gcvnode, xt ~ GCV(xt_min, zt, real_k, real_w)\n \n # Noisy observations \n y = datavar(Float64)\n y ~ NormalMeanVariance(xt, y_variance)\n \n return gcvnode\nend\n\n@constraints function hgfconstraints() \n q(xt, zt, xt_min) = q(xt, xt_min)q(zt)\nend\n\n@meta function hgfmeta()\n # Lets use 31 approximation points in the Gauss Hermite cubature approximation method\n GCV(xt_min, xt, zt) -> GCVMetadata(GaussHermiteCubature(31)) \nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"hgfmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"function run_inference(data, real_k, real_w, z_variance, y_variance)\n\n autoupdates = @autoupdates begin\n zt_min_mean, zt_min_var = mean_var(q(zt))\n xt_min_mean, xt_min_var = mean_var(q(xt))\n end\n\n return infer(\n model = hgf(real_k, real_w, z_variance, y_variance),\n constraints = hgfconstraints(),\n meta = hgfmeta(),\n data = (y = data, ),\n autoupdates = autoupdates,\n keephistory = length(data),\n historyvars = (\n xt = KeepLast(),\n zt = KeepLast()\n ),\n initmarginals = (\n zt = NormalMeanVariance(0.0, 5.0),\n xt = NormalMeanVariance(0.0, 5.0),\n ), \n iterations = 5,\n free_energy = true,\n autostart = true,\n callbacks = (\n after_model_creation = (model, returnval) -> begin \n gcvnode = returnval\n setmarginal!(gcvnode, :y_x, MvNormalMeanCovariance([ 0.0, 0.0 ], [ 5.0, 5.0 ]))\n end,\n )\n )\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"run_inference (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"result = run_inference(y, real_k, real_w, z_variance, y_variance);\n\nmz = result.history[:zt];\nmx = result.history[:xt];","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"let \n pz = plot(title = \"Hidden States Z\")\n px = plot(title = \"Hidden States X\")\n \n plot!(pz, 1:n, z, label = \"z_i\", color = :orange)\n plot!(pz, 1:n, mean.(mz), ribbon = std.(mz), label = \"estimated z_i\", color = :teal)\n \n plot!(px, 1:n, x, label = \"x_i\", color = :green)\n plot!(px, 1:n, mean.(mx), ribbon = std.(mx), label = \"estimated x_i\", color = :violet)\n \n plot(pz, px, layout = @layout([ a; b ]))\nend","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see from our plot, estimated signal resembles closely to the real hidden states with small variance. We maybe also interested in the values for Bethe Free Energy functional:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"plot(result.free_energy_history, label = \"Bethe Free Energy\")","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"As we can see BetheFreeEnergy converges nicely to a stable point.","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"At final, lets check the overall performance of our resulting Variational Message Passing algorithm:","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"@benchmark run_inference($y, $real_k, $real_w, $z_variance, $y_variance)","category":"page"},{"location":"examples/problem_specific/Hierarchical Gaussian Filter/","page":"Hierarchical Gaussian Filter","title":"Hierarchical Gaussian Filter","text":"BenchmarkTools.Trial: 45 samples with 1 evaluation.\n Range (min … max): 84.766 ms … 164.193 ms ┊ GC (min … max): 0.00% … 0.0\n0%\n Time (median): 109.323 ms ┊ GC (median): 0.00%\n Time (mean ± σ): 112.571 ms ± 13.115 ms ┊ GC (mean ± σ): 1.76% ± 3.3\n8%\n\n █▄▃▃ \n ▄▁▁▁▁▁▁▄▁▁▁▁▄▇▄▁▆████▁▁▆▄▆▄▁▁▁▄▁▁▁▁▄▁▄▁▁▁▄▁▁▁▁▁▄▁▁▁▁▁▁▁▁▁▁▁▁▄ ▁\n 84.8 ms Histogram: frequency by time 164 ms <\n\n Memory estimate: 18.78 MiB, allocs estimate: 456890.","category":"page"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = RxInfer","category":"page"},{"location":"#RxInfer","page":"Home","title":"RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"(Image: RxInfer Logo)","category":"page"},{"location":"","page":"Home","title":"Home","text":"
","category":"page"},{"location":"","page":"Home","title":"Home","text":"Julia package for automatic Bayesian inference on a factor graph with reactive message passing.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Given 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 Forney-style factor graph (FFG) representation of the model. RxInfer.jl has been designed with a focus on efficiency, scalability and maximum performance for running inference with message passing.","category":"page"},{"location":"#Package-Features","page":"Home","title":"Package Features","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"User friendly syntax for specification of probabilistic models.\nAutomatic generation of message passing algorithms including\nBelief propagation\nVariational message passing\nExpectation maximization\nSupport for hybrid models combining discrete and continuous latent variables.\nSupport for hybrid distinct message passing inference algorithm under a unified paradigm.\nFactorisation and functional form constraints specification.\nEvaluation of Bethe free energy as a model performance measure.\nSchedule-free reactive message passing API.\nHigh performance.\nScalability for large models with millions of parameters and observations.\nInference procedure is differentiable.\nEasy to extend with custom nodes and message update rules.","category":"page"},{"location":"#Why-RxInfer","page":"Home","title":"Why RxInfer","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Many important AI applications, including audio processing, self-driving vehicles, weather forecasting, and extended-reality video processing require continually solving an inference task in sophisticated probabilistic models with a large number of latent variables. Often, the inference task in these applications must be performed continually and in real-time in response to new observations. Popular MC-based inference methods, such as the No U-Turn Sampler (NUTS) or Hamiltonian Monte Carlo (HMC) sampling, rely on computationally heavy sampling procedures that do not scale well to probabilistic models with thousands of latent states. Therefore, MC-based inference is practically not suitable for real-time applications. While the alternative variational inference method (VI) promises to scale better to large models than sampling-based inference, VI requires the derivation of gradients of a \"variational Free Energy\" cost function. For large models, manual derivation of these gradients might not be feasible, while automated \"black-box\" gradient methods do not scale either because they are not capable of taking advantage of sparsity or conjugate pairs in the model. Therefore, while Bayesian inference is known as the optimal data processing framework, in practice, real-time AI applications rely on much simpler, often ad hoc, data processing algorithms.","category":"page"},{"location":"","page":"Home","title":"Home","text":"RxInfer aims to remedy these issues by running efficient Bayesian inference in sophisticated probabilistic models, taking advantage of local conjugate relationships in probabilistic models, and focusing on real-time Bayesian inference in large state-space models with thousands of latent variables. In addition, RxInfer provides a straightforward way to extend its functionality with custom factor nodes and message passing update rules. The engine is capable of running various Bayesian inference algorithms in different parts of the factor graph of a single probabilistic model. This makes it easier to explore different \"what-if\" scenarios and enables very efficient inference in specific cases.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Curious about how RxInfer compares to other tools you might be considering? We invite you to view a detailed comparison, where we put RxInfer head-to-head with other popular packages in the field.","category":"page"},{"location":"#How-to-get-started?","page":"Home","title":"How to get started?","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Head to the Getting started section to get up and running with RxInfer. Alternatively, explore various examples in the documentation.","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\n \"manuals/background.md\",\n \"manuals/comparison.md\",\n \"manuals/getting-started.md\",\n \"manuals/model-specification.md\",\n \"manuals/constraints-specification.md\",\n \"manuals/meta-specification.md\",\n \"manuals/inference-execution.md\",\n \"manuals/custom-node.md\",\n \"manuals/debugging.md\",\n \"manuals/delta-node.md\",\n \"examples/overview.md\",\n \"library/exported-methods.md\",\n \"library/functional-forms.md\",\n \"contributing/overview.md\",\n \"contributing/new-example.md\"\n]\nDepth = 2","category":"page"},{"location":"#References","page":"Home","title":"References","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RxInfer: A Julia package for reactive real-time Bayesian inference - a reference paper for the RxInfer.jl framwork.\nVariational Message Passing and Local Constraint Manipulation in Factor Graphs - describes theoretical aspects of the underlying Bayesian inference method.\nReactive Message Passing for Scalable Bayesian Inference - describes implementation aspects of the Bayesian inference engine and performs benchmarks and accuracy comparison on various models.\nA Julia package for reactive variational Bayesian inference - a reference paper for the ReactiveMP.jl package, the underlying inference engine.\nThe Factor Graph Approach to Model-Based Signal Processing - an introduction to message passing and FFGs.","category":"page"},{"location":"#Ecosystem","page":"Home","title":"Ecosystem","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"The RxInfer unites 3 core packages into one powerful reactive message passing-based Bayesian inference framework:","category":"page"},{"location":"","page":"Home","title":"Home","text":"ReactiveMP.jl - core package for efficient and scalable for reactive message passing \nGraphPPL.jl - package for model and constraints specification\nRocket.jl - reactive programming tools","category":"page"},{"location":"#Index","page":"Home","title":"Index","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"manuals/inference/infer/#user-guide-inference","page":"Static vs Streamline inference","title":"Automatic Inference Specification","text":"","category":"section"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"RxInfer provides the infer function for quickly running and testing your model with both static and streaming datasets. To enable streaming behavior, the infer function accepts an autoupdates argument, which specifies how to update your priors for future states based on newly updated posteriors. ","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"It's important to note that while this function covers most capabilities of the inference engine, advanced use cases may require resorting to the Manual Inference Specification.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"For details on manual inference specification, see the Manual Inference section.","category":"page"},{"location":"manuals/inference/infer/","page":"Static vs Streamline inference","title":"Static vs Streamline inference","text":"infer\nInferenceResult\nRxInfer.start\nRxInfer.stop\n@autoupdates\nRxInferenceEngine\nRxInferenceEvent","category":"page"},{"location":"manuals/inference/infer/#RxInfer.infer","page":"Static vs Streamline inference","title":"RxInfer.infer","text":"infer(\n model; \n data = nothing,\n datastream = nothing,\n autoupdates = nothing,\n initmarginals = nothing,\n initmessages = nothing,\n constraints = nothing,\n meta = nothing,\n options = nothing,\n returnvars = nothing, \n predictvars = nothing, \n historyvars = nothing,\n keephistory = nothing,\n iterations = nothing,\n free_energy = false,\n free_energy_diagnostics = BetheFreeEnergyDefaultChecks,\n showprogress = false,\n callbacks = nothing,\n addons = nothing,\n postprocess = DefaultPostprocess(),\n warn = true,\n events = nothing,\n uselock = false,\n autostart = true,\n catch_exception = false\n)\n\nThis function provides a generic way to perform probabilistic inference for batch/static and streamline/online scenarios. Returns an InferenceResult (batch setting) or RxInferenceEngine (streamline setting) based on the parameters used.\n\nArguments\n\nFor more information about some of the arguments, please check below. \n\nmodel: specifies a model generator, required\ndata: NamedTuple or Dict with data, required (or datastream or predictvars)\ndatastream: A stream of NamedTuple with data, required (or data)\nautoupdates = nothing: auto-updates specification, required for streamline inference, see @autoupdates\ninitmarginals = nothing: NamedTuple or Dict with initial marginals, optional\ninitmessages = nothing: NamedTuple or Dict with initial messages, optional\nconstraints = nothing: constraints specification object, optional, see @constraints\nmeta = nothing: meta specification object, optional, may be required for some models, see @meta\noptions = nothing: model creation options, optional, see ModelInferenceOptions\nreturnvars = nothing: return structure info, optional, defaults to return everything at each iteration, see below for more information\npredictvars = nothing: return structure info, optional, see below for more information (exclusive for batch inference)\nhistoryvars = nothing: history structure info, optional, defaults to no history, see below for more information (exclusive for streamline inference)\nkeephistory = nothing: history buffer size, defaults to empty buffer, see below for more information (exclusive for streamline inference)\niterations = nothing: number of iterations, optional, defaults to nothing, the inference engine does not distinguish between variational message passing or Loopy belief propagation or expectation propagation iterations, see below for more information\nfree_energy = false: compute the Bethe free energy, optional, defaults to false. Can be passed a floating point type, e.g. Float64, for better efficiency, but disables automatic differentiation packages, such as ForwardDiff.jl\nfree_energy_diagnostics = BetheFreeEnergyDefaultChecks: free energy diagnostic checks, optional, by default checks for possible NaNs and Infs. nothing disables all checks.\nshowprogress = false: show progress module, optional, defaults to false (exclusive for batch inference)\ncatch_exception specifies whether exceptions during the inference procedure should be caught, optional, defaults to false (exclusive for batch inference)\ncallbacks = nothing: inference cycle callbacks, optional, see below for more info\naddons = nothing: inject and send extra computation information along messages, see below for more info\npostprocess = DefaultPostprocess(): inference results postprocessing step, optional, see below for more info\nevents = nothing: inference cycle events, optional, see below for more info (exclusive for streamline inference)\nuselock = false: specifies either to use the lock structure for the inference or not, if set to true uses Base.Threads.SpinLock. Accepts custom AbstractLock. (exclusive for streamline inference)\nautostart = true: specifies whether to call RxInfer.start on the created engine automatically or not (exclusive for streamline inference)\nwarn = true: enables/disables warnings\n\nNote on NamedTuples\n\nWhen passing NamedTuple as a value for some argument, make sure you use a trailing comma for NamedTuples with a single entry. The reason is that Julia treats returnvars = (x = KeepLast()) and returnvars = (x = KeepLast(), ) expressions differently. This first expression creates (or overwrites!) new local/global variable named x with contents KeepLast(). The second expression (note trailing comma) creates NamedTuple with x as a key and KeepLast() as a value assigned for this key.\n\nThe model argument accepts a ModelGenerator as its input. The easiest way to create the ModelGenerator is to use the @model macro. For example:\n\n@model function coin_toss(some_argument, some_keyword_argument = 3)\n ...\nend\n\nresult = infer(\n model = coin_toss(some_argument; some_keyword_argument = 3)\n)\n\nNote: The model keyword argument does not accept a FactorGraphModel instance as a value, as it needs to inject constraints and meta during the inference procedure.\n\ndata\n\nEither data or datastream or predictvars keyword argument is required. Specifying both data and datastream is not supported and will result in an error. Specifying both datastream and predictvars is not supported and will result in an error.\n\nNote: The behavior of the data keyword argument depends on the inference setting (batch or streamline).\n\nThe data keyword argument must be a NamedTuple (or Dict) where keys (of Symbol type) correspond to all datavars defined in the model specification. For example, if a model defines x = datavar(Float64) the data field must have an :x key (of Symbol type) which holds a value of type Float64. The values in the data must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then data[:x] must provide a container with length n and with elements of type Float64.\n\nstreamline setting\n\nAll entries in the data argument are zipped together with the Base.zip function to form one slice of the data chunck. This means all containers in the data argument must be of the same size (zip iterator finished as soon as one container has no remaining values). In order to use a fixed value for some specific datavar it is not necessary to create a container with that fixed value, but rather more efficient to use Iterators.repeated to create an infinite iterator.\n\ndatastream\n\nThe datastream keyword argument must be an observable that supports subscribe! and unsubscribe! functions (streams from the Rocket.jl package are also supported). The elements of the observable must be of type NamedTuple where keys (of Symbol type) correspond to all datavars defined in the model specification, except for those which are listed in the autoupdates specification. For example, if a model defines x = datavar(Float64) (which is not part of the autoupdates specification) the named tuple from the observable must have an :x key (of Symbol type) which holds a value of type Float64. The values in the named tuple must have the exact same shape as the datavar container. In other words, if a model defines x = datavar(Float64, n) then namedtuple[:x] must provide a container with length n and with elements of type Float64.\n\nNote: The behavior of the individual named tuples from the datastream observable is similar to that which is used in the batch setting. In fact, you can see the streamline inference as an efficient version of the batch inference, which automatically updates some datavars with the autoupdates specification and listens to the datastream to update the rest of the datavars.\n\nFor specific types of inference algorithms, such as variational message passing, it might be required to initialize (some of) the marginals before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial marginals, you can use the initmarginals argument, such as\n\ninfer(...\n initmarginals = (\n # initialize the marginal distribution of x as a vague Normal distribution\n # if x is a vector, then it simply uses the same value for all elements\n # However, it is also possible to provide a vector of distributions to set each element individually \n x = vague(NormalMeanPrecision), \n ),\n)\n\nThis argument needs to be a named tuple, i.e. `initmarginals = (a = ..., )`, or dictionary.\n\n- ### `initmessages`\n\nFor specific types of inference algorithms, such as loopy belief propagation or expectation propagation, it might be required to initialize (some of) the messages before running the inference procedure in order to break the dependency loop. If this is not done, the inference algorithm will not be executed due to the lack of information and message and/or marginals will not be updated. In order to specify these initial messages, you can use the `initmessages` argument, such as\n\njulia infer(... initmessages = ( # initialize the messages distribution of x as a vague Normal distribution # if x is a vector, then it simply uses the same value for all elements # However, it is also possible to provide a vector of distributions to set each element individually x = vague(NormalMeanPrecision), ), )\n\noptions\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\nreturnvars\n\nreturnvars specifies latent variables of interest and their posterior updates. Its behavior depends on the inference type: streamline or batch.\n\nBatch inference:\n\nAccepts a NamedTuple or Dict of return variable specifications.\nTwo specifications available: KeepLast (saves the last update) and KeepEach (saves all updates).\nWhen iterations is set, returns every update for each iteration (equivalent to KeepEach()); if nothing, saves the last update (equivalent to KeepLast()).\nUse iterations = 1 to force KeepEach() for a single iteration or set returnvars = KeepEach() manually.\n\nExample:\n\nresult = infer(\n ...,\n returnvars = (\n x = KeepLast(),\n τ = KeepEach()\n )\n)\n\nShortcut for setting the same option for all variables:\n\nresult = infer(\n ...,\n returnvars = KeepLast() # or KeepEach()\n)\n\nStreamline inference:\n\nFor each symbol in returnvars, infer creates an observable stream of posterior updates.\nAgents can subscribe to these updates using the Rocket.jl package.\n\nExample:\n\nengine = infer(\n ...,\n autoupdates = my_autoupdates,\n returnvars = (:x, :τ),\n autostart = false\n)\n\npredictvars\n\npredictvars specifies the variables which should be predicted. In the model definition these variables are specified as datavars, although they should not be passed inside data argument.\n\nSimilar to returnvars, predictvars accepts a NamedTuple or Dict. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n predictvars = (\n o = KeepLast(),\n τ = KeepEach()\n )\n)\n\nNote: The predictvars argument is exclusive for batch setting.\n\nhistoryvars\n\nhistoryvars specifies the variables of interests and the amount of information to keep in history about the posterior updates when performing streamline inference. The specification is similar to the returnvars when applied in batch setting. The historyvars requires keephistory to be greater than zero.\n\nhistoryvars accepts a NamedTuple or Dict or return var specification. There are two specifications:\n\nKeepLast: saves the last update for a variable, ignoring any intermediate results during iterations\nKeepEach: saves all updates for a variable for all iterations\n\nExample: \n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = (\n x = KeepLast(),\n τ = KeepEach()\n ),\n keephistory = 10\n)\n\nIt is also possible to set either historyvars = KeepLast() or historyvars = KeepEach() that acts as an alias and sets the given option for all random variables in the model.\n\nExample:\n\nresult = infer(\n ...,\n autoupdates = my_autoupdates,\n historyvars = KeepLast(),\n keephistory = 10\n)\n\nkeep_history\n\nSpecifies the buffer size for the updates history both for the historyvars and the free_energy buffers in streamline inference.\n\niterations\n\nSpecifies the number of variational (or loopy belief propagation) iterations. By default set to nothing, which is equivalent of doing 1 iteration. \n\nfree_energy\n\nStreamline inference:\n\nSpecifies if the infer function should create an observable stream of Bethe Free Energy (BFE) values, computed at each VMP iteration.\n\nWhen free_energy = true and keephistory > 0, additional fields are exposed in the engine for accessing the history of BFE updates.\nengine.free_energy_history: Averaged BFE history over VMP iterations.\nengine.free_energy_final_only_history: BFE history of values computed in the last VMP iterations for each observation.\nengine.free_energy_raw_history: Raw BFE history.\n\nBatch inference:\n\nSpecifies if the infer function should return Bethe Free Energy (BFE) values.\n\nOptionally accepts a floating-point type (e.g., Float64) for improved BFE computation performance, but restricts the use of automatic differentiation packages.\nfree_energy_diagnostics\n\nThis settings specifies either a single or a tuple of diagnostic checks for Bethe Free Energy values stream. By default checks for NaNs and Infs. See also BetheFreeEnergyCheckNaNs and BetheFreeEnergyCheckInfs. Pass nothing to disable any checks.\n\ncatch_exception\n\nThe catch_exception keyword argument specifies whether exceptions during the batch inference procedure should be caught in the error field of the result. By default, if exception occurs during the inference procedure the result will be lost. Set catch_exception = true to obtain partial result for the inference in case if an exception occurs. Use RxInfer.issuccess and RxInfer.iserror function to check if the inference completed successfully or failed. If an error occurs, the error field will store a tuple, where first element is the exception itself and the second element is the caught backtrace. Use the stacktrace function with the backtrace as an argument to recover the stacktrace of the error. Use Base.showerror function to display the error.\n\ncallbacks\n\nThe inference function has its own lifecycle. The user is free to provide some (or none) of the callbacks to inject some extra logging or other procedures in the inference function, e.g.\n\nresult = infer(\n ...,\n callbacks = (\n on_marginal_update = (model, name, update) -> println(\"$(name) has been updated: $(update)\"),\n after_inference = (args...) -> println(\"Inference has been completed\")\n )\n)\n\nThe callbacks keyword argument accepts a named-tuple of 'name = callback' pairs. The list of all possible callbacks for different inference setting (batch or streamline) and their arguments is present below:\n\non_marginal_update: args: (model::FactorGraphModel, name::Symbol, update) (exlusive for batch inference)\nbefore_model_creation: args: ()\nafter_model_creation: args: (model::FactorGraphModel, returnval)\nbefore_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nbefore_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_data_update: args: (model::FactorGraphModel, data) (exlusive for batch inference)\nafter_iteration: args: (model::FactorGraphModel, iteration::Int)::Bool (exlusive for batch inference)\nafter_inference: args: (model::FactorGraphModel) (exlusive for batch inference)\nbefore_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\nafter_autostart: args: (engine::RxInferenceEngine) (exlusive for streamline inference)\n\nbefore_iteration and after_iteration callbacks are allowed to return true/false value. true indicates that iterations must be halted and no further inference should be made.\n\naddons\n\nThe addons field extends the default message computation rules with some extra information, e.g. computing log-scaling factors of messages or saving debug-information. Accepts a single addon or a tuple of addons. If set, replaces the corresponding setting in the options. Automatically changes the default value of the postprocess argument to NoopPostprocess.\n\npostprocess\n\nThe postprocess keyword argument controls whether the inference results must be modified in some way before exiting the inference function. By default, the inference function uses the DefaultPostprocess strategy, which by default removes the Marginal wrapper type from the results. Change this setting to NoopPostprocess if you would like to keep the Marginal wrapper type, which might be useful in the combination with the addons argument. If the addons argument has been used, automatically changes the default strategy value to NoopPostprocess.\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.InferenceResult","page":"Static vs Streamline inference","title":"RxInfer.InferenceResult","text":"InferenceResult\n\nThis structure is used as a return value from the infer function. \n\nPublic Fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior' pairs. See the returnvars argument for infer.\nfree_energy: (optional) An array of Bethe Free Energy values per VMP iteration. See the free_energy argument for infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\nerror: (optional) A reference to an exception, that might have occurred during the inference. See the catch_exception argument for infer.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.start","page":"Static vs Streamline inference","title":"RxInfer.start","text":"start(engine::RxInferenceEngine)\n\nStarts the RxInferenceEngine by subscribing to the data source, instantiating free energy (if enabled) and starting the event loop. Use RxInfer.stop to stop the RxInferenceEngine. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.stop\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.stop","page":"Static vs Streamline inference","title":"RxInfer.stop","text":"stop(engine::RxInferenceEngine)\n\nStops the RxInferenceEngine by unsubscribing to the data source, free energy (if enabled) and stopping the event loop. Use RxInfer.start to start the RxInferenceEngine again. Note that it is not always possible to stop/restart the engine and this depends on the data source type.\n\nSee also: RxInfer.start\n\n\n\n\n\n","category":"function"},{"location":"manuals/inference/infer/#RxInfer.@autoupdates","page":"Static vs Streamline inference","title":"RxInfer.@autoupdates","text":"@autoupdates\n\nCreates the auto-updates specification for the rxinference function. In the online-streaming Bayesian inference procedure it is important to update your priors for the future states based on the new updated posteriors. The @autoupdates structure simplify such a specification. It accepts a single block of code where each line defines how to update the datavar's in the probabilistic model specification. \n\nEach line of code in the auto-update specification defines datavars, which need to be updated, on the left hand side of the equality expression and the update function on the right hand side of the expression. The update function operates on posterior marginals in the form of the q(symbol) expression.\n\nFor example:\n\n@autoupdates begin \n x = f(q(z))\nend\n\nThis structure specifies to automatically update x = datavar(...) as soon as the inference engine computes new posterior over z variable. It then applies the f function to the new posterior and calls update!(x, ...) automatically. \n\nAs an example consider the following model and auto-update specification:\n\n@model function kalman_filter()\n x_current_mean = datavar(Float64)\n x_current_var = datavar(Float64)\n\n x_current ~ Normal(mean = x_current_mean, var = x_current_var)\n\n x_next ~ Normal(mean = x_current, var = 1.0)\n\n y = datavar(Float64)\n y ~ Normal(mean = x_next, var = 1.0)\nend\n\nThis model has two datavars that represent our prior knowledge of the x_current state of the system. The x_next random variable represent the next state of the system that is connected to the observed variable y. The auto-update specification could look like:\n\nautoupdates = @autoupdates begin\n x_current_mean, x_current_var = mean_cov(q(x_next))\nend\n\nThis structure specifies to update our prior as soon as we have a new posterior q(x_next). It then applies the mean_cov function on the updated posteriors and updates datavars x_current_mean and x_current_var automatically.\n\nSee also: infer\n\n\n\n\n\n","category":"macro"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEngine","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEngine","text":"RxInferenceEngine\n\nThe return value of the rxinference function. \n\nPublic fields\n\nposteriors: Dict or NamedTuple of 'random variable' - 'posterior stream' pairs. See the returnvars argument for the infer.\nfree_energy: (optional) A stream of Bethe Free Energy values per VMP iteration. See the free_energy argument for the infer.\nhistory: (optional) Saves history of previous marginal updates. See the historyvars and keephistory arguments for the infer.\nfree_energy_history: (optional) Free energy history, average over variational iterations \nfree_energy_raw_history: (optional) Free energy history, returns returns computed values of all variational iterations for each data event (if available)\nfree_energy_final_only_history: (optional) Free energy history, returns computed values of final variational iteration for each data event (if available)\nevents: (optional) A stream of events send by the inference engine. See the events argument for the infer.\nmodel: FactorGraphModel object reference.\nreturnval: Return value from executed @model.\n\nUse the RxInfer.start(engine) function to subscribe on the data source and start the inference procedure. Use RxInfer.stop(engine) to unsubscribe from the data source and stop the inference procedure. Note, that it is not always possible to start/stop the inference procedure.\n\nSee also: infer, RxInferenceEvent, RxInfer.start, RxInfer.stop\n\n\n\n\n\n","category":"type"},{"location":"manuals/inference/infer/#RxInfer.RxInferenceEvent","page":"Static vs Streamline inference","title":"RxInfer.RxInferenceEvent","text":"RxInferenceEvent{T, D}\n\nThe RxInferenceEngine sends events in a form of the RxInferenceEvent structure. T represents the type of an event, D represents the type of a data associated with the event. The type of data depends on the type of an event, but usually represents a tuple, which can be unrolled automatically with the Julia's splitting syntax, e.g. model, iteration = event. See the documentation of the rxinference function for possible event types and their associated data types.\n\nThe events system itself uses the Rocket.jl library API. For example, one may create a custom event listener in the following way:\n\nusing Rocket\n\nstruct MyEventListener <: Rocket.Actor{RxInferenceEvent}\n # ... extra fields\nend\n\nfunction Rocket.on_next!(listener::MyEventListener, event::RxInferenceEvent{ :after_iteration })\n model, iteration = event\n println(\"Iteration $(iteration) has been finished.\")\nend\n\nfunction Rocket.on_error!(listener::MyEventListener, err)\n # ...\nend\n\nfunction Rocket.on_complete!(listener::MyEventListener)\n # ...\nend\n\n\nand later on:\n\nengine = infer(events = Val((:after_iteration, )), ...)\n\nsubscription = subscribe!(engine.events, MyEventListener(...))\n\nSee also: infer, RxInferenceEngine\n\n\n\n\n\n","category":"type"},{"location":"examples/advanced_examples/overview/#examples-advanced_examples-overview","page":"Overview","title":"Advanced examples","text":"","category":"section"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Advanced examples contain more complex inference problems.","category":"page"},{"location":"examples/advanced_examples/overview/","page":"Overview","title":"Overview","text":"Active Inference Mountain car: This notebooks covers RxInfer usage in the Active Inference setting for the simple mountain car problem.\nAdvanced Tutorial: This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.\nAssessing People’s Skills: The demo is inspired by the example from Chapter 2 of Bishop's Model-Based Machine Learning book. We are going to perform an exact inference to assess the skills of a student given the results of the test.\nChance-Constrained Active Inference: This notebook applies reactive message passing for active inference in the context of chance-constraints.\nConjugate-Computational Variational Message Passing (CVI): This example provides an extensive tutorial for the non-conjugate message-passing based inference by exploiting the local CVI approximation.\nGlobal Parameter Optimisation: This example shows how to use RxInfer.jl automated inference within other optimisation packages such as Optim.jl.\nSolve GP regression by SDE: In this notebook, we solve a GP regression problem by using 'Stochastic Differential Equation' (SDE). This method is well described in the dissertation 'Stochastic differential equation methods for spatio-temporal Gaussian process regression.' by Arno Solin and 'Sequential Inference for Latent Temporal Gaussian Process Models' by Jouni Hartikainen.\nInfinite Data Stream: This example shows RxInfer capabilities of running inference for infinite time-series data.\nNonlinear Sensor Fusion: Nonlinear object position identification using a sparse set of sensors","category":"page"},{"location":"manuals/constraints-specification/#user-guide-constraints-specification","page":"Constraints specification","title":"Constraints Specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"RxInfer.jl exports @constraints macro for the extra constraints specification that can be used during the inference step in ReactiveMP.jl engine package.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"using RxInfer","category":"page"},{"location":"manuals/constraints-specification/#General-syntax","page":"Constraints specification","title":"General syntax","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts either regular Julia function or a single begin ... end block. For example both are valid:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"\n# `functional` style\n@constraints function create_my_constraints(arg1, arg2)\n ...\nend\n\n# `block` style\nmyconstraints = @constraints begin \n ...\nend\n","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In the first case it returns a function that return constraints upon calling, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(mean_field)\n q(x) :: PointMass\n\n if mean_field\n q(x, y) = q(x)q(y)\n end\nend\n\nmyconstraints = make_constraints(true)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"and in the second case it evaluates automatically and returns constraints object directly.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints begin \n q(x) :: PointMass\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/#Options-specification","page":"Constraints specification","title":"Options specification","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro accepts optional list of options as a first argument and specified as an array of key = value pairs, e.g. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"myconstraints = @constraints [ warn = false ] begin \n ...\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"List of available options:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"warn::Bool - enables/disables various warnings with an incompatible model/constraints specification","category":"page"},{"location":"manuals/constraints-specification/#Marginal-and-messages-form-constraints","page":"Constraints specification","title":"Marginal and messages form constraints","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To specify marginal or messages form constraints @constraints macro uses :: operator (in somewhat similar way as Julia uses it for multiple dispatch type specification)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"The following constraint:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the resulting marginal of the variable (or array of variables) named x must be approximated with a PointMass object. Message passing based algorithms compute posterior marginals as a normalized product of two colliding messages on corresponding edges of a factor graph. In a few words q(x)::PointMass reads as:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"mathrmapproximate q(x) = fracoverrightarrowmu(x)overleftarrowmu(x)int overrightarrowmu(x)overleftarrowmu(x) mathrmdxmathrmasPointMass","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Sometimes it might be useful to set a functional form constraint on messages too. For example if it is essential to keep a specific Gaussian parametrisation or if some messages are intractable and need approximation. To set messages form constraint @constraints macro uses μ(...) instead of q(...):","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: PointMass\n μ(x) :: SampleList(1000)\n # it is possible to assign different form constraints on the same variable \n # both for the marginal and for the messages \nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints macro understands \"stacked\" form constraints. For example the following form constraint","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) :: SampleList(1000) :: PointMass\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"indicates that the q(x) first must be approximated with a SampleList and in addition the result of this approximation should be approximated as a PointMass. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\nNot all combinations of \"stacked\" form constraints are compatible between each other.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"You can find more information about built-in functional form constraint in the Built-in Functional Forms section. In addition, the ReactiveMP library documentation explains the functional form interfaces and shows how to build a custom functional form constraint that is compatible with RxInfer.jl and ReactiveMP.jl inference engine.","category":"page"},{"location":"manuals/constraints-specification/#Factorisation-constraints-on-posterior-distribution-q()","page":"Constraints specification","title":"Factorisation constraints on posterior distribution q()","text":"","category":"section"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model macro specifies generative model p(s, y) where s is a set of random variables and y is a set of observations. In a nutshell the goal of probabilistic programming is to find p(s|y). RxInfer approximates p(s|y) with a proxy distribution q(x) using KL divergence and Bethe Free Energy optimisation procedure. By default there are no extra factorisation constraints on q(s) and the optimal solution is q(s) = p(s|y). However, inference may be not tractable for every model without extra factorisation constraints. To circumvent this, RxInfer.jl and ReactiveMP.jl accept optional factorisation constraints specification syntax:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"For example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a so-called mean-field assumption on variables x and y in the model. Furthermore, if x is an array of variables in our model we may induce extra mean-field assumption on x in the following way.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x) = q(x[begin])..q(x[end])\n q(x, y) = q(x)q(y)\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"These constraints specify a mean-field assumption between variables x and y (either single variable or collection of variables) and additionally specify mean-field assumption on variables x_i.","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"note: Note\n@constraints macro does not support matrix-based collections of variables. E.g. it is not possible to write q(x[begin, begin])..q(x[end, end])","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"It is possible to write more complex factorisation constraints, for example:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints begin \n q(x, y) = q(x[begin], y[begin])..q(x[end], y[end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"specifies a mean-field assumption between collection of variables named x and y only for variables with different indices. Another example is","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@constraints function make_constraints(k)\n q(x) = q(x[begin:k])q(x[k+1:end])\nend","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"In this example we specify a mean-field assumption between a set of variables x[begin:k] and x[k+1:end]. ","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"To create a model with extra constraints the user may pass an optional constraints keyword argument for the create_model function:","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"@model function my_model(arguments...)\n ...\nend\n\nconstraints = @constraints begin \n ...\nend\n\nmodel, returnval = create_model(my_model(arguments...); constraints = constraints)","category":"page"},{"location":"manuals/constraints-specification/","page":"Constraints specification","title":"Constraints specification","text":"Alternatively, it is possible to use constraints directly in the automatic infer function that accepts constraints keyword argument. ","category":"page"},{"location":"contributing/overview/#contributing-overview","page":"Overview","title":"Contributing","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when contributing to this package.","category":"page"},{"location":"contributing/overview/#Reporting-bugs","page":"Overview","title":"Reporting bugs","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We track bugs using GitHub issues. We encourage you to write complete, specific, reproducible bug reports. Mention the versions of Julia and RxInfer for which you observe unexpected behavior. Please provide a concise description of the problem and complement it with code snippets, test cases, screenshots, tracebacks or any other information that you consider relevant. This will help us to replicate the problem and narrow the search space for solutions.","category":"page"},{"location":"contributing/overview/#Nightly-Julia-status","page":"Overview","title":"Nightly Julia status","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The badge that indicates if RxInfer can be installed on a Julia nightly version. The failing badge may indicate either a problem with RxInfer itself of with one if the dependencies. Click on the badge to get the latest evaluation report.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"(Image: PkgEval)","category":"page"},{"location":"contributing/overview/#Suggesting-features","page":"Overview","title":"Suggesting features","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We welcome new feature proposals. However, before submitting a feature request, consider a few things:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Does the feature require changes in the core RxInfer code? If it doesn't (for example, you would like to add a factor node for a particular application), you can add local extensions in your script/notebook or consider making a separate repository for your extensions.\nIf you would like to add an implementation of a feature that changes a lot in the core RxInfer code, please open an issue on GitHub and describe your proposal first. This will allow us to discuss your proposal with you before you invest your time in implementing something that may be difficult to merge later on.","category":"page"},{"location":"contributing/overview/#Contributing-code","page":"Overview","title":"Contributing code","text":"","category":"section"},{"location":"contributing/overview/#Installing-RxInfer","page":"Overview","title":"Installing RxInfer","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We suggest that you use the dev command from the new Julia package manager to install RxInfer for development purposes. To work on your fork of RxInfer, use your fork's URL address in the dev command, for example:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] dev git@github.com:your_username/RxInfer.jl.git","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The dev command clones RxInfer to ~/.julia/dev/RxInfer. All local changes to RxInfer code will be reflected in imported code.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nIt is also might be useful to install Revise.jl package as it allows you to modify code and use the changes without restarting Julia.","category":"page"},{"location":"contributing/overview/#Core-dependencies","page":"Overview","title":"Core dependencies","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl heavily depends on the ReactiveMP.jl, GraphPPL.jl and Rocket.jl packages. RxInfer.jl must be updated every time any of these packages has a major update and/or API changes. Developers are adviced to use the dev command for all of these packages while making changes to the RxInfer.jl. It is worth noting though that standard Julia testing utilities ignore the local development environment and always try to test the package with the latest released versions of the core dependencies. Read the section about the Makefile below to see how to test RxInfer.jl with the locally installed core dependencies.","category":"page"},{"location":"contributing/overview/#Committing-code","page":"Overview","title":"Committing code","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the standard GitHub Flow workflow where all contributions are added through pull requests. In order to contribute, first fork the repository, then commit your contributions to your fork, and then create a pull request on the main branch of the RxInfer repository.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Before opening a pull request, please make sure that all tests pass without failing! All examples (can be found in /examples/ directory) have to run without errors as well. ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make test, make examples and make docs commands to ensure that all tests, examples and the documentation build run without any issues. See below for the Makefile commands description in more details.","category":"page"},{"location":"contributing/overview/#Style-conventions","page":"Overview","title":"Style conventions","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use default Julia style guide. We list here a few important points and our modifications to the Julia style guide:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"Use 4 spaces for indentation\nType names use UpperCamelCase. For example: AbstractFactorNode, RandomVariable, etc..\nFunction names are lowercase with underscores, when necessary. For example: activate!, randomvar, as_variable, etc..\nVariable names and function arguments use snake_case\nThe name of a method that modifies its argument(s) must end in !","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nRxInfer repository contains scripts to automatically format code according to our guidelines. Use make format command to fix code style. This command overwrites files. Use make lint to run a linting procedure without overwriting the actual source files.","category":"page"},{"location":"contributing/overview/#Unit-tests","page":"Overview","title":"Unit tests","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"We use the test-driven development (TDD) methodology for RxInfer development. The test coverage should be as complete as possible. Please make sure that you write tests for each piece of code that you want to add.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"All unit tests are located in the /test/ directory. The /test/ directory follows the structure of the /src/ directory. Each test file should have the following filename format: test_*.jl. Some tests are also present in jldoctest docs annotations directly in the source code. See Julia's documentation about doctests.","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"The tests can be evaluated by running following command in the Julia REPL:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"] test RxInfer","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"In addition tests can be evaluated by running following command in the RxInfer root directory:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make test","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nUse make devtest to use local dev-ed versions of the core packages.","category":"page"},{"location":"contributing/overview/#Makefile","page":"Overview","title":"Makefile","text":"","category":"section"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"RxInfer.jl uses Makefile for most common operations:","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"make help: Shows help snippet\nmake test: Run tests, supports extra arguments\nmake test test_args=\"distributions:normal_mean_variance\" would run tests only from distributions/test_normal_mean_variance.jl\nmake test test_args=\"distributions:normal_mean_variance models:lgssm\" would run tests both from distributions/test_normal_mean_variance.jl and models/test_lgssm.jl\nmake test dev=true would run tests while using dev-ed versions of core packages\nmake devtest: Alias for the make test dev=true ...\nmake docs: Compile documentation\nmake devdocs: Same as make docs, but uses dev-ed versions of core packages\nmake examples: Run all examples and put them in the docs/ folder if successfull \nmake devexamples: Same as make examples, but uses dev-ed versions of core packages\nmake lint: Check codestyle\nmake format: Check and fix codestyle ","category":"page"},{"location":"contributing/overview/","page":"Overview","title":"Overview","text":"note: Note\nCore packages include ReactiveMP.jl, GraphPPL.jl and Rocket.jl. When using any of the dev commands from the Makefile those packages must be present in the Pkg.devdir() directory.","category":"page"},{"location":"contributing/new-release/#contributing-new-release","page":"Publishing a new release","title":"Publishing a new release","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Please read first the general Contributing section. Also, please read the FAQ section in the Julia General registry.","category":"page"},{"location":"contributing/new-release/#Start-the-release-process","page":"Publishing a new release","title":"Start the release process","text":"","category":"section"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"In order to start the release process a person with the associated permissions should: ","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"Open a commit page on GitHub\nWrite the @JuliaRegistrator register comment for the commit:","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"(Image: Release comment)","category":"page"},{"location":"contributing/new-release/","page":"Publishing a new release","title":"Publishing a new release","text":"The Julia Registrator bot should automatically register a request for the new release. Once all checks have passed on the Julia Registrator's side, the new release will be published and tagged automatically.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#examples-solve-gp-regression-by-sde","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"In this notebook, we solve a GP regression problem by using \"Stochastic Differential Equation\" (SDE). This method is well described in the dissertation \"Stochastic differential equation methods for spatio-temporal Gaussian process regression.\" by Arno Solin and \"Sequential Inference for Latent Temporal Gaussian Process Models\" by Jouni Hartikainen. The idea of the method is as follows.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Suppose a function f(x) follows a zero-mean Gaussian Process beginaligned f(x) sim mathcalGP(0 k(xx)) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"When the dimensionality of x is 1, we can consider f(x) as a stochastic process over time, i.e. f(t). For a certain classses of covariance functions, f(t) is a solution to an m-th order linear stochastic differential equation (SDE) beginaligned a_0 f(t) + a_1 fracd f(t)dt + dots + a_m fracd^m f(t)dt^m = w(t) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where w(t) is a zero-mean white noise process with spectral density Q_c. If we define a vector-valued function mathbff(t) = (f(t) ddt f(t)dots d^m-1dt^m-1f(t)), then we can rewrite the above SDE under the companion form","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracd mathbff(t)dt = mathbfF mathbff(t) + mathbfL w(t) quad (1)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfF and mathbfL are defined based on the choice of covariance functions. From (1), we have the following state-space model: beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) quad(2a) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) quad(2b) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where mathbfA_k = exp(mathbfFDelta t_k), with Delta t_k = t_k+1 - t_k, is called the discrete-time state transition matrix, and mathbfQ_k the process noise covariance matrix. For the computation of mathbfQ_k, we will come back later. According to Arno Solin and Jouni Hartikainen's dissertation, the GP regression problem amounts to the inference problem of the above state-space model, and this can be solved by RTS-smoothing. The state-space model starts from the initial state f_0 sim mathcalN(mathbf0 mathbfP_0). For stationary covariance function, the SDE has a stationary state f_infty sim mathcalN(mathbf0 mathbfP_infty), where mathbfP_infty is the solution to beginaligned fracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0 quad (mathrmLyapunov equation) endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"With this stationary condition, the process noise covariance mathbfQ_k is computed as follows beginaligned mathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T endaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"For one-dimensional problem the SDE representation of the GP is defined by the matrices mathbfF mathbfL mathbfQ_c mathbfP_0 and mathbfH. Once we obtain all the matrices, we can do GP regression by implementing RTS-smoothing on the state-space model (2). In this notebook we will particularly use the Matern class of covariance functions for Gaussian Process.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"using RxInfer, Random, Distributions, LinearAlgebra, Plots","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Create-state-space-model-for-GP-regression","page":"Solve GP regression by SDE","title":"Create state space model for GP regression","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Here we create a state-space model beginaligned mathbff_k = mathbfA_k-1 mathbff_k-1 + mathbfq_k-1 quad mathbfq_k-1 sim mathcalN(mathbf0 mathbfQ_k-1) \ny_k = mathbfH mathbff(t_k) + epsilon_k quad epsilon_k sim mathcalN(0 sigma^2_noise) \nendaligned where y_k is the noisy observation of the function f at time t_k, and sigma^2_noise is the noise variance and assumed to be known.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"@model function gp_regression(n, P∞, A, Q, H, σ²_noise)\n f_0 ~ MvNormalMeanCovariance(zeros(length(H)), P∞)\n f = randomvar(n)\n y = datavar(Float64, n) where { allow_missing = true }\n \n f_prev = f_0\n\n for i=1:n\n f[i] ~ MvNormalMeanCovariance(A[i] * f_prev, Q[i])\n y[i] ~ NormalMeanVariance(dot(H , f[i]), σ²_noise)\n f_prev = f[i]\n end\n return f, y\nend","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Generate-data","page":"Solve GP regression by SDE","title":"Generate data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Random.seed!(10)\nn = 100\nσ²_noise = 0.04;\nt = collect(range(-2, 2, length=n)); #timeline\nf_true = sinc.(t); # true process\nf_noisy = f_true + sqrt(σ²_noise)*randn(n); #noisy process\n\npos = sort(randperm(75)[1:2:75]); \nt_obser = t[pos]; # time where we observe data\n\ny_data = Array{Union{Float64,Missing}}(missing, n)\nfor i in pos \n y_data[i] = f_noisy[i]\nend\n\nθ = [1., 1.]; # store [l, σ²]\nΔt = [t[1]]; # time difference\nappend!(Δt, t[2:end] - t[1:end-1]);","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Let's-visualize-our-data","page":"Solve GP regression by SDE","title":"Let's visualize our data","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"plot(t, f_true, label=\"True process f(t)\")\nscatter!(t_obser, y_data[pos], label = \"Noisy observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-3/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-3/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"The Matern is a stationary covariance function and defined as follows beginaligned k(tau) = sigma^2 frac2^1-nuGamma(nu) left(fracsqrt2nutaul right)^nu K_nuleft(fracsqrt2nutaul right) endaligned where beginaligned sigma^2 textthe magnitude scale hyperparameter\nl textthe characteristic length-scale\nnu textthe smoothness hyperparameter\nK_nu() textthe modified Bessel function of the second kind endaligned When we say the Matern-3/2, we mean nu=32. The matrices for the state space model are computed as follows beginaligned mathbfF = beginpmatrix 0 1\n-lambda^2 -2lambda endpmatrix quad quad mathbfL = beginpmatrix 0 1 endpmatrix quad quad mathbfP_infty = beginpmatrix sigma^2 0 0 lambda^2sigma^2 endpmatrix quad quad mathbfH = beginpmatrix 1 0 endpmatrix quad quad Q_c = 4lambda^3sigma^2 endaligned where lambda = fracsqrt3l From these matrices we can define mathbfA_k and mathbfQ_k.","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(3)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 1.];\nH = [1., 0.];\nF = [0. 1.; -λ^2 -2λ]\nP∞ = [θ[2] 0.; 0. (λ^2*θ[2]) ]\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_32 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Covariance-function:-Matern-5/2","page":"Solve GP regression by SDE","title":"Covariance function: Matern-5/2","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Now let's try the Matern-5/2 kernel. The matrices for the SDE representation of the Matern-5/2 are:","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfF = beginpmatrix\n0 1 0\n0 0 1 \n-lambda^3 -3lambda^2 -3lambda\nendpmatrix quad quad mathbfL = beginpmatrix\n0 0 1\nendpmatrix quad quad mathbfH = beginpmatrix\n1 0 0\nendpmatrix quad quad Q_c = frac163 sigma^2 lambda^5 \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where lambda = sqrt5 l. To find mathbfP_infty, we solve the Lyapunov equation","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nfracdmathbfP_inftydt = mathbfF mathbfP_infty + mathbfP_infty mathbfF^T + mathbfL mathbfQ_c mathbfL^T = 0\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"of which the solution is","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nvec(mathbfP_infty) = (mathbfI otimes mathbfF + mathbfFotimesmathbfI)^-1 vec(-mathbfLQ_cmathbfL^T)\nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"where vec() is the vectorization operator and otimes denotes the Kronecker product. Now we can find mathbfA_k and mathbfQ_k ","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfA_k = exp(mathbfFDelta t_k) \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"beginaligned\nmathbfQ_k = mathbfP_infty - mathbfA_k mathbfP_infty mathbfA_k^T \nendaligned","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"λ = sqrt(5)/θ[1];\n#### compute matrices for the state-space model ######\nL = [0., 0., 1.];\nH = [1., 0., 0.];\nF = [0. 1. 0.; 0. 0. 1.;-λ^3 -3λ^2 -3λ]\nQc = 16/3 * θ[2] * λ^5;\n\nI = diageye(3) ; \nvec_P = inv(kron(I,F) + kron(F,I)) * vec(-L * Qc * L'); \nP∞ = reshape(vec_P,3,3);\nA = [exp(F * i) for i in Δt]; \nQ = [P∞ - i*P∞*i' for i in A];","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"result_52 = infer(\n model = gp_regression(n, P∞, A, Q, H, σ²_noise),\n data = (y = y_data,)\n)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"Inference results:\n Posteriors | available for (f, f_0)\n Predictions | available for (y)","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/#Result","page":"Solve GP regression by SDE","title":"Result","text":"","category":"section"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"slicedim(dim) = (a) -> map(e -> e[dim], a)\n\nplot(t, mean.(result_32.posteriors[:f]) |> slicedim(1), ribbon = var.(result_32.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M32\", title = \"Matern-3/2\", legend =false, lw = 2)\nplot!(t, mean.(result_52.posteriors[:f]) |> slicedim(1), ribbon = var.(result_52.posteriors[:f]) |> slicedim(1) .|> sqrt, label =\"Approx. process_M52\",legend = :bottomleft, title = \"GPRegression by SSM\", lw = 2)\nplot!(t, f_true,label=\"true process\", lw = 2)\nscatter!(t_obser, f_noisy[pos], label=\"Observations\")\nxlabel!(\"t\")\nylabel!(\"f(t)\")","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/GP Regression by SSM/","page":"Solve GP regression by SDE","title":"Solve GP regression by SDE","text":"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. ","category":"page"},{"location":"contributing/new-documentation/#guide-docs-contributing","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Contributing to our documentation is a valuable way to enhance the RxInfer ecosystem. To get started, you can follow these steps:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Familiarize Yourself: First, take some time to explore our existing documentation. Understand the structure, style, and content to align your contributions with our standards.\nIdentify Needs: Identify areas that require improvement, clarification, or expansion. These could be missing explanations, code examples, or outdated information.\nFork the Repository: Fork our documentation repository on GitHub to create your own copy. This allows you to work on your changes independently.\nMake Your Edits: Create or modify content in your forked repository. Ensure your contributions are clear, concise, and well-structured.\nSubmit a Pull Request: When you're satisfied with your changes, submit a pull request (PR) to our main repository. Describe your changes in detail in the PR description.\nReview and Feedback: Our documentation maintainers will review your PR. They may provide feedback or request adjustments. Be responsive to this feedback to facilitate the merging process.\nMerging: Once your changes align with our documentation standards, they will be merged into the main documentation. Congratulations, you've successfully contributed to the RxInfer ecosystem!","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"By following these steps, you can play an essential role in improving and expanding our documentation, making it more accessible and valuable to the RxInfer community.","category":"page"},{"location":"contributing/new-documentation/#Use-[LiveServer.jl](https://github.com/tlienart/LiveServer.jl)","page":"Contributing to the documentation","title":"Use LiveServer.jl","text":"","category":"section"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"LiveServer.jl is a simple and lightweight web server developed in Julia. It features live-reload capabilities, making it a valuable tool for automatically refreshing the documentation of a package while you work on its content.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"To use LiveServer.jl, simply follow these steps[1]","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"[1]: Make sure to install the LiveServer and Documenter in your current working environment.","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"Make sure to import the required packages ","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> using LiveServer, Documenter","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"After importing the required packages, you can start the live server with the following command:","category":"page"},{"location":"contributing/new-documentation/","page":"Contributing to the documentation","title":"Contributing to the documentation","text":"julia> servedocs()","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#examples-bayesian-linear-regression-tutorial","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"This notebook is an extensive tutorial on Bayesian linear regression with RxInfer and consists of two major parts:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The first part uses a regular Bayesian Linear Regression on a simple application of fuel consumption for a car with synthetic data.\nThe second part is an adaptation of a tutorial from NumPyro and uses Hierarchical Bayesian linear regression on the OSIC pulmonary fibrosis progression dataset from Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"using RxInfer, Random, Plots, StableRNGs, LinearAlgebra, StatsPlots, LaTeXStrings, DataFrames, CSV, GLM","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-1.-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 1. Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John recently purchased a new car and is interested in its fuel consumption rate. He believes that this rate has a linear relationship with speed, and as such, he wants to conduct tests by driving his car on different types of roads, recording both the fuel usage and speed. In order to determine the fuel consumption rate, John employs Bayesian linear regression.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-known-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with known noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"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_ninmathbbR as a normal distribution and treats x_n as a fixed hyper-parameter:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\np(y_n mid a b) = mathcalN(y_n mid a x_n + b 1)\nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The recorded speed is denoted as x_n in mathbbR and the recorded fuel consumption as y_n in mathbbR. Prior beliefs on a and b are informed by the vehicle manual.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginaligned\n p(a) = mathcalN(a mid m_a v_a) \n p(b) = mathcalN(b mid m_b v_b) \nendaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Together they form the probabilistic model p(y a b) = p(a)p(b) prod_N=1^N p(y_n mid a b) where the goal is to infer the posterior distributions p(a mid y) and p(bmid y).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He records the speed and fuel consumption for the urban road which is the xdata and ydata.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function generate_data(a, b, v, nr_samples; rng=StableRNG(1234))\n x = float.(collect(1:nr_samples))\n y = a .* x .+ b .+ randn(rng, nr_samples) .* sqrt(v)\n return x, y\nend;","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data, y_data = generate_data(0.5, 25.0, 1.0, 250)\n\nscatter(x_data, y_data, title = \"Dataset (City road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In order to estimate the two parameters with the recorded data, he uses a RxInfer.jl to create the above described model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = 1.0)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He is delighted that he can utilize the inference function from this package, saving him the effort of starting from scratch and enabling him to obtain the desired results for this road. He does note that there is a loop in his model, namely all a and b variables are connected over all observations, therefore he needs to initialize one of the messages and run multiple iterations for the loopy belief propagation algorithm. It is worth noting that loopy belief propagation is not guaranteed to converge in general and might be highly influenced by the choice of the initial messages in the initmessages argument. He is going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results = infer(\n model = linear_regression(length(x_data)), \n data = (y = y_data, x = x_data), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast()),\n iterations = 20,\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b)\n Free Energy: | Real[450.062, 8526.84, 4960.42, 2949.02, 1819.14, 1184\n.44, 827.897, 627.595, 515.064, 451.839, 416.313, 396.349, 385.129, 378.821\n, 375.274, 373.279, 372.156, 371.524, 371.167, 370.966]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He knows the theoretical coefficients and noise for this car from the manual. He is going to compare the experimental solution with theoretical results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a\\mid y)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0,Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b)\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"p(b\\mid y)\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"a = results.posteriors[:a]\nb = results.posteriors[:b]\n\nprintln(\"Real a: \", 0.5, \" | Estimated a: \", mean_var(a), \" | Error: \", abs(mean(a) - 0.5))\nprintln(\"Real b: \", 25.0, \" | Estimated b: \", mean_var(b), \" | Error: \", abs(mean(b) - 25.0))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Real a: 0.5 | Estimated a: (0.501490188462706, 1.9162284531300301e-7) | Err\nor: 0.001490188462705988\nReal b: 25.0 | Estimated b: (24.81264210195605, 0.0040159675312827) | Error\n: 0.18735789804394898","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that the loopy belief propagation has actually converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# drop first iteration, which is influenced by the `initmessages`\nplot(2:20, results.free_energy[2:end], title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Univariate-regression-with-unknown-noise","page":"Bayesian Linear Regression Tutorial","title":"Univariate regression with unknown noise","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Afterwards, he plans to test the car on a mountain road. However, mountain roads are typically narrow and filled with small stones, which makes it more difficult to establish a clear relationship between fuel consumption and speed, leading to an unknown level of noise in the regression model. Therefore, he design a model with unknown Inverse-Gamma distribution on the variance. beginaligned p(y_n mid a b s) = mathcalN(y_n mid ax_n + b s)\np(s) = mathcalIG(smidalpha theta)\np(a) = mathcalN(a mid m_a v_a) \np(b) = mathcalN(b mid m_b v_b) endaligned","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_unknown_noise(nr_samples)\n a ~ Normal(mean = 0.0, variance = 1.0)\n b ~ Normal(mean = 0.0, variance = 100.0)\n s ~ InverseGamma(1.0, 1.0)\n \n x = datavar(Float64, nr_samples)\n y = datavar(Float64, nr_samples)\n \n y .~ Normal(mean = a .* x .+ b, variance = s)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_un, y_data_un = generate_data(0.5, 25.0, 400.0, 250)\n\nscatter(x_data_un, y_data_un, title = \"Dateset with unknown noise (mountain road)\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To solve this problem in closed-from we need to resort to a variational approximation. The procedure will be a combination of variational inference and loopy belief propagation. He chooses constraints = MeanField() as a global variational approximation and provides initial marginals with the initmarginals argument. He is, again, going to evaluate the convergency performance of the algorithm with the free_energy = true option:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_unknown_noise = infer(\n model = linear_regression_unknown_noise(length(x_data_un)), \n data = (y = y_data_un, x = x_data_un), \n initmessages = (b = NormalMeanVariance(0.0, 100.0), ), \n returnvars = (a = KeepLast(), b = KeepLast(), s = KeepLast()), \n iterations = 20,\n constraints = MeanField(),\n initmarginals = (s = vague(InverseGamma), ),\n free_energy = true\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, s)\n Free Energy: | Real[1657.49, 1192.08, 1142.31, 1135.43, 1129.19, 1125\n.47, 1123.34, 1122.13, 1121.44, 1121.05, 1120.82, 1120.69, 1120.61, 1120.56\n, 1120.53, 1120.52, 1120.5, 1120.5, 1120.49, 1120.49]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Based on the Bethe free energy below, John knows that his algorithm has converged after 20 iterations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"plot(results_unknown_noise.free_energy, title=\"Free energy\", xlabel=\"Iteration\", ylabel=\"Free energy [nats]\", legend=false)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Below he visualizes the obtained posterior distributions for parameters:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"pra = plot(range(-3, 3, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 1.0), x), title=L\"Prior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(a)$\", c=1,)\npra = vline!(pra, [ 0.5 ], label=L\"True $a$\", c = 3)\npsa = plot(range(0.45, 0.55, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:a], x), title=L\"Posterior for $a$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(a)$\", c=2,)\npsa = vline!(psa, [ 0.5 ], label=L\"True $a$\", c = 3)\n\nplot(pra, psa, size = (1000, 200), xlabel=L\"$a$\", ylabel=L\"$p(a)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(-40, 40, length = 1000), (x) -> pdf(NormalMeanVariance(0.0, 100.0), x), title=L\"Prior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(b)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 25.0 ], label=L\"True $b$\", c = 3)\npsb = plot(range(23, 28, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:b], x), title=L\"Posterior for $b$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(b)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 25.0 ], label=L\"True $b$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$b$\", ylabel=L\"$p(b)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"prb = plot(range(0.001, 400, length = 1000), (x) -> pdf(InverseGamma(1.0, 1.0), x), title=L\"Prior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$p(s)$\", c=1, legend = :topleft)\nprb = vline!(prb, [ 200 ], label=L\"True $s$\", c = 3)\npsb = plot(range(0.001, 400, length = 1000), (x) -> pdf(results_unknown_noise.posteriors[:s], x), title=L\"Posterior for $s$ parameter\", fillalpha=0.3, fillrange = 0, label=L\"$q(s)$\", c=2, legend = :topleft)\npsb = vline!(psb, [ 200 ], label=L\"True $s$\", c = 3)\n\nplot(prb, psb, size = (1000, 200), xlabel=L\"$s$\", ylabel=L\"$p(s)$\", ylims=[0, Inf])","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He sees that in the presence of more noise the inference result is more uncertain about the actual values for a and b parameters.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"John samples a and b and plot many possible regression lines on the same plot:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"as = rand(results_unknown_noise.posteriors[:a], 100)\nbs = rand(results_unknown_noise.posteriors[:b], 100)\np = scatter(x_data_un, y_data_un, title = \"Linear regression with more noise\", legend=false)\nxlabel!(\"Speed\")\nylabel!(\"Fuel consumption\")\nfor (a, b) in zip(as, bs)\n global p = plot!(p, x_data_un, a .* x_data_un .+ b, alpha = 0.05, color = :red)\nend\n\nplot(p, size = (900, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"From this plot John can see that many lines do fit the data well and there is no definite \"best\" answer to the regression coefficients. He realize that most of these lines, however, resemble a similar angle and shift.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Multivariate-linear-regression","page":"Bayesian Linear Regression Tutorial","title":"Multivariate linear regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In addition to fuel consumption, he is also interested in evaluating the car's power performance, braking performance, handling stability, smoothness, and other factors. To investigate the car's performance, he includes additional measurements. Essentially, this approach involves performing multiple linear regression tasks simultaneously, using multiple data vectors for x and y with different levels of noise. As in the previous example, he assumes the level of noise to be unknown.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function linear_regression_multivariate(dim, nr_samples)\n a ~ MvNormal(mean = zeros(dim), covariance = 100 * diageye(dim))\n b ~ MvNormal(mean = ones(dim), covariance = 100 * diageye(dim))\n W ~ InverseWishart(dim + 2, 100 * diageye(dim))\n\n # Here is a small trick to make the example work\n # We treat the `x` vector as a Diagonal matrix such that we can easily multiply it with `a`\n x = datavar(Diagonal{Float64, Vector{Float64}}, nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n z = randomvar(nr_samples)\n\n z .~ x .* a .+ b\n y .~ MvNormal(mean = z, covariance = W)\n\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"After received all the measurement records, he plots the measurements and performance index:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dim_mv = 6\nnr_samples_mv = 50\nrng_mv = StableRNG(42)\na_mv = randn(rng_mv, dim_mv)\nb_mv = 10 * randn(rng_mv, dim_mv)\nv_mv = 100 * rand(rng_mv, dim_mv)\n\nx_data_mv, y_data_mv = collect(zip(generate_data.(a_mv, b_mv, v_mv, nr_samples_mv)...));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft)\n\nplt = palette(:tab10)\n\ndata_set_label = [\"\"]\n\nfor k in 1:dim_mv\n global p = scatter!(p, x_data_mv[k], y_data_mv[k], label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\nxlabel!(L\"$x$\")\nylabel!(L\"$y$\")\np","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Before this data can be used to perform inference, John needs to change its format slightly.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"x_data_mv_processed = map(i -> Diagonal([getindex.(x_data_mv, i)...]), 1:nr_samples_mv)\ny_data_mv_processed = map(i -> [getindex.(y_data_mv, i)...], 1:nr_samples_mv);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"results_mv = infer(\n model = linear_regression_multivariate(dim_mv, nr_samples_mv),\n data = (y = y_data_mv_processed, x = x_data_mv_processed),\n initmarginals = (W = InverseWishart(dim_mv + 2, 10 * diageye(dim_mv)), ),\n initmessages = (b = MvNormalMeanCovariance(ones(dim_mv), 10 * diageye(dim_mv)), ),\n returnvars = (a = KeepLast(), b = KeepLast(), W = KeepLast()),\n free_energy = true,\n iterations = 50,\n constraints = MeanField()\n)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (a, b, W)\n Free Energy: | Real[864.485, 789.026, 769.094, 750.865, 737.67, 724.7\n22, 712.341, 700.865, 690.782, 682.505 … 664.434, 664.434, 664.434, 664.4\n34, 664.434, 664.434, 664.434, 664.434, 664.434, 664.434]","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Again, the algorithm nicely converged, because the Bethe free energy reached a plateau. John also draws the results for the linear regression parameters and sees that the lines very nicely follow the provided data.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p = plot(title = \"Multivariate linear regression\", legend = :topleft, xlabel=L\"$x$\", ylabel=L\"$y$\")\n\n# how many lines to plot\nr = 50\n\ni_a = collect.(eachcol(rand(results_mv.posteriors[:a], r)))\ni_b = collect.(eachcol(rand(results_mv.posteriors[:b], r)))\n\nplt = palette(:tab10)\n\nfor k in 1:dim_mv\n x_mv_k = x_data_mv[k]\n y_mv_k = y_data_mv[k]\n\n for i in 1:r\n global p = plot!(p, x_mv_k, x_mv_k .* i_a[i][k] .+ i_b[i][k], label = nothing, alpha = 0.05, color = plt[k])\n end\n\n global p = scatter!(p, x_mv_k, y_mv_k, label = \"Measurement #$k\", ms = 2, color = plt[k])\nend\n\n# truncate the init step\nf = plot(results_mv.free_energy[2:end], title =\"Bethe free energy convergence\", label = nothing, xlabel = \"Iteration\", ylabel = \"Bethe free energy [nats]\") \n\nplot(p, f, size = (1000, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He needs more iterations to converge in comparison to the very first example, but that is expected since the problem became multivariate and, hence, more difficult.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_a_mv = results_mv.posteriors[:a]\n\nps_a = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $a_{%$k}$\", xlabel=L\"$a_{%$k}$\", ylabel=L\"$p(a_{%$k})$\", xlims = (-1.5,1.5), xticks=[-1.5, 0, 1.5], ylims=[0, Inf])\n\n local m_a_mv_k = mean(i_a_mv)[k]\n local v_a_mv_k = std(i_a_mv)[k, k]\n \n _p = plot!(_p, Normal(m_a_mv_k, v_a_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(a_{%$k})$\", c=2,)\n _p = vline!(_p, [ a_mv[k] ], label=L\"True $a_{%$k}$\", c = 3)\n \n push!(ps_a, _p)\nend\n\nplot(ps_a...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"i_b_mv = results_mv.posteriors[:b]\n\nps_b = []\n\nfor k in 1:dim_mv\n \n local _p = plot(title = L\"Estimated $b_{%$k}$\", xlabel=L\"$b_{%$k}$\", ylabel=L\"$p(b_{%$k})$\", xlims = (-20,20), xticks=[-20, 0, 20], ylims =[0, Inf])\n local m_b_mv_k = mean(i_b_mv)[k]\n local v_b_mv_k = std(i_b_mv)[k, k]\n\n _p = plot!(_p, Normal(m_b_mv_k, v_b_mv_k), fillalpha=0.3, fillrange = 0, label=L\"$q(b_{%$k})$\", c=2,)\n _p = vline!(_p, [ b_mv[k] ], label=L\"Real $b_{%$k}$\", c = 3)\n \n push!(ps_b, _p)\nend\n\nplot(ps_b...)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"He also checks the noise estimation procedure and sees that the noise variance are currently a bit underestimated. Note here that he neglects the covariance terms between the individual elements, which might result in this kind of behaviour.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"scatter(1:dim_mv, v_mv, ylims=(0, 100), label=L\"True $s_d$\")\nscatter!(1:dim_mv, diag(mean(results_mv.posteriors[:W])); yerror=sqrt.(diag(var(results_mv.posteriors[:W]))), label=L\"$\\mathrm{E}[s_d] \\pm \\sigma$\")\nplot!(; xlabel=L\"Dimension $d$\", ylabel=\"Variance\", title=\"Estimated variance of the noise\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Part-2.-Hierarchical-Bayesian-Linear-Regression","page":"Bayesian Linear Regression Tutorial","title":"Part 2. Hierarchical Bayesian Linear Regression","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Disclaimer The tutorial below is an adaptation of the Bayesian Hierarchical Linear Regression tutorial implemented in NumPyro. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The original author in NumPyro is Carlos Souza. Updated by Chris Stoafer in NumPyro. Adapted to RxInfer by Dmitry Bagaev.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Probabilistic Machine Learning models can not only make predictions about future data but also model uncertainty. In areas such as personalized medicine, there might be a large amount of data, but there is still a relatively small amount available for each patient. To customize predictions for each person, it becomes necessary to build a model for each individual — considering its inherent uncertainties — and then couple these models together in a hierarchy so that information can be borrowed from other similar individuals [1].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The purpose of this tutorial is to demonstrate how to implement a Bayesian Hierarchical Linear Regression model using RxInfer. To provide motivation for the tutorial, I will use the OSIC Pulmonary Fibrosis Progression competition, hosted on Kaggle.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# https://www.machinelearningplus.com/linear-regression-in-julia/\n# https://nbviewer.org/github/pyro-ppl/numpyro/blob/master/notebooks/source/bayesian_hierarchical_linear_regression.ipynb","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Understanding-the-Task","page":"Bayesian Linear Regression Tutorial","title":"Understanding the Task","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Pulmonary fibrosis is a disorder characterized by scarring of the lungs, and its cause and cure are currently unknown. In this competition, the objective was to predict the severity of decline in lung function for patients. Lung function is assessed based on the output from a spirometer, which measures the forced vital capacity (FVC), representing the volume of air exhaled.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In medical applications, it is valuable to evaluate a model's confidence in its decisions. As a result, the metric used to rank the teams was designed to reflect both the accuracy and certainty of each prediction. This metric is a modified version of the Laplace Log Likelihood (further details will be provided later).","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's explore the data and delve deeper into the problem involved.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"dataset = CSV.read(\"../data/hbr/osic_pulmonary_fibrosis.csv\", DataFrame);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"describe(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"7×7 DataFrame\n Row │ variable mean min median max \n ⋯\n │ Symbol Union… Any Union… Any \n ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ Patient ID00007637202177411956430 ID004266\n372 ⋯\n 2 │ Weeks 31.8618 -5 28.0 133\n 3 │ FVC 2690.48 827 2641.0 6399\n 4 │ Percent 77.6727 28.8776 75.6769 153.145\n 5 │ Age 67.1885 49 68.0 88 \n ⋯\n 6 │ Sex Female Male\n 7 │ SmokingStatus Currently smokes Never sm\noke\n 3 columns om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"first(dataset, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5×7 DataFrame\n Row │ Patient Weeks FVC Percent Age Sex Sm\noki ⋯\n │ String31 Int64 Int64 Float64 Int64 String7 St\nrin ⋯\n─────┼─────────────────────────────────────────────────────────────────────\n─────\n 1 │ ID00007637202177411956430 -4 2315 58.2536 79 Male Ex\n-sm ⋯\n 2 │ ID00007637202177411956430 5 2214 55.7121 79 Male Ex\n-sm\n 3 │ ID00007637202177411956430 7 2061 51.8621 79 Male Ex\n-sm\n 4 │ ID00007637202177411956430 9 2144 53.9507 79 Male Ex\n-sm\n 5 │ ID00007637202177411956430 11 2069 52.0634 79 Male Ex\n-sm ⋯\n 1 column om\nitted","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The dataset provided us with a baseline chest CT scan and relevant clinical information for a group of patients. Each patient has an image taken at Week = 0, and they undergo numerous follow-up visits over approximately 1-2 years, during which their Forced Vital Capacity (FVC) is measured. For the purpose of this tutorial, we will only consider the Patient ID, the weeks, and the FVC measurements, discarding all other information. Restricting our analysis to these specific columns allowed our team to achieve a competitive score, highlighting the effectiveness of Bayesian hierarchical linear regression models, especially when dealing with uncertainty, which is a crucial aspect of the problem.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Since this is real medical data, the relative timing of FVC measurements varies widely, as shown in the 3 sample patients below:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo(dataset, patient_id) = filter(:Patient => ==(patient_id), dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientinfo (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart(dataset, patient_id; line_kws = true)\n info = patientinfo(dataset, patient_id)\n x = info[!, \"Weeks\"]\n y = info[!, \"FVC\"]\n\n p = plot(tickfontsize = 10, margin = 1Plots.cm, size = (400, 400), titlefontsize = 11)\n p = scatter!(p, x, y, title = patient_id, legend = false, xlabel = \"Weeks\", ylabel = \"FVC\")\n \n if line_kws\n # Use the `GLM.jl` package to estimate linear regression\n linearFormulae = @formula(FVC ~ Weeks)\n linearRegressor = lm(linearFormulae, patientinfo(dataset, patient_id))\n linearPredicted = predict(linearRegressor)\n p = plot!(p, x, linearPredicted, color = :red, lw = 3)\n end\n\n return p\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart(dataset, \"ID00007637202177411956430\")\np2 = patientchart(dataset, \"ID00009637202177434476278\")\np3 = patientchart(dataset, \"ID00010637202177584971671\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"On average, each of the 176 patients provided in the dataset had 9 visits during which their FVC was measured. These visits occurred at specific weeks within the interval [-12, 133]. The decline in lung capacity is evident, but it also varies significantly from one patient to another.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Our task was to predict the FVC measurements for each patient at every possible week within the [-12, 133] interval, along with providing a confidence score for each prediction. In other words, we were required to fill a matrix, as shown below, with the predicted values and their corresponding confidence scores:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The task was ideal for applying Bayesian inference. However, the vast majority of solutions shared within the Kaggle community utilized discriminative machine learning models, disregarding the fact that most discriminative methods struggle to provide realistic uncertainty estimates. This limitation stems from their typical training process, which aims to optimize parameters to minimize certain loss criteria (such as predictive error). As a result, these models do not inherently incorporate uncertainty into their parameters or subsequent predictions. While some methods may produce uncertainty estimates as a by-product or through post-processing steps, these are often heuristic-based and lack a statistically principled approach to estimate the target uncertainty distribution [2].","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modelling:-Bayesian-Hierarchical-Linear-Regression-with-Partial-Pooling","page":"Bayesian Linear Regression Tutorial","title":"Modelling: Bayesian Hierarchical Linear Regression with Partial Pooling","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In a basic linear regression, which is not hierarchical, the assumption is that all FVC decline curves share the same α and β values. This model is known as the \"pooled model.\" On the other extreme, we could assume a model where each patient has a personalized FVC decline curve, and these curves are entirely independent of one another. This model is referred to as the \"unpooled model,\" where each patient has completely separate regression lines.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In this analysis, we will adopt a middle ground approach known as \"Partial pooling.\" Specifically, we will assume that while α's and β's are different for each patient, as in the unpooled case, these coefficients share some similarities. This partial pooling will be achieved by modeling each individual coefficient as being drawn from a common group distribution.:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Mathematically, the model is described by the following equations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n mu_alpha sim mathcalN(mathrmmean = 00 mathrmvariance = 2500000) \n sigma_alpha sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mu_beta sim mathcalN(mathrmmean = 00 mathrmvariance = 90) \n sigma_beta sim mathcalGamma(mathrmshape = 175 mathrmscale = 136) \n alpha_i sim mathcalN(mathrmmean = mu_alpha mathrmprecision = sigma_alpha) \n beta sim mathcalN(mathrmmean = mu_beta mathrmprecision = sigma_beta) \n sigma sim mathcalGamma(mathrmshape = 175 mathrmscale = 4554) \n mathrmFVC_ij sim mathcalN(mathrmmean = alpha_i + t beta_i mathrmprecision = sigma)\n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"where t is the time in weeks. Those are very uninformative priors, but that's ok: our model will converge!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Implementing this model in RxInfer is pretty straightforward:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled(patient_codes, weeks)\n μ_α ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β ~ Normal(mean = 0.0, var = 9.0) # Prior for the mean of β (slope)\n σ_α ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the precision of α (intercept)\n σ_β ~ Gamma(shape = 1.75, scale = 1.36) # Prior for the precision of β (slope)\n\n n_codes = length(patient_codes) # Total number of data points\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α, precision = σ_α) # Sample the intercept α from a Normal distribution\n β[i] ~ Normal(mean = μ_β, precision = σ_β) # Sample the slope β from a Normal distribution\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Prior for the standard deviation of the error term\n \n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes) # Observed FVC measurements\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Variational constraints are used in variational methods to restrict the set of functions or probability distributions that the method can explore during optimization. These constraints help guide the optimization process towards more meaningful and tractable solutions. We need variational constraints to ensure that the optimization converges to valid and interpretable solutions, avoiding solutions that might not be meaningful or appropriate for the given problem. By incorporating constraints, we can control the complexity and shape of the solutions, making them more useful for practical applications. We use the @constraints macro from RxInfer to define approriate variational constraints.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@constraints function partially_pooled_constraints()\n # Assume that `μ_α`, `σ_α`, `μ_β`, `σ_β` and `σ` are jointly independent\n q(μ_α, σ_α, μ_β, σ_β, σ) = q(μ_α)q(σ_α)q(μ_β)q(σ_β)q(σ)\n # Assume that `μ_α`, `σ_α`, `α` are jointly independent\n q(μ_α, σ_α, α) = q(μ_α, α)q(σ_α)\n # Assume that `μ_β`, `σ_β`, `β` are jointly independent\n q(μ_β, σ_β, β) = q(μ_β, β)q(σ_β)\n # Assume that `FVC_est`, `σ` are jointly independent\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"These @constraints assume some structural independencies in the resulting variational approximation. For simplicity we can also use constraints = MeanField() in the inference function below. That's all for modelling!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inference-in-the-model","page":"Bayesian Linear Regression Tutorial","title":"Inference in the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"A significant achievement of Probabilistic Programming Languages, like RxInfer, is the ability to separate model specification and inference. Once I define my generative model with priors, condition statements, and data likelihoods, I can delegate the challenging inference tasks to RxInfer's inference engine.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Calling the inference engine only takes a few lines of code. Before proceeding, let's assign a numerical Patient ID to each patient code, a task that can be easily accomplished using label encoding.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patient_ids = dataset[!, \"Patient\"] # get the column of all patients\npatient_code_encoder = Dict(map(((id, patient), ) -> patient => id, enumerate(unique(patient_ids))));\npatient_code_column = map(patient -> patient_code_encoder[patient], patient_ids)\n\ndataset[!, :PatientCode] = patient_code_column\n\nfirst(patient_code_encoder, 5)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"5-element Vector{Pair{InlineStrings.String31, Int64}}:\n \"ID00197637202246865691526\" => 85\n \"ID00388637202301028491611\" => 160\n \"ID00341637202287410878488\" => 142\n \"ID00020637202178344345685\" => 9\n \"ID00305637202281772703145\" => 127","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_inference(dataset)\n\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n\n results = infer(\n model = partially_pooled(patient_codes, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n σ = vague(Gamma),\n σ_α = vague(Gamma),\n σ_β = vague(Gamma),\n ),\n returnvars = KeepLast(),\n iterations = 100\n )\n \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We use a hybrid message passing approach combining exact and variational inference. In loopy models, where there are cycles or feedback loops in the graphical model, we need to initialize messages to kick-start the message passing process. Messages are passed between connected nodes in the model to exchange information and update beliefs iteratively. Initializing messages provides a starting point for the iterative process and ensures that the model converges to a meaningful solution.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"In variational inference procedures, we need to initialize marginals because variational methods aim to approximate the true posterior distribution with a simpler, tractable distribution. Initializing marginals involves providing initial estimates for the parameters of this approximating distribution. These initial estimates serve as a starting point for the optimization process, allowing the algorithm to iteratively refine the approximation until it converges to a close approximation of the true posterior distribution. ","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_inference_results = partially_pooled_inference(dataset)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Inference results:\n Posteriors | available for (α, σ_α, σ_β, σ, FVC_est, μ_β, μ_α, β)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Checking-the-model","page":"Bayesian Linear Regression Tutorial","title":"Checking the model","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspecting-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspecting the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_α])...)\n local μ_β = Normal(mean_std(partially_pooled_inference_results.posteriors[:μ_β])...)\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n plot(p1, p2, p3, p4, size = (1200, 400), layout = @layout([ a b; c d ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Looks like our model learned personalized alphas and betas for each patient!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Visualizing-FVC-decline-curves-for-some-patients","page":"Bayesian Linear Regression Tutorial","title":"Visualizing FVC decline curves for some patients","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Now, let's visually inspect the FVC decline curves predicted by our model. We will complete the FVC table by predicting all the missing values. To do this, we need to create a table to accommodate the predictions.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function patientchart_bayesian(results, dataset, encoder, patient_id; kwargs...)\n info = patientinfo(dataset, patient_id)\n patient_code_id = encoder[patient_id]\n\n patient_α = results.posteriors[:α][patient_code_id]\n patient_β = results.posteriors[:β][patient_code_id]\n\n estimated_σ = inv(mean(results.posteriors[:σ]))\n \n predict_weeks = range(-12, 134)\n\n predicted = map(predict_weeks) do week\n pm = mean(patient_α) + mean(patient_β) * week\n pv = var(patient_α) + var(patient_β) * week ^ 2 + estimated_σ\n return pm, sqrt(pv)\n end\n \n p = patientchart(dataset, patient_id; kwargs...)\n \n return plot!(p, predict_weeks, getindex.(predicted, 1), ribbon = getindex.(predicted, 2), color = :orange)\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"patientchart_bayesian (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"p1 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\")\np2 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\")\np3 = patientchart_bayesian(partially_pooled_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\")\n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The results match our expectations perfectly! Let's highlight the observations:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model successfully learned Bayesian Linear Regressions! The orange line representing the learned predicted FVC mean closely aligns with the red line representing the deterministic linear regression. More importantly, the model effectively predicts uncertainty, demonstrated by the light orange region surrounding the mean FVC line.\nThe model predicts higher uncertainty in cases where the data points are more dispersed, such as in the 1st and 3rd patients. In contrast, when data points are closely grouped together, as seen in the 2nd patient, the model predicts higher confidence, resulting in a narrower light orange region.\nAdditionally, across all patients, we observe that the uncertainty increases as we look further into the future. The light orange region widens as the number of weeks increases, reflecting the growth of uncertainty over time.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Computing-the-modified-Laplace-Log-Likelihood-and-RMSE","page":"Bayesian Linear Regression Tutorial","title":"Computing the modified Laplace Log Likelihood and RMSE","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"As mentioned earlier, the competition evaluated models using a modified version of the Laplace Log Likelihood, which takes into account both the accuracy and certainty of each prediction—a valuable feature in medical applications.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To compute the metric, we predicted both the FVC value and its associated confidence measure (standard deviation σ). The metric is given by the formula:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"beginequation\n beginaligned\n sigma_mathrmclipped = max(sigma 70) \n delta = min(vert mathrmFVC_mathrmtrue - mathrmFVC_mathrmpredvert 1000) \n mathrmmetric = -fracsqrt2deltasigma_mathrmclipped - mathrmln(sqrt2sigma_mathrmclipped) \n endaligned\nendequation","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"To prevent large errors from disproportionately penalizing results, errors were thresholded at 1000 ml. Additionally, confidence values were clipped at 70 ml to account for the approximate measurement uncertainty in FVC. The final score was determined by averaging the metric across all (Patient, Week) pairs. It is worth noting that metric values will be negative, and a higher score indicates better model performance.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function FVC_predict(results)\n return broadcast(results.posteriors[:FVC_est], Ref(results.posteriors[:σ])) do f, s\n return @call_rule NormalMeanPrecision(:out, Marginalisation) (m_μ = f, q_τ = s)\n end\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"FVC_predict (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function compute_rmse(results, dataset)\n FVC_predicted = FVC_predict(results)\n return mean((dataset[!, \"FVC\"] .- mean.(FVC_predicted)) .^ 2) ^ (1/2)\nend\n\nfunction compute_laplace_log_likelihood(results, dataset)\n FVC_predicted = FVC_predict(results)\n sigma_c = std.(FVC_predicted)\n sigma_c[sigma_c .< 70] .= 70\n delta = abs.(mean.(FVC_predicted) .- dataset[!, \"FVC\"])\n delta[delta .> 1000] .= 1000\n return mean(-sqrt(2) .* delta ./ sigma_c .- log.(sqrt(2) .* sigma_c))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"compute_laplace_log_likelihood (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.0313266260767\nLaplace Log Likelihood: -6.15689374755478","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"What do these numbers signify? They indicate that adopting this approach would lead to outperforming the majority of public solutions in the competition. In several seconds of inference!","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Interestingly, most public solutions rely on a standard deterministic Neural Network and attempt to model uncertainty through a quantile loss, adhering to a frequentist approach. The importance of uncertainty in single predictions is growing in the field of machine learning, becoming a crucial requirement. Especially when the consequences of an inaccurate prediction are significant, knowing the probability distribution of individual predictions becomes essential.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Add-layer-to-model-hierarchy:-Smoking-Status","page":"Bayesian Linear Regression Tutorial","title":"Add layer to model hierarchy: Smoking Status","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We can enhance the model by incorporating the column \"SmokingStatus\" as a pooling level, where model parameters will be partially pooled within the groups \"Never smoked,\" \"Ex-smoker,\" and \"Currently smokes.\" To achieve this, we need to:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Encode the \"SmokingStatus\" column. Map the patient encoding to the corresponding \"SmokingStatus\" encodings. Refine and retrain the model with the additional hierarchical structure.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"combine(groupby(dataset, \"SmokingStatus\"), nrow)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"3×2 DataFrame\n Row │ SmokingStatus nrow\n │ String31 Int64\n─────┼─────────────────────────\n 1 │ Ex-smoker 1038\n 2 │ Never smoked 429\n 3 │ Currently smokes 82","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping = Dict(map(((code, smoking_status), ) -> smoking_status => code, enumerate(unique(dataset[!, \"SmokingStatus\"]))))\nsmoking_code_encoder = Dict(map(unique(values(patient_ids))) do patient_id\n smoking_status = first(unique(patientinfo(dataset, patient_id)[!, \"SmokingStatus\"]))\n return patient_code_encoder[patient_id] => smoking_id_mapping[smoking_status]\nend)\n\nsmoking_status_patient_mapping = map(id -> smoking_code_encoder[id], 1:length(unique(patient_ids)));","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"@model function partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks)\n μ_α_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of α (intercept)\n μ_β_global ~ Normal(mean = 0.0, var = 250000.0) # Prior for the mean of β (slope)\n σ_α_global ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n σ_β_global ~ Gamma(shape = 1.75, scale = 1.36) # Corresponds to half-normal with scale 3.0\n\n n_codes = length(patient_codes) # Total number of data points\n n_smoking_statuses = length(unique(smoking_status_patient_mapping)) # Number of different smoking patterns\n n_patients = length(unique(patient_codes)) # Number of unique patients in the data\n\n μ_α_smoking_status = randomvar(n_smoking_statuses) # Individual intercepts for smoking pattern\n μ_β_smoking_status = randomvar(n_smoking_statuses) # Individual slopes for smoking pattern\n \n for i in 1:n_smoking_statuses\n μ_α_smoking_status[i] ~ Normal(mean = μ_α_global, precision = σ_α_global)\n μ_β_smoking_status[i] ~ Normal(mean = μ_β_global, precision = σ_β_global)\n end\n \n α = randomvar(n_patients) # Individual intercepts for each patient\n β = randomvar(n_patients) # Individual slopes for each patient\n\n for i in 1:n_patients\n α[i] ~ Normal(mean = μ_α_smoking_status[smoking_status_patient_mapping[i]], precision = σ_α_global)\n β[i] ~ Normal(mean = μ_β_smoking_status[smoking_status_patient_mapping[i]], precision = σ_β_global)\n end\n\n σ ~ Gamma(shape = 1.75, scale = 45.54) # Corresponds to half-normal with scale 100.0\n\n FVC_est = randomvar(n_codes)\n data = datavar(Int, n_codes)\n\n for i in 1:n_codes\n FVC_est[i] ~ α[patient_codes[i]] + β[patient_codes[i]] * weeks[i] # FVC estimation using patient-specific α and β\n data[i] ~ Normal(mean = FVC_est[i], precision = σ) # Likelihood of the observed FVC data\n end\n \nend\n\n@constraints function partially_pooled_with_smooking_constraints()\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)\n q(μ_α_smoking_status, μ_β_smoking_status, σ_α_global, σ_β_global) = q(μ_α_smoking_status)q(μ_β_smoking_status)q(σ_α_global)q(σ_β_global)\n q(μ_α_global, σ_α_global, μ_β_global, σ_β_global, σ) = q(μ_α_global)q(σ_α_global)q(μ_β_global)q(σ_β_global)q(σ)\n q(μ_α_global, σ_α_global, α) = q(μ_α_global, α)q(σ_α_global)\n q(μ_β_global, σ_β_global, β) = q(μ_β_global, β)q(σ_β_global)\n q(FVC_est, σ) = q(FVC_est)q(σ) \nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smooking_constraints (generic function with 1 method)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"function partially_pooled_with_smoking(dataset, smoking_status_patient_mapping)\n patient_codes = values(dataset[!, \"PatientCode\"])\n weeks = values(dataset[!, \"Weeks\"])\n FVC_obs = values(dataset[!, \"FVC\"]);\n \n return infer(\n model = partially_pooled_with_smoking(patient_codes, smoking_status_patient_mapping, weeks),\n data = (data = FVC_obs, ),\n options = (limit_stack_depth = 500, ),\n constraints = partially_pooled_with_smooking_constraints(),\n initmessages = (\n α = vague(NormalMeanVariance),\n β = vague(NormalMeanVariance),\n ),\n initmarginals = (\n σ = Gamma(1.75, 45.54),\n σ_α_global = Gamma(1.75, 45.54),\n σ_β_global = Gamma(1.75, 1.36),\n ),\n returnvars = KeepLast(),\n iterations = 100,\n )\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking (generic function with 2 methods)","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"partially_pooled_with_smoking_inference_results = partially_pooled_with_smoking(dataset, smoking_status_patient_mapping);","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Inspect-the-learned-parameters","page":"Bayesian Linear Regression Tutorial","title":"Inspect the learned parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Convert to `Normal` since it supports easy plotting with `StatsPlots`\nlet \n local μ_α = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_α_global])...)\n local μ_β = Normal(mean_std(partially_pooled_with_smoking_inference_results.posteriors[:μ_β_global])...)\n local αsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_α_smoking_status])\n local βsmoking = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status])\n local α = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:α])\n local β = map(d -> Normal(mean_std(d)...), partially_pooled_with_smoking_inference_results.posteriors[:β])\n \n local p1 = plot(μ_α, title = \"q(μ_α_global)\", fill = 0, fillalpha = 0.2, label = false)\n local p2 = plot(μ_β, title = \"q(μ_β_global)\", fill = 0, fillalpha = 0.2, label = false)\n \n local p3 = plot(title = \"q(α)...\", legend = false)\n local p4 = plot(title = \"q(β)...\", legend = false)\n \n foreach(d -> plot!(p3, d), α) # Add each individual `α` on plot `p3`\n foreach(d -> plot!(p4, d), β) # Add each individual `β` on plot `p4`\n \n local p5 = plot(title = \"q(μ_α_smoking_status)...\", legend = false)\n local p6 = plot(title = \"q(μ_β_smoking_status)...\", legend = false)\n \n foreach(d -> plot!(p5, d, fill = 0, fillalpha = 0.2), αsmoking) \n foreach(d -> plot!(p6, d, fill = 0, fillalpha = 0.2), βsmoking)\n \n plot(p1, p2, p3, p4, p5, p6, size = (1200, 600), layout = @layout([ a b; c d; e f ]))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Interpret-smoking-status-model-parameters","page":"Bayesian Linear Regression Tutorial","title":"Interpret smoking status model parameters","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"The model parameters for each smoking status reveal intriguing findings, particularly concerning the trend, μ_β_smoking_status. In the summary below, it is evident that the trend for current smokers has a positive mean, while the trend for ex-smokers and those who have never smoked is negative.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"smoking_id_mapping","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Dict{InlineStrings.String31, Int64} with 3 entries:\n \"Currently smokes\" => 3\n \"Ex-smoker\" => 1\n \"Never smoked\" => 2","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"posteriors_μ_β_smoking_status = partially_pooled_with_smoking_inference_results.posteriors[:μ_β_smoking_status]\n\nprintln(\"Trend for\")\nforeach(pairs(smoking_id_mapping)) do (key, id)\n println(\" $key: $(mean(posteriors_μ_β_smoking_status[id]))\")\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Trend for\n Currently smokes: 1.8157457671008241\n Ex-smoker: -4.56516461765951\n Never smoked: -4.446729680170274","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Let's look at these curves for individual patients to help interpret these model results.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"# Never smoked\np1 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00007637202177411956430\") \n# Ex-smoker\np2 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00009637202177434476278\") \n# Currently smokes\np3 = patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, \"ID00011637202177653955184\") \n\nplot(p1, p2, p3, layout = @layout([ a b c ]), size = (1200, 400))","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Review-patients-that-currently-smoke","page":"Bayesian Linear Regression Tutorial","title":"Review patients that currently smoke","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"When plotting each patient with the smoking status \"Currently smokes,\" we observe different trends. Some patients show a clear positive trend, while others do not exhibit a clear trend or even have a negative trend. Compared to the unpooled trend lines, the trend lines with partial pooling are less prone to overfitting and display greater uncertainty in both slope and intercept.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Depending on the purpose of the model, we can proceed in different ways:","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"If our goal is to gain insights into how different attributes relate to a patient's FVC over time, we can stop here and understand that current smokers might experience an increase in FVC over time when monitored for Pulmonary Fibrosis. We may then formulate hypotheses to explore the reasons behind this observation and design new experiments for further testing.\nHowever, if our aim is to develop a model for generating predictions to treat patients, it becomes crucial to ensure that the model does not overfit and can be trusted with new patients. To achieve this, we could adjust model parameters to shrink the \"Currently smokes\" group's parameters closer to the global parameters, or even consider merging the group with \"Ex-smokers.\" Additionally, collecting more data for current smokers could help in ensuring the model's robustness and preventing overfitting.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"let \n local plots = []\n\n for (i, patient) in enumerate(unique(filter(:SmokingStatus => ==(\"Currently smokes\"), dataset)[!, \"Patient\"]))\n push!(plots, patientchart_bayesian(partially_pooled_with_smoking_inference_results, dataset, patient_code_encoder, patient))\n end\n\n plot(plots..., size = (1200, 1200))\nend","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#Modified-Laplace-Log-Likelihood-and-RMSE-for-model-with-Smoking-Status-Level","page":"Bayesian Linear Regression Tutorial","title":"Modified Laplace Log Likelihood and RMSE for model with Smoking Status Level","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"We calculate the metrics for the updated model and compare to the original model.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"println(\"RMSE: $(compute_rmse(partially_pooled_with_smoking_inference_results, dataset))\")\nprintln(\"Laplace Log Likelihood: $(compute_laplace_log_likelihood(partially_pooled_with_smoking_inference_results, dataset))\")","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"RMSE: 124.7845980866563\nLaplace Log Likelihood: -6.165346437287973","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"Both the Laplace Log Likelihood and RMSE indicate slightly worse performance for the smoking status model. Adding this hierarchy level as it is did not improve the model's performance significantly. However, we did discover some interesting results from the smoking status level that might warrant further investigation. Additionally, we could attempt to enhance model performance by adjusting priors or exploring different hierarchy levels, such as gender.","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/#References","page":"Bayesian Linear Regression Tutorial","title":"References","text":"","category":"section"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[1] Ghahramani, Z. Probabilistic machine learning and artificial intelligence. Nature 521, 452–459 (2015). https://doi.org/10.1038/nature14541","category":"page"},{"location":"examples/basic_examples/Bayesian Linear Regression Tutorial/","page":"Bayesian Linear Regression Tutorial","title":"Bayesian Linear Regression Tutorial","text":"[2] Rainforth, Thomas William Gamlen. Automating Inference, Learning, and Design Using Probabilistic Programming. University of Oxford, 2017.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#examples-probit-model-(ep)","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"RxInfer comes with support for expectation propagation (EP). In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model. Here, the probit function links continuous variable x_t with the discrete variable y_t. The model is defined as:","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"beginaligned\n u = 01 \n x_0 sim mathcalN(0 100) \n x_t sim mathcalN(x_t-1+ u 001) \n y_t sim mathrmBer(Phi(x_t))\nendaligned","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Import-packages","page":"Probit Model (EP)","title":"Import packages","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"using RxInfer, StableRNGs, Random, Plots\nusing StatsFuns: normcdf","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Data-generation","page":"Probit Model (EP)","title":"Data generation","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n \n # hyper parameters\n u = 0.1\n\n # allocate space for data\n data_x = zeros(nr_samples + 1)\n data_y = zeros(nr_samples)\n \n # initialize data\n data_x[1] = -2\n \n # generate data\n for k = 2:nr_samples + 1\n \n # calculate new x\n data_x[k] = data_x[k-1] + u + sqrt(0.01)*randn(rng)\n \n # calculate y\n data_y[k-1] = normcdf(data_x[k]) > rand(rng)\n \n end\n \n # return data\n return data_x, data_y\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"n = 40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"40","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"data_x, data_y = generate_data(n);","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"p = plot(xlabel = \"t\", ylabel = \"x, y\")\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\")","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Model-specification","page":"Probit Model (EP)","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"@model function probit_model(nr_samples::Int64)\n \n # allocate space for variables\n x = randomvar(nr_samples + 1)\n y = datavar(Float64, nr_samples)\n \n # specify uninformative prior\n x[1] ~ Normal(mean = 0.0, precision = 0.01)\n \n # create model \n for k = 2:nr_samples + 1\n x[k] ~ Normal(mean = x[k - 1] + 0.1, precision = 100)\n y[k - 1] ~ Probit(x[k]) where {\n # Probit node by default uses RequireMessage pipeline with vague(NormalMeanPrecision) message as initial value for `in` edge\n # To change initial value use may specify it manually, like. Changes to the initial message may improve stability in some situations\n pipeline = RequireMessage(in = NormalMeanPrecision(0, 0.01)) \n }\n end\n \nend;","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Inference","page":"Probit Model (EP)","title":"Inference","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"result = infer(\n model = probit_model(length(data_y)), \n data = (y = data_y, ), \n iterations = 5, \n returnvars = (x = KeepLast(),),\n free_energy = true\n)","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"Inference results:\n Posteriors | available for (x)\n Free Energy: | Real[23.1779, 15.743, 15.6467, 15.6462, 15.6462]","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/#Results","page":"Probit Model (EP)","title":"Results","text":"","category":"section"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"mx = result.posteriors[:x]\n\np = plot(xlabel = \"t\", ylabel = \"x, y\", legend = :bottomright)\np = scatter!(p, data_y, label = \"y\")\np = plot!(p, data_x[2:end], label = \"x\", lw = 2)\np = plot!(mean.(mx)[2:end], ribbon = std.(mx)[2:end], fillalpha = 0.2, label=\"x (inferred mean)\")\n\nf = plot(xlabel = \"t\", ylabel = \"BFE\")\nf = plot!(result.free_energy, label = \"Bethe Free Energy\")\n\nplot(p, f, size = (800, 400))","category":"page"},{"location":"examples/problem_specific/Probit Model (EP)/","page":"Probit Model (EP)","title":"Probit Model (EP)","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#examples-advanced-tutorial","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This notebook covers the fundamentals and advanced usage of the RxInfer.jl package.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"This tutorial is also available in the documentation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#General-model-specification-syntax","page":"Advanced Tutorial","title":"General model specification syntax","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We use the @model macro from the RxInfer.jl package to create a probabilistic model p(s y) and we also specify extra constraints on the variational family of distributions mathcalQ, used for approximating intractable posterior distributions. Below there is a simple example of the general syntax for model specification. In this tutorial we do not cover all possible ways to create models or advanced features of RxInfer.jl. Instead we refer the interested reader to the documentation for a more rigorous explanation and illustrative examples.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `@model` macro accepts a regular Julia function\n@model function test_model1(s_mean, s_precision)\n \n # We use the `randomvar` function to create \n # a random variable in our model\n s = randomvar()\n \n # the `tilde` operator creates a functional dependency\n # between variables in our model and can be read as \n # `sampled from` or `is modeled by`\n s ~ Normal(mean = s_mean, precision = s_precision)\n \n # We use the `datavar` function to create \n # observed data variables in our models\n # We also need to specify the type of our data \n # In this example it is `Float64`\n y = datavar(Float64)\n \n y ~ Normal(mean = s, precision = 1.0)\n \n # It is possible to return something from the model specification (including variables and nodes)\n return \"Hello world\"\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @model macro creates a function with the same name and with the same set of input arguments as the original function (test_model1(s_mean, s_precision) in this example). The return value is modified in such a way to contain a reference to the model object as the first value and to the user specified variables in the form of a tuple as the second value.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"modelgenerator = test_model1(0.0, 1.0)\n\nmodel, returnval = create_model(modelgenerator)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(FactorGraphModel(), \"Hello world\")","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The benefits of using model generator as a way to create a model is that it allows to change inference constraints and meta specification for nodes. We will talk about factorisation and form constraints and meta specification later on in this demo.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl returns a factor graph-based representation of a model. We can examine this factor graph structure with the help of some utility functions such as: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(): returns an array of factor nodes in a corresponding factor graph\ngetrandom(): returns an array of random variables in the model\ngetdata(): returns an array of data inputs in the model\ngetconstant(): returns an array of constant values in the model","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getnodes(model)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"FactorNodesCollection(nodes: 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getrandom(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :s","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getdata(model) .|> name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Symbol}:\n :y","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getconstant(model) .|> getconst","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"3-element Vector{Float64}:\n 0.0\n 1.0\n 1.0","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use control flow statements such as if or for blocks in the model specification function. In general, any valid snippet of Julia code can be used inside the @model block. As an example consider the following (valid!) model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model2(n)\n \n if n <= 1\n error(\"`n` argument must be greater than one.\")\n end\n \n # `randomvar(n)` creates a dense sequence of \n # random variables\n s = randomvar(n)\n \n # `datavar(Float64, n)` creates a dense sequence of \n # observed data variables of type `Float64`\n y = datavar(Float64, n)\n \n s[1] ~ Normal(mean = 0.0, precision = 0.1)\n y[1] ~ Normal(mean = s[1], precision = 1.0)\n \n for i in 2:n\n s[i] ~ Normal(mean = s[i - 1], precision = 1.0)\n y[i] ~ Normal(mean = s[i], precision = 1.0)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, _ = create_model(test_model2(10));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of factor nodes in generated Factor Graph\ngetnodes(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"20","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of random variables\ngetrandom(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of data inputs\ngetdata(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# An amount of constant values\ngetconstant(model) |> length","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"21","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use complex expressions inside the functional dependency expressions","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y ~ NormalMeanPrecision(2.0 * (s + 1.0), 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ operator automatically creates a random variable if none was created before with the same name and throws an error if this name already exists","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# s = randomvar() here is optional\n# `~` creates random variables automatically\ns ~ NormalMeanPrecision(0.0, 1.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example model which will throw an error:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function error_model1()\n s = 1.0\n s ~ NormalMeanPrecision(0.0, 1.0)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default the RxInfer.jl package creates new references for constants (literals like 0.0 or 1.0) in a model. In some situations this may not be efficient, especially when these constants represent large matrices. RxInfer.jl will by default create new copies of some constant (e.g. matrix) in a model every time it uses it. However it is possible to use constvar() function to create and reuse similar constants in the model specification syntax as","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Creates constant reference in a model with a prespecified value\nc = constvar(0.0)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"An example:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model5(dim::Int, n::Int, A::Matrix, P::Matrix, Q::Matrix)\n \n s = randomvar(n)\n \n y = datavar(Vector{Float64}, n)\n \n # Here we create constant references\n # for constant matrices in our model \n # to make inference more memory efficient\n cA = constvar(A)\n cP = constvar(P)\n cQ = constvar(Q)\n \n s[1] ~ MvNormal(mean = zeros(dim), covariance = cP)\n y[1] ~ MvNormal(mean = s[1], covariance = cQ)\n \n for i in 2:n\n s[i] ~ MvNormal(mean = cA * s[i - 1], covariance = cP)\n y[i] ~ MvNormal(mean = s[i], covariance = cQ)\n end\n \nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The ~ expression can also return a reference to a newly created node in a corresponding factor graph for convenience in later usage:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n\n # In this example `ynode` refers to the corresponding \n # `GaussianMeanVariance` node created in the factor graph\n ynode, y ~ GaussianMeanVariance(0.0, 1.0)\n \n return ynode, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Probabilistic-inference-in-RxInfer.jl","page":"Advanced Tutorial","title":"Probabilistic inference in RxInfer.jl","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl uses the Rocket.jl package API for inference routines. Rocket.jl is a reactive programming extension for Julia that is higly inspired by RxJS and similar libraries from the Rx ecosystem. It consists of observables, actors, subscriptions and operators. For more information and rigorous examples see Rocket.jl github page.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Observables","page":"Advanced Tutorial","title":"Observables","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Observables are lazy push-based collections and they deliver their values over time.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Timer that emits a new value every second and has an initial one second delay \nobservable = timer(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerObservable(300, 300)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"A subscription allows us to subscribe on future values of some observable, and actors specify what to do with these new values:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"actor = (value) -> println(value)\nsubscription1 = subscribe!(observable, actor)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We always need to unsubscribe from some observables\nunsubscribe!(subscription1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# We can modify our observables\nmodified = observable |> filter(d -> rem(d, 2) === 1) |> map(Int, d -> d ^ 2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Int64, MapProxy(Int64))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscription2 = subscribe!(modified, (value) -> println(value))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"TimerSubscription()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(subscription2)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n \n # We assume that the outcome of each coin flip \n # is modeled by a Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during the inference step\n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can call the inference function to run inference in such model:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"p = 0.75 # Bias of a coin\n\ndataset = float.(rand(Bernoulli(p), 500));\n\nresult = infer(\n model = coin_toss_model(length(dataset)),\n data = (y = dataset, )\n)\n\nprintln(\"Inferred bias: \", mean_var(result.posteriors[:θ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inferred bias: (0.7642436149312377, 0.0003532849254275917)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"We can see that the inferred bias is quite close to the actual value we used in the dataset generation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The RxInfer.jl package's API is more flexible (and reactive!) and can return posterior marginal distributions in our specified model in the form of an observable. It is possible to subscribe on its future updates, but for convenience RxInfer.jl only caches the last obtained values of all marginals in a model. To get a reference for the posterior marginal of some random variable in a model RxInfer.jl exports two functions: ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getmarginal(x): for a single random variable x\ngetmarginals(xs): for a dense sequence of random variables sx","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let's see how it works in practice. Here we create a simple coin toss model. We assume that observations are governed by the Bernoulli distribution with unknown bias parameter θ. To have a fully Bayesian treatment of this problem we endow θ with the Beta prior.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = create_model(coin_toss_model(length(dataset)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# As soon as we have a new value for the marginal posterior over the `θ` variable\n# we simply print the first two statistics of it\nθ_subscription = subscribe!(getmarginal(θ), (marginal) -> println(\"New update: mean(θ) = \", mean(marginal), \", std(θ) = \", std(marginal)));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To pass data to our model we use update! function","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"New update: mean(θ) = 0.7642436149312377, std(θ) = 0.018795875223771616","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It is necessary to always unsubscribe from running observables\nunsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# The ReactiveMP.jl inference backend is lazy and does not compute posterior marginals if no-one is listening for them\n# At this moment we have already unsubscribed from the new posterior updates so this `update!` does nothing\nupdate!(y, dataset)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Rocket.jl provides some useful built-in actors for obtaining posterior marginals especially with static datasets.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `keep` actor simply keeps all incoming updates in an internal storage, ordered\nθvalues = keep(Marginal)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"KeepActor{Marginal}(Marginal[])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `getmarginal` always emits last cached value as its first value\nsubscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=389.0, β=120.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginal(θ) |> take(1), θvalues);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θvalues)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"2-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=389.0, β=120.0))\n Marginal(Beta{Float64}(α=389.0, β=120.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# the `buffer` actor keeps very last incoming update in an internal storage and can also store \n# an array of updates for a sequence of random variables\nθbuffer = buffer(Marginal, 1)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"BufferActor{Marginal, Vector{Marginal}}(Marginal[#undef])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=389.0, β=120.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"subscribe!(getmarginals([ θ ]) |> take(1), θbuffer);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(θbuffer)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"1-element Vector{Marginal}:\n Marginal(Beta{Float64}(α=389.0, β=120.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Reactive-Online-Inference","page":"Advanced Tutorial","title":"Reactive Online Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl naturally supports reactive streams of data and it is possible to run reactive inference with some external datasource.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function online_coin_toss_model()\n \n # We create datavars for the prior \n # over `θ` variable\n θ_a = datavar(Float64)\n θ_b = datavar(Float64)\n \n θ ~ Beta(θ_a, θ_b)\n \n y = datavar(Float64)\n y ~ Bernoulli(θ)\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"autoupdates = @autoupdates begin \n θ_a, θ_b = params(q(θ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(θ_a,θ_b = params(q(θ)),)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"rxresult = infer(\n model = online_coin_toss_model(),\n data = (y = dataset, ),\n autoupdates = autoupdates,\n historyvars = (θ = KeepLast(), ),\n keephistory = length(dataset),\n initmarginals = (\n θ = vague(Beta),\n ),\n autostart = true\n);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"animation = @animate for i in 1:length(dataset)\n plot(mean.(rxresult.history[:θ][1:i]), ribbon = std.(rxresult.history[:θ][1:i]), title = \"Online coin bias inference\", label = \"Inferred bias\", legend = :bottomright)\n hline!([ p ], label = \"Real bias\", size = (600, 200))\nend\n\ngif(animation, \"../pics/online-coin-bias-inference.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we used static dataset and the history field of the reactive inference result, but the rxinference function also supports any real-time reactive stream and can run indefinitely.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"That was an example of exact Bayesian inference with Sum-Product (or Belief Propagation) algorithm. However, RxInfer is not limited to only the sum-product algorithm but it also supports variational message passing with Constrained Bethe Free Energy Minimisation.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Variational-inference","page":"Advanced Tutorial","title":"Variational inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"On a very high-level, ReactiveMP.jl is aimed to solve the Constrained Bethe Free Energy minimisation problem. For this task we approximate our exact posterior marginal distribution by some family of distributions q in mathcalQ. Often this involves assuming some factorization over q. For this purpose the @model macro supports optional where { ... } clauses for every ~ expression in a model specification.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_a for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"There are several options to specify the mean-field factorisation constraint. ","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i])q(μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out)q(mean)q(precision) } # With names from node specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = MeanField() } # With alias name","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to use local structured factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"y[i] ~ NormalMeanPrecision(μ, τ) where { q = q(y[i], μ)q(τ) } # With names from model specification\ny[i] ~ NormalMeanPrecision(μ, τ) where { q = q(out, mean)q(precision) } # With names from node specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-constraints-macro","page":"Advanced Tutorial","title":"RxInfer.jl constraints macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl package exports @constraints macro to simplify factorisation and form constraints specification. Read more about @constraints macro in the corresponding documentation section, here we show a simple example of the same factorisation constraints specification, but with @constraints macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints6 = @constraints begin\n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: where blocks have higher priority over constraints specification","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model6(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n # Here we assume a mean-field assumption on our \n # variational family of distributions locally for the current node\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Inference","page":"Advanced Tutorial","title":"Inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To run inference in this model we again need to create a synthetic dataset:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"dataset = rand(Normal(-3.0, inv(sqrt(5.0))), 1000);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#inference-function","page":"Advanced Tutorial","title":"inference function","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to simplify model and inference testing, RxInfer.jl exports pre-written inference function, that is aimed for simple use cases with static datasets:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Use ?inference to quickly check the documentation for the inference function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"result = infer(\n model = test_model6(length(dataset)),\n data = (y = dataset, ),\n constraints = constraints6, \n initmarginals = (μ = vague(NormalMeanPrecision), τ = vague(GammaShapeRate)),\n returnvars = (μ = KeepLast(), τ = KeepLast()),\n iterations = 10,\n free_energy = true,\n showprogress = true\n)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Inference results:\n Posteriors | available for (μ, τ)\n Free Energy: | Real[14763.3, 3275.55, 643.409, 599.743, 599.742, 599.\n742, 599.742, 599.742, 599.742, 599.742]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(result.posteriors[:μ]), \", std = \", std(result.posteriors[:μ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -2.9941782279022204, std = 0.013832445627312158","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(result.posteriors[:τ]), \", std = \", std(result.posteriors[:τ]))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 5.226382915400179, std = 0.23349756856917872","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Manual-inference","page":"Advanced Tutorial","title":"Manual inference","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For advanced use cases it is advised to write inference functions manually as it provides more flexibility, here is an example of manual inference specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"For variational inference we also usually need to set initial marginals for our inference procedure. For that purpose ReactiveMP inference engine export the setmarginal! function:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-3.0001723247568237e-9, w\n=0.010000001002000566))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-27.485015477021832, w=9.\n189467886050704))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-9988.618014104622, w=333\n6.0167911607655))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15639.907122824821, w=52\n23.438936935284))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.743045696663, w=52\n26.389965662661))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751868939184, w=52\n26.392912456405))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877744757, w=52\n26.392915397171))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877753584, w=52\n26.392915400165))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877753579, w=52\n26.392915400165))\n Marginal(NormalWeightedMeanPrecision{Float64}(xi=-15648.751877753586, w=52\n26.392915400165))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"10-element Vector{Marginal}:\n Marginal(GammaShapeRate{Float64}(a=501.0, b=5.0000000000457825e14))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=54578.32700317227))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=150.17955039164815))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.91400707251834))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85985008582941))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.8597960371289))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85979598318833))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85979598313438))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.8597959831344))\n Marginal(GammaShapeRate{Float64}(a=501.0, b=95.85979598313433))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"μ: mean = \", mean(last(μ_values)), \", std = \", std(last(μ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ: mean = -2.9941782279022204, std = 0.013832445627312158","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"println(\"τ: mean = \", mean(last(τ_values)), \", std = \", std(last(τ_values)))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"τ: mean = 5.226382915400179, std = 0.23349756856917872","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Form-constraints","page":"Advanced Tutorial","title":"Form constraints","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In order to support form constraints, the randomvar() function also supports a where { ... } clause with some optional arguments. One of these arguments is form_constraint that allows us to specify a form constraint to the random variables in our model. Another one is prod_constraint that allows to specify an additional constraints during computation of product of two colliding messages. For example we can perform the EM algorithm if we assign a point mass contraint on some variables in our model.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7_with_manual_constraints(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar() where { marginal_form_constraint = PointMassFormConstraint() }\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ) where { q = q(y[i])q(μ)q(τ) }\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"As in the previous example we can use @constraints macro to achieve the same goal with a nicer syntax:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"constraints7 = @constraints begin \n q(μ) :: PointMass\n \n q(μ, τ) = q(μ)q(τ) # Mean-Field over `μ` and `τ`\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Constraints:\n marginals form:\n q(μ) :: PointMassFormConstraint() [ prod_constraint = GenericProd() ]\n messages form:\n factorisation:\n q(μ, τ) = q(μ)q(τ)\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example we specified an extra constraints for q_i for Bethe factorisation:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(s) = prod_a in mathcalV q_a(s_a) prod_i in mathcalE q_i^-1(s_i)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model7(n)\n τ ~ Gamma(shape = 1.0, rate = 1.0) \n \n # In case of form constraints `randomvar()` call is necessary\n μ = randomvar()\n μ ~ Normal(mean = 0.0, variance = 100.0)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = μ, precision = τ)\n end\n \n return μ, τ, y\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model7(length(dataset)), constraints = constraints7);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"setmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, PointMass(1.0))\n\nμ_values = keep(Marginal)\nτ_values = keep(Marginal)\n\nμ_subscription = subscribe!(getmarginal(μ), μ_values)\nτ_subscription = subscribe!(getmarginal(τ), τ_values)\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(μ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(PointMass{Float64}(-2.9941782336196785))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"getvalues(τ_values) |> last","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Marginal(GammaShapeRate{Float64}(a=501.0, b=95.76412770708546))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"By default RxInfer tries to compute an analytical product of two colliding messages and throws an error if no analytical solution is known. However, it is possible to fall back to a generic product that does not require an analytical solution to be known. In this case the inference backend will simply propagate the product of two messages in a form of a tuple. It is not possible to use such a tuple-product during an inference and in this case it is mandatory to use some form constraint to approximate this product.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { \n prod_constraint = ProdGeneric(),\n form_constraint = SampleListFormConstraint() \n}","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Sometimes it is useful to preserve a specific parametrisation of the resulting product later on in an inference procedure. The ReactiveMP inference engine exports a special prod_constraint called ProdPreserveType especially for that purpose:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"μ = randomvar() where { prod_constraint = ProdPreserveType(NormalWeightedMeanPrecision) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: @constraints macro specifies required prod_constraint automatically.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Free-Energy","page":"Advanced Tutorial","title":"Free Energy","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During variational inference the RxInfer optimises a special functional called the Bethe Free Energy functional. It is possible to obtain its values for all VMP iterations with the score function.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"model, (μ, τ, y) = create_model(test_model6(length(dataset)), constraints = constraints6);","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_observable = score(model, Float64, BetheFreeEnergy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"ProxyObservable(Float64, ErrorIfProxy())","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"bfe_subscription = subscribe!(bfe_observable, (fe) -> println(\"Current BFE value: \", fe));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Reset the model with vague marginals\nsetmarginal!(μ, vague(NormalMeanPrecision))\nsetmarginal!(τ, vague(GammaShapeRate))\n\nfor i in 1:10\n update!(y, dataset)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Current BFE value: 612.2308443178317\nCurrent BFE value: 599.7424442637521\nCurrent BFE value: 599.7424440148366\nCurrent BFE value: 599.742444014837\nCurrent BFE value: 599.7424440148343\nCurrent BFE value: 599.7424440148375\nCurrent BFE value: 599.7424440148361\nCurrent BFE value: 599.742444014837\nCurrent BFE value: 599.7424440148361\nCurrent BFE value: 599.742444014837","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# It always necessary to unsubscribe and release computer resources\nunsubscribe!([ μ_subscription, τ_subscription, bfe_subscription ])","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Meta-data-specification","page":"Advanced Tutorial","title":"Meta data specification","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"During model specification some functional dependencies may accept an optional meta object in the where { ... } clause. The purpose of the meta object is to adjust, modify or supply some extra information to the inference backend during the computations of the messages. The meta object for example may contain an approximation method that needs to be used during various approximations or it may specify the tradeoff between accuracy and performance:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example the `meta` object for the autoregressive `AR` node specifies the variate type of \n# the autoregressive process and its order. In addition it specifies that the message computation rules should\n# respect accuracy over speed with the `ARsafe()` strategy. In contrast, `ARunsafe()` strategy tries to speedup computations\n# by cost of possible numerical instabilities during an inference procedure\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Multivariate, order, ARsafe()) }\n...\ns[i] ~ AR(s[i - 1], θ, γ) where { q = q(s[i - 1], s[i])q(θ)q(γ), meta = ARMeta(Univariate, order, ARunsafe()) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Another example with GaussianControlledVariance, or simply GCV [see Hierarchical Gaussian Filter], node:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# In this example we specify structured factorisation and flag meta with `GaussHermiteCubature` \n# method with `21` sigma points for approximation of non-lineariety between hierarchy layers\nxt ~ GCV(xt_min, zt, real_k, real_w) where { q = q(xt, xt_min)q(zt)q(κ)q(ω), meta = GCVMetadata(GaussHermiteCubature(21)) }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The Meta object is useful to pass any extra information to a node that is not a random variable or constant model variable. It may include extra approximation methods, differentiation methods, optional non-linear functions, extra inference parameters etc.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#RxInfer.jl-@meta-macro","page":"Advanced Tutorial","title":"RxInfer.jl @meta macro","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Users can use @meta macro from the RxInfer.jl package to achieve the same goal. Read more about @meta macro in the corresponding documentation section. Here is a simple example of the same meta specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@meta begin \n AR(s, θ, γ) -> ARMeta(Multivariate, 5, ARsafe())\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Meta specification:\n AR(s, θ, γ) -> ARMeta{Multivariate, ARsafe}(5, ARsafe())\nOptions:\n warn = true","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Creating-custom-nodes-and-message-computation-rules","page":"Advanced Tutorial","title":"Creating custom nodes and message computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-nodes","page":"Advanced Tutorial","title":"Custom nodes","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To create a custom functional form and to make it available during model specification the ReactiveMP inference engine exports the @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# `@node` macro accepts a name of the functional form, its type, either `Stochastic` or `Deterministic` and an array of interfaces:\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# Interfaces may have aliases for their names that might be convenient for factorisation constraints specification\n@node NormalMeanVariance Stochastic [ out, (μ, aliases = [ mean ]), (v, aliases = [ var ]) ]\n\n# `NormalMeanVariance` structure declaration must exist, otherwise `@node` macro will throw an error\nstruct NormalMeanVariance end \n\n@node NormalMeanVariance Stochastic [ out, μ, v ]\n\n# It is also possible to use function objects as a node functional form\nfunction dot end\n\n# Syntax for functions is a bit differet, as it is necesssary to use `typeof(...)` function for them \n# out = dot(x, a)\n@node typeof(dot) Deterministic [ out, x, a ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Note: Deterministic nodes do not support factorisation constraints with the where { q = ... } clause.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"After that it is possible to use the newly created node during model specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function test_model()\n ...\n y ~ dot(x, a)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Custom-messages-computation-rules","page":"Advanced Tutorial","title":"Custom messages computation rules","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl exports the @rule macro to create custom message computation rules. For example let us create a simple + node to be available for usage in the model specification usage. We refer to A Factor Graph Approach to Signal Modelling , System Identification and Filtering [ Sascha Korl, 2005, page 32 ] for a rigorous explanation of the + node in factor graphs. According to Korl, assuming that inputs are Gaussian Sum-Product message computation rule for + node is the following:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu_z = mu_x + mu_y\nV_z = V_x + V_y\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"To specify this in RxInfer.jl we use the @node and @rule macros:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@node typeof(+) Deterministic [ z, x, y ]\n\n@rule typeof(+)(:z, Marginalisation) (m_x::UnivariateNormalDistributionsFamily, m_y::UnivariateNormalDistributionsFamily) = begin\n x_mean, x_var = mean_var(m_x)\n y_mean, y_var = mean_var(m_y)\n return NormalMeanVariance(x_mean + y_mean, x_var + y_var)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In this example, for the @rule macro, we specify a type of our functional form: typeof(+). Next, we specify an edge we are going to compute an outbound message for. Marginalisation indicates that the corresponding message respects the marginalisation constraint for posterior over corresponding edge:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nq(z) = int q(z x y) mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"If we look on difference between sum-product rules and variational rules with mean-field assumption we notice that they require different local information to compute an outgoing message:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nmu(z) = int f(x y z)mu(x)mu(y)mathrmdxmathrmdy\nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"beginaligned\nnu(z) = exp int log f(x y z)q(x)q(y)mathrmdxmathrmdy \nendaligned","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"The @rule macro supports both cases with special prefixes during rule specification:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"m_ prefix corresponds to the incoming message on a specific edge\nq_ prefix corresponds to the posterior marginal of a specific edge","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Sum-Product rule with m_ messages used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (m_out::UnivariateNormalDistributionsFamily, m_τ::PointMass) = begin \n m_out_mean, m_out_cov = mean_cov(m_out)\n return NormalMeanPrecision(m_out_mean, inv(m_out_cov + inv(mean(m_τ))))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Example of a Variational rule with Mean-Field assumption with q_ posteriors used:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:μ, Marginalisation) (q_out::Any, q_τ::Any) = begin \n return NormalMeanPrecision(mean(q_out), mean(q_τ))\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"RxInfer.jl also supports structured rules. It is possible to obtain joint marginal over a set of edges:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule NormalMeanPrecision(:τ, Marginalisation) (q_out_μ::Any, ) = begin\n m, V = mean_cov(q_out_μ)\n θ = 2 / (V[1,1] - V[1,2] - V[2,1] + V[2,2] + abs2(m[1] - m[2]))\n α = convert(typeof(θ), 1.5)\n return Gamma(α, θ)\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"NOTE: In the @rule specification the messages or marginals arguments must be in order with interfaces specification from @node macro:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference backend expects arguments in `@rule` macro to be in the same order\n@node NormalMeanPrecision Stochastic [ out, μ, τ ]","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Any rule always has access to the meta information with hidden the meta::Any variable:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any) = begin \n ...\n println(meta)\n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"It is also possible to dispatch on a specific type of a meta object:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::LaplaceApproximation) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"or","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@rule MyCustomNode(:out, Marginalisation) (m_in1::Any, m_in2::Any, meta::GaussHermiteCubature) = begin \n ...\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/#Customizing-messages-computational-pipeline","page":"Advanced Tutorial","title":"Customizing messages computational pipeline","text":"","category":"section"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"In certain situations it might be convenient to customize the default message computational pipeline. RxInfer.jl supports the pipeline keyword in the where { ... } clause to add some extra steps after a message has been computed. A use case might be an extra approximation method to preserve conjugacy in the model, debugging or simple printing.","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Logs all outbound messages\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LoggerPipelineStage() }\n# Initialise messages to be vague\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = InitVaguePipelineStage() }\n# In principle, it is possible to approximate outbound messages with Laplace Approximation\ny[i] ~ NormalMeanPrecision(x[i], 1.0) where { pipeline = LaplaceApproximation() }","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"Let us return to the coin toss model, but this time we want to print flowing messages:","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"@model function coin_toss_model_log(n)\n\n y = datavar(Float64, n)\n\n θ ~ Beta(2.0, 7.0) where { pipeline = LoggerPipelineStage(\"θ\") }\n\n for i in 1:n\n y[i] ~ Bernoulli(θ) where { pipeline = LoggerPipelineStage(\"y[$i]\") }\n end\n \n return y, θ\nend","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"_, (y, θ) = RxInfer.create_model(coin_toss_model_log(5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"θ_subscription = subscribe!(getmarginal(θ), (value) -> println(\"New posterior marginal for θ: \", value));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[θ][Beta][out]: VariationalMessage()","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"coinflips = float.(rand(Bernoulli(0.5), 5));","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"update!(y, coinflips)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"[y[1]][Bernoulli][p]: VariationalMessage()\n[y[2]][Bernoulli][p]: VariationalMessage()\n[y[3]][Bernoulli][p]: VariationalMessage()\n[y[4]][Bernoulli][p]: VariationalMessage()\n[y[5]][Bernoulli][p]: VariationalMessage()\nNew posterior marginal for θ: Marginal(Beta{Float64}(α=5.0, β=9.0))","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"unsubscribe!(θ_subscription)","category":"page"},{"location":"examples/advanced_examples/Advanced Tutorial/","page":"Advanced Tutorial","title":"Advanced Tutorial","text":"# Inference is lazy and does not send messages if no one is listening for them\nupdate!(y, coinflips)","category":"page"},{"location":"manuals/custom-node/#create-node","page":"Defining a custom node and rules","title":"Creating your own custom nodes","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Welcome to the RxInfer documentation on creating custom factor graph nodes. In RxInfer, factor nodes represent functional relationships between variables, also known as factors. Together, these factors define your probabilistic model. Quite often these factors represent distributions, denoting how a certain parameter affects another. However, other factors are also possible, such as ones specifying linear or non-linear relationships. RxInfer already supports a lot of factor nodes, however, depending on the problem that you are trying to solve, you may need to create a custom node that better fits the specific requirements of your model. This tutorial will guide you through the process of defining a custom node in RxInfer, step by step. By the end of this tutorial, you will be able to create your own custom node and integrate it into your model.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To create a custom node in RxInfer, 4 steps are required:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Create your custom node in RxInfer using the @node macro.\nDefine the corresponding message passing update rules with the @rule macro. These rules specify how the node processes information in the form of messages, and how it communicates the results to adjacent parts of the model.\nSpecify computations for marginal distributions of the relevant variables with the @marginalrule macro.\nImplement the computation of the Free Energy in a node with the @average_energy macro.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Throughout this tutorial, we will create a node for the Bernoulli distribution. The Bernoulli distribution is a commonly used distribution in statistical modeling that is often used to model a binary outcome, such as a coin flip. By recreating this node, we will be able to demonstrate the process of creating a custom node, from notifying RxInfer of the nodes existence to implementing the required methods. While this tutorial focuses on the Bernoulli distribution, the principles can be applied to creating custom nodes for other distributions as well. So let's get started!","category":"page"},{"location":"manuals/custom-node/#Problem-statement","page":"Defining a custom node and rules","title":"Problem statement","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane wants to determine whether a coin is a fair coin, meaning that is equally likely to land on heads or tails. In order to determine this, she will throw the coin K=20 times and write down how often it lands on heads and tails. The result of this experiment is a realization of the underlying stochastic process. Jane models the outcome of the experiment x_kin01 using the Bernoulli distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_k mid pi) = mathrmBer(x_k mid pi) = pi^x_k (1-pi)^1-x_k","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"where pi in01 denotes the probability that she throws heads, also known as the success probability. Jane also has a prior belief (initial guess) about the value of pi which she models using the Beta distribution as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(pi) = mathrmBeta(pi mid 4 8)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With this prior belief, the total probabilistic model that she has for this experiment is given by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"p(x_1K pi) = p(pi) prod_k=1^K p(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Jane is interested in determining the fairness of the coin. Therefore she aims to infer (calculate) the posterior belief of pi, p(pi mid x_1K), denoting how pi is distributed after we have seen the data.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-1:-Creating-the-custom-node","page":"Defining a custom node and rules","title":"Step 1: Creating the custom node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nIn this example we will assume that the Bernoulli node and distribution do not yet exist. The RxInfer already defines the node for the Bernoulli distribution from the Distributions.jl package.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"First things first, let's import RxInfer:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using RxInfer","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to define a custom node using the @node macro from RxInfer, we need the following three arguments:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The name of the node. (::Type)\nWhether the node is Deterministic or Stochastic.\nThe interfaces of the node and any potential aliases. (::Vector)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the name of the node we wish to use MyBernoulli in this tutorial (Bernoulli already exists). However, the corresponding distribution does not yet exist. Therefore we need to specify it first as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"# struct for Bernoulli distribution with success probability π\nstruct MyBernoulli{T <: Real} <: ContinuousUnivariateDistribution\n π :: T\n new(π :: Real) = 0 ≤ π ≤ 1 ? MyBernoulli(π) : throw(ArgumentError(\"π must be between 0 and 1\"))\t\nend\n\n# for simplicity, let's also specify the mean of the distribution\nDistributions.mean(d::MyBernoulli) = d.π\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this case the distribution also has an entry in the struct, however, this is not necessary as long as the name of the distribution is a Type. The custom node created with struct NewNode end would also work fine.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"note: Note\nYou can use regular functions, e.g + as a node type. Their Julia type, however, is written with the typeof(_) specification, e.g. typeof(+)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For our node we are dealing with a stochastic node, because the node forms a probabilistic relationship. This means that for a given value of pi, we do know the corresponding value of the output, but we do have some belief about this. Deterministic nodes include for example linear and non-linear transformation.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The interfaces specify what variables are connected to the node. The first argument is its output by convention. The ordering is important for both the model specification as the rule definition. As an example consider the NormalMeanVariance factor node. This factor node has interfaces [out, μ, v] and can be called in the model specification language as x ~ NormalMeanVariance(μ, v). It is also possible to use aliases for the interfaces, which can be specified in a tuple as you will see below.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Concluding, we can create the MyBernoulli factor node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@node MyBernoulli Stochastic [out, (π, aliases = [p])]","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Cool! Step 1 is done, we have created a custom node.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-2:-Defining-rules-for-our-node","page":"Defining a custom node and rules","title":"Step 2: Defining rules for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order for RxInfer to perform probabilistic inference and compute posterior distributions, such as p(pimid x_1K), we need to tell it how to perform inference locally around our node. This localization is what makes RxInfer achieve high performance. In our message passing-based paradigm, we need to describe how the node processes incoming information in the form of messages (or marginals). Here we will highlight two different message passing strategies: sum-product message passing and variational message passing.","category":"page"},{"location":"manuals/custom-node/#Sum-product-message-passing-update-rules","page":"Defining a custom node and rules","title":"Sum-product message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In sum-product message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecmu(x) propto int mathrmBer(xmid pi) vecmu(pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(pi) propto sum_x in 01 mathrmBer(xmid pi) overleftarrowmu(x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"This integral does not always have nice tractable solutions. However, for some forms of the incoming messages, it does yield a tractable solution.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"For the case of a Beta message coming into our node, the outgoing message will be the predictive posterior of the Bernoulli distribution with a Beta prior. Here we obtain pi = fracalphaalpha + beta, which coincides with the mean of the Beta distribution. Hence, we can write down the first update rule using the @rule macro as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: Beta,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here, :out refers to the interface of the outgoing message. The second argument denotes the incoming messages (which can be typed) as a tuple. Therefore make sure that it has a trailing , when there is a single message coming in. m_π is shorthand for \"the incoming message on interface π\". As we will see later, the structured approximation update rule for incoming message from π will have q_π as parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The second rule is also straightforward; if π is a PointMass and therefore fixed, the outgoing message will be MyBernoulli(π):","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:out, Marginalisation) (m_π :: PointMass,) = MyBernoulli(mean(m_π))","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Continuing with the sum-product update rules, we now have to define the update rules towards the π interface. We can only do exact inference if the incoming message is known, which in the case of the Bernoulli distribution, means that the out message is a PointMass distribution that is either 0 or 1. The updated Beta distribution for π will be:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrowmu(π) propto mathrmBeta(1 + x 2 - x)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which gives us the following update rule:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@rule MyBernoulli(:π, Marginalisation) (m_out :: PointMass,) = begin\n p = mean(m_out)\n Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/#Variational-message-passing-update-rules","page":"Defining a custom node and rules","title":"Variational message passing update rules","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We will now cover our second set of update rules. The sum-product messages are not always tractable and therefore we may need to resort to approximations. Here we highlight the variational approximation. In variational message passing we compute outgoing messages to our node as","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"vecnu(x) propto exp int q(pi) ln mathrmBer(xmid pi) mathrmdx","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"overleftarrownu(pi) propto exp sum_x in 01 q(x) ln mathrmBer(xmid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"These messages depend on the marginals on the adjacent edges and not on the incoming messages as was the case with sum-product message passing. Update rules that operate on the marginals instead of the incoming messages are specified with the q_{interface} argument names. With these update rules, we can often support a wider family of distributions. Below we directly give the variational update rules. Deriving them yourself will be a nice challenge.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"#rules towards out\n@rule MyBernoulli(:out, Marginalisation) (q_π :: PointMass,) = MyBernoulli(mean(q_π))\n\n@rule Bernoulli(:out, Marginalisation) (q_π::Any,) = begin\n rho_1 = mean(log, q_π) # E[ln(x)]\n rho_2 = mean(mirrorlog, q_π) # E[log(1-x)]\n m = max(rho_1, rho_2)\n tmp = exp(rho_1 - m)\n p = clamp(tmp / (tmp + exp(rho_2 - m)), tiny, one(m))\n return Bernoulli(p)\nend\n\n#rules towards π\n@rule MyBernoulli(:π, Marginalisation) (q_out :: Any,) = begin\n p = mean(q_out)\n return Beta(one(p) + p, 2one(p) - p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"node: Node\nTypically, the type of the variational distributions q_ does not matter in the real computations, but only their statistics, e.g mean or var. Thus, in this case, we may safely use ::Any.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the example that we will show later on, we solely use sum-product message passing. Variational message passing requires us to set the local constraints in our model, something which is out of scope of this tutorial.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-3:-Defining-joint-marginals-for-our-node","page":"Defining a custom node and rules","title":"Step 3: Defining joint marginals for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"The entire probabilistic model can be scored using the Bethe free energy, which bounds the log-evidence for acyclic graphs. This Bethe free energy consists out of the sum of node-local entropies, negative node-local average energies and edge specific entropies. Formally we can denote this by","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Fqf = - sum_ainmathcalV mathrmHq_a(s_a) - sum_ainmathcalVmathrmE_q_a(s_a)ln f_a(s_a) + sum_iinmathcalEmathrmHq_i(s_i)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Here we call q_a(s_a) the joint marginals around a node and -mathrmE_q_a(s_a)ln f_a(s_a) we term the average energy.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In order to be able to compute the Bethe free energy, we need to first describe how to compute q_a(s_a), defined in our case as ","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"q(x_k pi) = vecmu(pi) overleftarrowmu(x_k) mathrmBer(x_k mid pi)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To calculate the updated posterior marginal for our custom distribution, we need to return joint posterior marginals for the interfaces of our node. In our case, the posterior marginal for the observation is still the same PointMass distribution. However, to calculate the posterior marginal over π, we use RxInfer's built-in prod functionality to multiply the Beta prior with the Beta likelihood. This gives us the updated posterior distribution, which is also a Beta distribution. We use ProdAnalytical() parameter to ensure that we multiply the two distributions analytically. This is done as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@marginalrule MyBernoulli(:out_π) (m_out::PointMass, m_π::Beta) = begin\n r = mean(m_out)\n p = prod(ProdAnalytical(), Beta(one(r) + r, 2one(r) - r), m_π)\n return (out = m_out, p = p)\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In this code :out_π describes the arguments of the joint marginal distribution. The second argument contains the incoming messages. Here we know from the model specification that we observe out and therefore this has to be a PointMass. Because it is a PointMass, the joint marginal automatically factorizes as q(x_k pi) = q(x_k)q(pi). These are the distributions that we return in a form of the NamedTuple. NamedTuple is used only in cases where we know that the joint marginal factorizes further, but typically it should be a full distribution. For computing q(pi) we need to compute the product vecmu(pi)overleftarrowmu(pi). We already know how overleftarrowmu(pi) looks like from the previous step, so we can just use the prod function.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"","category":"page"},{"location":"manuals/custom-node/#Step-4:-Defining-the-average-energy-for-our-node","page":"Defining a custom node and rules","title":"Step 4: Defining the average energy for our node","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"To complete the computation of the Bethe free energy, we also need to compute the average energy term. The average energy in our MyBernoulli example can be computed as -mathrmE_q(x_k pi)ln p(x_k mid pi), however, because we know that we observe x_k and therefore q(x_k pi) factorizes, we can instead compute beginaligned -mathrmE_q(x_k)q(pi)ln p(x_k mid pi) = -mathrmE_q(x_k)q(pi) ln (pi^x_k (1-pi)^1 - x_k) \n= -mathrmE_q(x_k)q(pi) x_k ln(pi) + (1-x_k) ln(1-pi) \n= -mathrmE_q(x_k)x_k mathrmE_q(pi) ln(pi) - (1-mathrmE_q(x_k)x_k) mathrmE_q(pi)ln(1-pi) endaligned","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Which is what we implemented below. Note that mean(mirrorlog, q(x)) is equal to mathrmE_q(x)1-logx.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@average_energy Bernoulli (q_out::Any, q_π::Any) = -mean(q_out) * mean(log, q_π) - (1.0 - mean(q_out)) * mean(mirrorlog, q_π)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"In the case that the interfaces do not factorize, we would get something like @average_energy MyBernoulli (q_out_π) ....","category":"page"},{"location":"manuals/custom-node/#Using-our-node-in-a-model","page":"Defining a custom node and rules","title":"Using our node in a model","text":"","category":"section"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"With all the necessary functions defined, we can proceed to test our custom node in an experiment. For this experiment, we will generate a dataset from a Bernoulli distribution with a fixed success probability of 0.75. Next, we will define a probabilistic model that has a Beta prior and a MyBernoulli likelihood. The Beta prior will be used to model our prior belief about the probability of success. The MyBernoulli likelihood will be used to model the generative process of the observed data. We start by generating the dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Random\n\nrng = MersenneTwister(42)\nn = 500\nπ_real = 0.75\ndistribution = Bernoulli(π_real)\n\ndataset = float.(rand(rng, distribution, n))\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Next, we define our model. Note that we use the MyBernoulli node in the model. The model consists of a single latent variable π, which has a Beta prior and is the parameter of the MyBernoulli likelihood. The MyBernoulli node takes the value of π as its parameter and returns a binary observation. We set the hyperparameters of the Beta prior to be 4 and 8, respectively, which correspond to a distribution slightly biased towards higher values of π. The model is defined as follows:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model_mybernoulli(n)\n\n # `datavar` creates data 'inputs' in our model\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n π ~ Beta(4.0, 8.0)\n\n # We assume that outcome of each coin flip is governed by the MyBernoulli distribution\n for i in 1:n\n y[i] ~ MyBernoulli(π)\n end\n\nend","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Finally, we can run inference with this model and the generated dataset:","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"result_mybernoulli = infer(\n model = coin_model_mybernoulli(length(dataset)), \n data = (y = dataset, ),\n)","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"We have now completed our experiment and obtained the posterior marginal distribution for p through inference. To evaluate the performance of our inference, we can compare the estimated posterior to the true value. In our experiment, the true value for p is 0.75, and we can see that the estimated posterior has a mean of approximately 0.713, which shows that our custom node was able to successfully pass messages towards the π variable in order to learn the true value of the parameter.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(result_mybernoulli.posteriors[:π], x), fillalpha=0.3, fillrange = 0, label=\"p(π|x)\", c=3)\nvline!([π_real], label=\"Real π\")","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"As a sanity check, we can create the same model with the RxInfer built-in node Bernoulli and compare the resulting posterior distribution with the one obtained using our custom MyBernoulli node. This will give us confidence that our custom node is working correctly. We use the Bernoulli node with the same Beta prior and the observed data, and then run inference. We can compare the two posterior distributions and observe that they are exactly the same, which indicates that our custom node is performing as expected.","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"@model function coin_model(n)\n \n y = datavar(Float64, n)\n p ~ Beta(4.0, 8.0)\n\n for i in 1:n\n y[i] ~ Bernoulli(p)\n end\n\nend\n\nresult_bernoulli = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, ),\n)\n\nif !(result_bernoulli.posteriors[:p] == result_mybernoulli.posteriors[:π])\n error(\"Results are not identical\")\nelse \n println(\"Results are identical 🎉🎉🎉\")\nend\n\nnothing # hide","category":"page"},{"location":"manuals/custom-node/","page":"Defining a custom node and rules","title":"Defining a custom node and rules","text":"Congratulations! You have successfully implemented your own custom node in RxInfer. We went through the definition of a node to the implementation of the update rules and marginal posterior calculations. Finally we tested our custom node in a model and checked if we implemented everything correctly.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#examples-simple-nonlinear-node","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using RxInfer, Random, StableRNGs","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here is an example of creating custom node with nonlinear function approximation with samplelist.","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Custom-node-creation","page":"Simple Nonlinear Node","title":"Custom node creation","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"struct NonlinearNode end # Dummy structure just to make Julia happy\n\nstruct NonlinearMeta{R, F}\n rng :: R\n fn :: F # Nonlinear function, we assume 1 float input - 1 float output\n nsamples :: Int # Number of samples used in approximation\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@node NonlinearNode Deterministic [ out, in ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"We need to define two Sum-product message computation rules for our new custom node","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Rule for outbound message on out edge given inbound message on in edge\nRule for outbound message on in edge given inbound message on out edge\nBoth rules accept optional meta object","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `out` edge given inbound message on `in` edge\n@rule NonlinearNode(:out, Marginalisation) (m_in::NormalMeanVariance, meta::NonlinearMeta) = begin \n samples = rand(meta.rng, m_in, meta.nsamples)\n return SampleList(map(meta.fn, samples))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"# Rule for outbound message on `in` edge given inbound message on `out` edge\n@rule NonlinearNode(:in, Marginalisation) (m_out::Gamma, meta::NonlinearMeta) = begin \n return ContinuousUnivariateLogPdf((x) -> logpdf(m_out, meta.fn(x)))\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/#Model-specification","page":"Simple Nonlinear Node","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"After we have defined our custom node with custom rules we may proceed with a model specification:","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"beginaligned\np(theta) = mathcalN(thetamu_theta sigma_theta)\np(m) = mathcalN(thetamu_m sigma_m)\np(w) = f(theta)\np(y_im w) = mathcalN(y_im w)\nendaligned","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Given this IID model, we aim to estimate the precision of a Gaussian distribution. We pass a random variable theta through a non-linear transformation f to make it positive and suitable for a precision parameter of a Gaussian distribution. We, later on, will estimate the posterior of theta. ","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@model function nonlinear_estimation(n)\n \n θ ~ Normal(mean = 0.0, variance = 100.0)\n m ~ Normal(mean = 0.0, variance = 1.0)\n \n w ~ NonlinearNode(θ)\n \n y = datavar(Float64, n)\n \n for i in 1:n\n y[i] ~ Normal(mean = m, precision = w)\n end\n \nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@constraints function nconstsraints(nsamples)\n q(θ) :: SampleList(nsamples, LeftProposal())\n q(w) :: SampleList(nsamples, RightProposal())\n \n q(θ, w, m) = q(θ)q(m)q(w)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nconstsraints (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"@meta function nmeta(fn, nsamples)\n NonlinearNode(θ, w) -> NonlinearMeta(StableRNG(123), fn, nsamples)\nend","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nmeta (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Here we generate some data","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn(x) = abs(exp(x) * sin(x))","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"nonlinear_fn (generic function with 1 method)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"seed = 123\nrng = StableRNG(seed)\n\nniters = 15 # Number of VMP iterations\nnsamples = 5_000 # Number of samples in approximation\n\nn = 500 # Number of IID samples\nμ = -10.0\nθ = -1.0\nw = nonlinear_fn(θ)\n\ndata = rand(rng, NormalMeanPrecision(μ, w), n);","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"result = infer(\n model = nonlinear_estimation(n),\n meta = nmeta(nonlinear_fn, nsamples),\n constraints = nconstsraints(nsamples),\n data = (y = data, ), \n initmarginals = (m = vague(NormalMeanPrecision), w = vague(Gamma)),\n returnvars = (θ = KeepLast(), ),\n iterations = niters, \n showprogress = true\n)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"θposterior = result.posteriors[:θ]","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"SampleList(Univariate, 5000)","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"using Plots, StatsPlots\n\nestimated = Normal(mean_std(θposterior)...)\n\nplot(estimated, title=\"Posterior for θ\", label = \"Estimated\", legend = :bottomright, fill = true, fillopacity = 0.2, xlim = (-3, 3), ylim = (0, 2))\nvline!([ θ ], label = \"Real value of θ\")","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Simple Nonlinear Node/","page":"Simple Nonlinear Node","title":"Simple Nonlinear Node","text":"","category":"page"},{"location":"library/exported-methods/#lib-using-methods","page":"Exported methods","title":"Using methods from RxInfer","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In the Julia programming language (in contrast to Python for example) the most common way of loading a module is:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"A nice explanation about how modules/packages work in Julia can be found in the official documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"In a nutshell, Julia automatically resolves all name collisions and there is no a lot of benefit of importing specific names, e.g.:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"One of the reasons for that is that Julia uses multiple-dispatch capabilities to merge names automatically and will indicate (with a warning) if something went wrong or names have unresolvable collisions on types. As a small example of this feature consider the following small import example:","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"import RxInfer: mean as mean_from_rxinfer\nimport Distributions: mean as mean_from_distributions\n\nmean_from_rxinfer === mean_from_distributions","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Even though we import mean function from two different packages they actually refer to the same object. Worth noting that this is not always the case - Julia will print a warning in case it finds unresolvable conflicts and usage of such functions will be disallowed unless user import them specifically. Read more about this in the section of the Julia's documentation.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"# It is easier to let Julia resolve names automatically\n# Julia will not overwrite `mean` that is coming from both packages\nusing RxInfer, Distributions ","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(Normal(0.0, 1.0)) # `Normal` is an object from `Distributions.jl`","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"mean(NormalMeanVariance(0.0, 1.0)) # `NormalMeanVariance` is an object from `RxInfer.jl`","category":"page"},{"location":"library/exported-methods/#lib-list-methods","page":"Exported methods","title":"List of available methods","text":"","category":"section"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"Below you can find a list of exported methods from RxInfer.jl. All methods (even private) can be always accessed with RxInfer. prefix, e.g RxInfer.mean.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"note: Note\nSome exported names are (for legacy reasons) intended for private usage only. As a result some of these methods do not have a proper associated documentation with them. We constantly improve RxInfer.jl library and continue to add better documentation for many exported methods, but a small portion of these methods could be removed from this list in the future.","category":"page"},{"location":"library/exported-methods/","page":"Exported methods","title":"Exported methods","text":"using RxInfer #hide\nforeach(println, names(RxInfer))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/#examples-nonlinear-sensor-fusion","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"section"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"using RxInfer, Random, LinearAlgebra, Distributions, Plots, StatsPlots, Optimisers\nusing DataFrames, DelimitedFiles, StableRNGs","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In a secret ongoing mission to Mars, NASA has deployed its custom lunar roving vehicle, called WALL-E, to explore the area and to discover hidden minerals. During one of the solar storm, WALL-E's GPS unit got damaged, preventing it from accurately locating itself. The engineers at NASA were devastated as they developed the project over the past couple of years and spend most of their funding on it. Without being able to locate WALL-E, they were unable to complete their mission.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"A smart group of engineers came up with a solution to locate WALL-E. They decided to repurpose 3 nearby satelites as beacons for WALL-E, allowing it to detect its relative location to these beacons. However, these satelites were old and therefore WALL-E was only able to obtain noisy estimates of its distance to these beacons. These distances were communicated back to earth, where the engineers tried to figure our WALL-E's location. Luckily they knew the locations of these satelites and together with the noisy estimates of the distance to WALL-E they can infer the exact location of the moving WALL-E.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"To illustrate these noisy measurements, the engineers decided to plot them:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# fetch measurements\nbeacon_locations = readdlm(\"../data/sensor_fusion/beacons.txt\")\ndistances = readdlm(\"../data/sensor_fusion/distances.txt\")\nposition = readdlm(\"../data/sensor_fusion/position.txt\")\nnr_observations = size(distances, 1);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual location of WALL-E\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\")\n\n# plot noisy distance measurements\np2 = plot(distances, legend=:topleft, linewidth=3, label=[\"distance to beacon 1\" \"distance to beacon 2\" \"distance to beacon 3\"])\nxlabel!(\"time [sec]\"), ylabel!(\"distance [m]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"In order to track the location of WALL-E based on the noisy distance measurements to the beacon, the engineers developed a probabilistic model for the movements for WALL-E and the distance measurements that followed from this. The engineers assumed that the position of WALL-E at time t, denoted by z_t, follows a 2-dimensional normal random walk:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(z_t mid z_t - 1) = mathcalN(z_t mid z_t-1mathrmI_2)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"where mathrmI_2 denotes the 2-dimensional identity matrix. From the current position of WALL-E, we specify our noisy distance measurements y_t as a noisy set of the distances between WALL-E and the beacons, specified by s_i:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(y_t mid z_t) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixmathrmI_3 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers are smart enough to automate the probabilistic inference procedure using RxInfer.jl. They specify the probabilistic model as:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# function to compute distance to beacons\nfunction compute_distances(z) \n distance1 = norm(z - beacon_locations[1,:])\n distance2 = norm(z - beacon_locations[2,:])\n distance3 = norm(z - beacon_locations[3,:])\n distances = [distance1, distance2, distance3]\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model(nr_observations)\n \n # specify precision matrices\n W = diageye(2)\n R = diageye(3)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], W)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Due to non-linearity, exact probabilistic inference is intractable in this model. Therefore we resort to Conjugate-Computational Variational Inference (CVI) following the paper Probabilistic programming with stochastic variational message passing. This requires setting the @meta macro in RxInfer.jl.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Please note that we permit improper messages within the CVI procedure in this example by providing Val(false) to CVI constructor:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":" compute_distances(z) -> CVI(..., Val(false), ...)","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"This move may lead to numerical instabilities in other scenarios, however dissallowing improper messages in this case can lead to a biased estimates of posterior distribution. So, as a rule of thumb, you should try the default setting, and if it fails to find an unbiased result, enable improper messages.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_model_meta(nr_samples, nr_iterations, rng)\n compute_distances(z) -> CVI(rng, nr_samples, nr_iterations, Optimisers.Descent(0.1), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"NOTE: You can try out different meta for approximating the nonlinearity, e.g.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_linear_meta()\n compute_distances(z) -> Linearization()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@meta function random_walk_unscented_meta()\n compute_distances(z) -> Unscented()\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_fast = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1, 3, StableRNG(42)), # or random_walk_unscented_meta()\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(ones(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_accuracy = infer(\n model = random_walk_model(nr_observations),\n meta = random_walk_model_meta(1000, 100, StableRNG(42)),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = false,\n returnvars = (z = KeepLast(),),\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.1 * diageye(2)),),\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"After running this fast inference procedure, the engineers plot the results and evaluate the performance:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_fast.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Fast (1 sample, 3 iterations)\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot beacon and actual and estimated location of WALL-E (accurate inference)\np2 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_accuracy.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"), title!(\"Accurate (1000 samples, 100 iterations)\"); p2.series_list[end][:label] = \"estimated location ±2σ\"\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers were very happy with the solution, as it meant that the Mars mission could continue. However, they noted that the estimates began to deviate after WALL-E moved further away from the beacons. They deemed this was likely due to the noise in the distance measurements. Therefore, the engineers decided to adapt the model, such that they would also infer the process and observation noise precision matrices, Q and R respectively. They did this by adding Wishart priors to those matrices:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"beginaligned\n p(Q) = mathcalW(Q mid 3 mathrmI_2) \n p(R) = mathcalW(R mid 4 mathrmI_3) \n p(z_t mid z_t - 1 Q) = mathcalN(z_t mid z_t-1 Q^-1)\n p(y_t mid z_t R) = mathcalN left (y_t left vert beginbmatrix z_t - s_1 z_t - s_2 z_t - s_3endbmatrixR^-1 right right)\nendaligned","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"@model function random_walk_model_wishart(nr_observations)\n\n # allocate locations and observations\n z = randomvar(nr_observations)\n y = datavar(Vector{Float64}, nr_observations)\n\n # set priors on precision matrices\n Q ~ Wishart(3, diageye(2))\n R ~ Wishart(4, diageye(3))\n\n # specify initial estimates of the location\n z[1] ~ MvNormalMeanCovariance(zeros(2), diageye(2)) \n y[1] ~ MvNormalMeanCovariance(compute_distances(z[1]), diageye(3))\n\n # loop over time steps\n for t in 2:nr_observations\n\n # specify random walk state transition model\n z[t] ~ MvNormalMeanPrecision(z[t-1], Q)\n\n # specify non-linear distance observations model\n y[t] ~ MvNormalMeanPrecision(compute_distances(z[t]), R)\n \n end\n\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"meta = @meta begin \n compute_distances(z) -> CVI(StableRNG(42), 1000, 100, Optimisers.Descent(0.01), ForwardDiffGrad(), 1, Val(false), false)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"Because of the added complexity with the Wishart distributions, the engineers simplify the problem by employing a structured mean-field factorization:","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"constraints = @constraints begin\n q(z, Q, R) = q(z)q(Q)q(R)\nend;","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"The engineers run the inference procedure again and decide to track the inference performance using the Bethe free energy.","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"results_wishart = infer(\n model = random_walk_model_wishart(nr_observations),\n data = (y = [distances[t,:] for t in 1:nr_observations],),\n iterations = 100,\n free_energy = true,\n returnvars = (z = KeepLast(),),\n constraints = constraints,\n meta = meta,\n initmessages = (z = MvNormalMeanPrecision(zeros(2), 0.01 * diageye(2)),),\n initmarginals = (R = Wishart(4, diageye(3)), Q = Wishart(3, diageye(2)))\n);","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"They plot the new estimates and the performance over time, and luckily WALL-E is found!","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"# plot beacon and actual and estimated location of WALL-E (fast inference)\np1 = scatter(beacon_locations[:,1], beacon_locations[:,2], markershape=:utriangle, markersize=10, legend=:topleft, label=\"beacon locations\")\nplot!(position[1,:], position[2,:], label=\"actual location\", linewidth=3, linestyle=:dash, arrow=(:closed, 2.0), aspect_ratio=1.0)\nmap(posterior -> covellipse!(mean(posterior), cov(posterior), color=\"red\", label=\"\", n_std=2), results_wishart.posteriors[:z])\nxlabel!(\"longitude [m]\"), ylabel!(\"latitude [m]\"); p1.series_list[end][:label] = \"estimated location ±2σ\"\n\n# plot bethe free energy performance\np2 = plot(results_wishart.free_energy, label = \"\")\nxlabel!(\"iteration\"), ylabel!(\"Bethe free energy [nats]\")\n\nplot(p1, p2, size=(1200, 500))","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Nonlinear Sensor Fusion/","page":"Nonlinear Sensor Fusion","title":"Nonlinear Sensor Fusion","text":"","category":"page"},{"location":"examples/problem_specific/overview/#examples-problem_specific-overview","page":"Overview","title":"Problem specific","text":"","category":"section"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"This section contains a set of examples for Bayesian Inference with RxInfer package in various probabilistic models.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"note: Note\nAll examples have been pre-generated automatically from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Problem specific examples contain specialized models and inference for various domains.","category":"page"},{"location":"examples/problem_specific/overview/","page":"Overview","title":"Overview","text":"Autoregressive Models: An example of Bayesian treatment of latent AR and ARMA models. Reference: Albert Podusenko, Message Passing-Based Inference for Time-Varying Autoregressive Models.\nGamma Mixture Model: This example implements one of the Gamma mixture experiments outlined in https://biaslab.github.io/publication/mp-based-inference-in-gmm/ .\nGaussian Mixture: This example implements variational Bayesian inference in univariate and multivariate Gaussian mixture models with mean-field assumption.\nHierarchical Gaussian Filter: An example of online inference procedure for Hierarchical Gaussian Filter with univariate noisy observations using Variational Message Passing algorithm. Reference: Ismail Senoz, Online Message Passing-based Inference in the Hierarchical Gaussian Filter.\nInvertible neural networks: a tutorial: An example of variational Bayesian Inference with invertible neural networks. Reference: Bart van Erp, Hybrid Inference with Invertible Neural Networks in Factor Graphs.\nProbit Model (EP): In this demo we illustrate EP in the context of state-estimation in a linear state-space model that combines a Gaussian state-evolution model with a discrete observation model.\nRTS vs BIFM Smoothing: This example performs BIFM Kalman smoother on a factor graph using message passing and compares it with the RTS implementation.\nSimple Nonlinear Node: In this example we create a non-conjugate model and use a nonlinear link function between variables. We show how to extend the functionality of RxInfer and to create a custom factor node with arbitrary message passing update rules.\nUniversal Mixtures: Universal mixture modeling.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/#examples-coin-toss-model-(beta-bernoulli)","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"section"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"In this example, we are going to perform an exact inference for a coin toss model that can be represented as:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"beginaligned\np(theta) = mathrmBeta(thetaa b)\np(y_itheta) = mathrmBer(y_itheta)\nendaligned","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"where y_i in 0 1 is a binary observation induced by Bernoulli likelihood while theta is a Beta prior distribution on the parameter of Bernoulli. We are interested in inferring the posterior distribution of theta.","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"We start with importing all needed packages:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using RxInfer, Random","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Let's generate some synthetic dataset with IID observations from Bernoulli distribution, that represents our coin tosses. We also assume that our coin is biased:","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"rng = MersenneTwister(42)\nn = 500\nθ_real = 0.75\ndistribution = Bernoulli(θ_real)\n\ndataset = float.(rand(rng, Bernoulli(θ_real), n));","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n\n # We endow θ parameter of our model with some prior\n θ ~ Beta(4.0, 8.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n\n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n\nend","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (y = dataset, )\n)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Inference results:\n Posteriors | available for (θ)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"Beta{Float64}(α=365.0, β=147.0)","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np = plot(title = \"Inference results\")\n\nplot!(rθ, (x) -> pdf(Beta(2.0, 7.0), x), fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\nplot!(rθ, (x) -> pdf(θestimated, x), fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\nvline!([θ_real], label=\"Real θ\")","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"(Image: )","category":"page"},{"location":"examples/basic_examples/Coin Toss Model/","page":"Coin toss model (Beta-Bernoulli)","title":"Coin toss model (Beta-Bernoulli)","text":"","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#examples-invertible-neural-networks:-a-tutorial","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# Activate local environment, see `Project.toml`\nimport Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Table of contents","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Introduction\nModel specification\nModel compilation\nProbabilistic inference\nParameter estimation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Introduction","page":"Invertible neural networks: a tutorial","title":"Introduction","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Load-required-packages","page":"Invertible neural networks: a tutorial","title":"Load required packages","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Before we can start, we need to import some packages:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using RxInfer\nusing Random\nusing StableRNGs\n\nusing ReactiveMP # ReactiveMP is included in RxInfer, but we explicitly use some of its functionality\nusing LinearAlgebra # only used for some matrix specifics\nusing Plots # only used for visualisation\nusing Distributions # only used for sampling from multivariate distributions\nusing Optim # only used for parameter optimisation","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-specification","page":"Invertible neural networks: a tutorial","title":"Model specification","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Specifying an invertible neural network model is easy. The general recipe looks like follows: model = FlowModel(input_dim, (layer1(options), layer2(options), ...)). Here the first argument corresponds to the input dimension of the model and the second argument is a tuple of layers. An example model can be defined as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Alternatively, the input_dim can also be passed as an InputLayer layer as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the above AdditiveCouplingLayer layers the input bfx = x_1 x_2 ldots x_N is partitioned into chunks of unit length. These partitions are additively coupled to an output bfy = y_1 y_2 ldots y_N as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n y_1 = x_1 \n y_2 = x_2 + f_1(x_1) \n vdots \n y_N = x_N + f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Importantly, this structure can easily be converted as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"beginaligned\n x_1 = y_1 \n x_2 = y_2 - f_1(x_1) \n vdots \n x_N = y_N - f_N-1(x_N-1)\nendaligned","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"f_n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"is an arbitrarily complex function, here chosen to be a PlanarFlow, but this can be interchanged for any function or neural network. The permute keyword argument (which defaults to true) specifies whether the output of this layer should be randomly permuted or shuffled. This makes sure that the first element is also transformed in consecutive layers.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"A permutation layer can also be added by itself as a PermutationLayer layer with a custom permutation matrix if desired.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model = FlowModel(\n (\n InputLayer(2),\n AdditiveCouplingLayer(PlanarFlow(); permute=false),\n PermutationLayer(PermutationMatrix(2)),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Model-compilation","page":"Invertible neural networks: a tutorial","title":"Model compilation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"In the current models, the layers are setup to work with the passed input dimension. This means that the function f_n is repeated input_dim-1 times for each of the partitions. Furthermore the permutation layers are set up with proper permutation matrices. If we print the model we get","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"model","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel{3, Tuple{ReactiveMP.AdditiveCouplingLayerEmpty{Tuple{ReactiveMP.P\nlanarFlowEmpty{1}}}, PermutationLayer{Int64}, ReactiveMP.AdditiveCouplingLa\nyerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}}}(2, (ReactiveMP.AdditiveCou\nplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (ReactiveMP.Planar\nFlowEmpty{1}(),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]), ReactiveMP.Ad\nditiveCouplingLayerEmpty{Tuple{ReactiveMP.PlanarFlowEmpty{1}}}(2, (Reactive\nMP.PlanarFlowEmpty{1}(),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The text below describes the terms above. Please note the distinction in typing and elements, i.e. FlowModel{types}(elements):","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"FlowModel - specifies that we are dealing with a flow model.\n3 - Number of layers.\nTuple{AdditiveCouplingLayerEmpty{...},PermutationLayer{Int64},AdditiveCouplingLayerEmpty{...}} - tuple of layer types.\nTuple{ReactiveMP.PlanarFlowEmpty{1},ReactiveMP.PlanarFlowEmpty{1}} - tuple of functions f_n.\nPermutationLayer{Int64}(2, [0 1; 1 0]) - permutation layer with input dimension 2 and permutation matrix [0 1; 1 0].","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"From inspection we can see that the AdditiveCouplingLayerEmpty and PlanarFlowEmpty objects are different than before. They are initialized for the correct dimension, but they do not have any parameters registered to them. This is by design to allow for separating the model specification from potential optimization procedures. Before we perform inference in this model, the parameters should be initialized. We can randomly initialize the parameters as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(-0.5530639593835304, -0.2163616\n102550308, 1.2521116434309154),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.34763211887023543, -0.9116171319236555, -0.0789378301\n24018),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Now we can see that random parameters have been assigned to the individual functions inside of our model. Alternatively if we would like to pass our own parameters, then this is also possible. You can easily find the required number of parameters using the nr_params(model) function.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"CompiledFlowModel{3, Tuple{AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}, PermutationLayer{Int64}, AdditiveCouplingLayer{Tuple{PlanarFlow\n{Float64, Float64}}}}}(2, (AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, \nFloat64}}}(2, (PlanarFlow{Float64, Float64}(0.7296412319250487, -0.97673361\n28037319, -0.4749869451771002),), 1), PermutationLayer{Int64}(2, [0 1; 1 0]\n), AdditiveCouplingLayer{Tuple{PlanarFlow{Float64, Float64}}}(2, (PlanarFlo\nw{Float64, Float64}(0.3490911082645933, -0.8184067956921087, -1.45782147323\n52386),), 1)))","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Probabilistic-inference","page":"Invertible neural networks: a tutorial","title":"Probabilistic inference","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We can perform inference in our compiled model through standard usage of RxInfer and its underlying ReactiveMP inference engine. Let's first generate some random 2D data which has been sampled from a standard normal distribution and is consecutively passed through an invertible neural network. Using the forward(model, data) function we can propagate data in the forward direction.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64, model::CompiledFlowModel; seed = 123)\n\n rng = StableRNG(seed)\n \n # specify latent sampling distribution\n dist = MvNormal([1.5, 0.5], I)\n\n # sample from the latent distribution\n x = rand(rng, dist, nr_samples)\n\n # transform data\n y = zeros(Float64, size(x))\n for k = 1:nr_samples\n y[:,k] .= ReactiveMP.forward(model, x[:,k])\n end\n\n # return data\n return y, x\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# generate data\ny, x = generate_data(1000, compiled_model)\n\n# plot generated data\np1 = scatter(x[1,:], x[2,:], alpha=0.3, title=\"Original data\", size=(800,400))\np2 = scatter(y[1,:], y[2,:], alpha=0.3, title=\"Transformed data\", size=(800,400))\nplot(p1, p2, legend = false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The probabilistic model for doing inference can be described as ","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network(nr_samples::Int64)\n \n # initialize variables\n z_μ = randomvar()\n z_Λ = randomvar()\n x = randomvar(nr_samples)\n y_lat = randomvar(nr_samples)\n y = datavar(Vector{Float64}, nr_samples)\n\n # specify prior\n z_μ ~ MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2)))\n z_Λ ~ Wishart(2.0, tiny*diagm(ones(2)))\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x[k] ~ MvNormalMeanPrecision(z_μ, z_Λ)\n\n # specify transformed latent value\n y_lat[k] ~ Flow(x[k])\n\n # specify observations\n y[k] ~ MvNormalMeanCovariance(y_lat[k], tiny*diagm(ones(2)))\n\n end\n\n # return variables\n return z_μ, z_Λ, x, y_lat, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here the model is passed inside a meta data object of the flow node. Inference then resorts to","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"observations = [y[:,k] for k=1:size(y,2)]\n\nfmodel = invertible_neural_network(length(observations))\ndata = (y = observations, )\ninitmarginals = (z_μ = MvNormalMeanCovariance(zeros(2), huge*diagm(ones(2))), z_Λ = Wishart(2.0, tiny*diagm(ones(2))))\nreturnvars = (z_μ = KeepLast(), z_Λ = KeepLast(), x = KeepLast(), y_lat = KeepLast())\n\nconstraints = @constraints begin\n q(z_μ, x, z_Λ) = q(z_μ)q(z_Λ)q(x)\nend\n\n@meta function fmeta(model)\n compiled_model = compile(model, randn(StableRNG(321), nr_params(model)))\n Flow(y_lat, x) -> FlowMeta(compiled_model) # defaults to FlowMeta(compiled_model; approximation=Linearization()). \n # other approximation methods can be e.g. FlowMeta(compiled_model; approximation=Unscented(input_dim))\nend\n\n# First execution is slow due to Julia's initial compilation \nresult = infer(\n model = fmodel, \n data = data,\n constraints = constraints,\n meta = fmeta(model),\n initmarginals = initmarginals,\n returnvars = returnvars,\n free_energy = true,\n iterations = 10, \n showprogress = false\n)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Inference results:\n Posteriors | available for (z_μ, z_Λ, y_lat, x)\n Free Energy: | Real[29485.3, 23762.9, 23570.6, 23570.6, 23570.6, 2357\n0.6, 23570.6, 23570.6, 23570.6, 23570.6]","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fe_flow = result.free_energy\nzμ_flow = result.posteriors[:z_μ]\nzΛ_flow = result.posteriors[:z_Λ]\nx_flow = result.posteriors[:x]\ny_flow = result.posteriors[:y_lat];","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"As we can see, the variational free energy decreases inside of our model.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"plot(1:10, fe_flow/size(y,2), xlabel=\"iteration\", ylabel=\"normalized variational free energy [nats/sample]\", legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"If we plot a random noisy observation and its approximated transformed uncertainty we obtain:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# pick a random observation\nid = rand(StableRNG(321), 1:size(y,2))\nrand_observation = MvNormal(y[:,id], 5e-1*diagm(ones(2)))\nwarped_observation = MvNormal(ReactiveMP.backward(compiled_model, y[:,id]), ReactiveMP.inv_jacobian(compiled_model, y[:,id])*5e-1*diagm(ones(2))*ReactiveMP.inv_jacobian(compiled_model, y[:,id])');\n\np1 = scatter(x[1,:], x[2,:], alpha=0.1, title=\"Latent distribution\", size=(1200,500), label=\"generated data\")\ncontour!(-5:0.1:5, -5:0.1:5, (x, y) -> pdf(MvNormal([1.5, 0.5], I), [x, y]), c=:viridis, colorbar=false, linewidth=2)\nscatter!([mean(zμ_flow)[1]], [mean(zμ_flow)[2]], color=\"red\", markershape=:x, markersize=5, label=\"inferred mean\")\ncontour!(-5:0.01:5, -5:0.01:5, (x, y) -> pdf(warped_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, colorbar=false)\nscatter!([mean(warped_observation)[1]], [mean(warped_observation)[2]], color=\"red\", label=\"transformed noisy observation\")\np2 = scatter(y[1,:], y[2,:], alpha=0.1, label=\"generated data\")\nscatter!([ReactiveMP.forward(compiled_model, mean(zμ_flow))[1]], [ReactiveMP.forward(compiled_model, mean(zμ_flow))[2]], color=\"red\", marker=:x, label=\"inferred mean\")\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(MvNormal([1.5, 0.5], I), ReactiveMP.backward(compiled_model, [x, y])), c=:viridis, colorbar=false, linewidth=2)\ncontour!(-10:0.1:10, -10:0.1:10, (x, y) -> pdf(rand_observation, [x, y]), colors=\"red\", levels=1, linewidth=2, label=\"random noisy observation\", colorba=false)\nscatter!([mean(rand_observation)[1]], [mean(rand_observation)[2]], color=\"red\", label=\"random noisy observation\")\nplot(p1, p2, legend = true)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/#Parameter-estimation","page":"Invertible neural networks: a tutorial","title":"Parameter estimation","text":"","category":"section"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The flow model is often used to learn unknown probabilistic mappings. Here we will demonstrate it as follows for a binary classification task with the following data:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function generate_data(nr_samples::Int64; seed = 123)\n \n rng = StableRNG(seed)\n\n # sample weights\n w = rand(rng, nr_samples, 2)\n\n # sample appraisal\n y = zeros(Float64, nr_samples)\n for k = 1:nr_samples\n y[k] = 1.0*(w[k,1] > 0.5)*(w[k,2] < 0.5)\n end\n\n # return data\n return y, w\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"data_y, data_x = generate_data(50);\nscatter(data_x[:,1], data_x[:,2], marker_z=data_y, xlabel=\"w1\", ylabel=\"w2\", colorbar=false, legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"We will then specify a possible model as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# specify flow model\nmodel = FlowModel(2,\n (\n AdditiveCouplingLayer(PlanarFlow()), # defaults to AdditiveCouplingLayer(PlanarFlow(); permute=true)\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow()),\n AdditiveCouplingLayer(PlanarFlow(); permute=false)\n )\n);","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"The corresponding probabilistic model for the binary classification task can be created as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"@model function invertible_neural_network_classifier(nr_samples::Int64)\n \n # initialize variables\n x_lat = randomvar(nr_samples)\n y_lat1 = randomvar(nr_samples)\n y_lat2 = randomvar(nr_samples)\n y = datavar(Float64, nr_samples)\n x = datavar(Vector{Float64}, nr_samples)\n\n # specify observations\n for k = 1:nr_samples\n\n # specify latent state\n x_lat[k] ~ MvNormalMeanPrecision(x[k], 1e3*diagm(ones(2)))\n\n # specify transformed latent value\n y_lat1[k] ~ Flow(x_lat[k])\n y_lat2[k] ~ dot(y_lat1[k], [1, 1])\n\n # specify observations\n y[k] ~ Probit(y_lat2[k]) # default: where { pipeline = RequireMessage(in = NormalMeanPrecision(0, 1.0)) }\n\n end\n\n # return variables\n return x_lat, x, y_lat1, y_lat2, y\n\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fcmodel = invertible_neural_network_classifier(length(data_y))\ndata = (y = data_y, x = [data_x[k,:] for k=1:size(data_x,1)], )\n\n@meta function fmeta(model, params)\n compiled_model = compile(model, params)\n Flow(y_lat1, x_lat) -> FlowMeta(compiled_model)\nend","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"fmeta (generic function with 2 methods)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Here we see that the compilation occurs inside of our probabilistic model. As a result we can pass parameters (and a model) to this function which we wish to opmize for some criterium, such as the variational free energy. Inference can be described as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"For the optimization procedure, we will simplify our inference loop, such that it only accepts parameters as an argument (which is wishes to optimize) and outputs a performance metric.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"function f(params)\n Random.seed!(123) # Flow uses random permutation matrices, which is not good for the optimisation procedure\n result = infer(\n model = fcmodel, \n data = data,\n meta = fmeta(model, params),\n free_energy = true,\n free_energy_diagnostics = nothing, # Free Energy can be set to NaN due to optimization procedure\n iterations = 10, \n showprogress = false\n );\n \n result.free_energy[end]\nend;","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Optimization can be performed using the Optim package. Alternatively, other (custom) optimizers can be implemented, such as:","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(store_trace = true, show_trace = true, show_every = 50), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"uses finitediff and is slower/less accurate.","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"or","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"# create gradient function\ng = (x) -> ForwardDiff.gradient(f, x);\n\n# specify initial params\nparams = randn(nr_params(model))\n\n# create custom optimizer (here Adam)\noptimizer = Adam(params; λ=1e-1)\n\n# allocate space for gradient\n∇ = zeros(nr_params(model))\n\n# perform optimization\nfor it = 1:10000\n\n # backward pass\n ∇ .= ForwardDiff.gradient(f, optimizer.x)\n\n # gradient update\n ReactiveMP.update!(optimizer, ∇)\n\nend\n","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"res = optimize(f, randn(StableRNG(42), nr_params(model)), GradientDescent(), Optim.Options(f_tol = 1e-3, store_trace = true, show_trace = true, show_every = 100), autodiff=:forward)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"Iter Function value Gradient norm \n 0 5.888958e+02 8.943663e+02\n * time: 0.024276018142700195\n 100 1.059826e+01 4.120090e+00\n * time: 13.0049409866333\n * Status: success\n\n * Candidate solution\n Final objective value: 1.010332e+01\n\n * Found with\n Algorithm: Gradient Descent\n\n * Convergence measures\n |x - x'| = 1.21e-03 ≰ 0.0e+00\n |x - x'|/|x'| = 5.80e-04 ≰ 0.0e+00\n |f(x) - f(x')| = 6.28e-03 ≰ 0.0e+00\n |f(x) - f(x')|/|f(x')| = 6.22e-04 ≤ 1.0e-03\n |g(x)| = 2.07e+00 ≰ 1.0e-08\n\n * Work counters\n Seconds run: 15 (vs limit Inf)\n Iterations: 113\n f(x) calls: 301\n ∇f(x) calls: 301","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"optimization results are then given as","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"params = Optim.minimizer(res)\ninferred_model = compile(model, params)\ntrans_data_x_1 = hcat(map((x) -> ReactiveMP.forward(inferred_model, x), [data_x[k,:] for k=1:size(data_x,1)])...)'\ntrans_data_x_2 = map((x) -> dot([1, 1], x), [trans_data_x_1[k,:] for k=1:size(data_x,1)])\ntrans_data_x_2_split = [trans_data_x_2[data_y .== 1.0], trans_data_x_2[data_y .== 0.0]]\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, size=(1200,400), c=:viridis, colorbar=false, title=\"original data\")\np2 = scatter(trans_data_x_1[:,1], trans_data_x_1[:,2], marker_z = data_y, c=:viridis, size=(1200,400), colorbar=false, title=\"|> warp\")\np3 = histogram(trans_data_x_2_split; stacked=true, bins=50, size=(1200,400), title=\"|> dot\")\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"using StatsFuns: normcdf\np1 = scatter(data_x[:,1], data_x[:,2], marker_z = data_y, title=\"original labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np2 = scatter(data_x[:,1], data_x[:,2], marker_z = normcdf.(trans_data_x_2), title=\"predicted labels\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\np3 = contour(0:0.01:1, 0:0.01:1, (x, y) -> normcdf(dot([1,1], ReactiveMP.forward(inferred_model, [x,y]))), title=\"Classification map\", xlabel=\"weight 1\", ylabel=\"weight 2\", size=(1200,400), c=:viridis)\nplot(p1, p2, p3, layout=(1,3), legend=false)","category":"page"},{"location":"examples/problem_specific/Invertible Neural Network Tutorial/","page":"Invertible neural networks: a tutorial","title":"Invertible neural networks: a tutorial","text":"(Image: )","category":"page"},{"location":"contributing/new-example/#contributing-new-example","page":"Contributing to the examples","title":"Contributing to the examples","text":"","category":"section"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"We welcome all possible contributors. This page details some of the guidelines that should be followed when adding a new example (in the examples/ folder) to this package.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"In order to add a new example simply create a new Jupyter notebook with your experiments in the examples/\"subcategory\" folder. When creating a new example add a descriptive explanation of your experiments, model specification, inference constraints decisions and add appropriate results analysis. We expect examples to be readable for the general public and therefore highly value descriptive comments. If a submitted example only contains code, we will kindly request some changes to improve the readability.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"After preparing the new example it is necessary to modify the examples/.meta.jl file.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"Make sure that the very first cell of the notebook contains ONLY # in it and has the markdown cell type. This is important for generating links in our documentation.\nThe path option must be set to a local path in a category sub-folder.\nThe text in the description option will be used on the Examples page in the documentation.\nSet category = :hidden_examples to hide a certain example in the documentation (the example will be executed to ensure it runs without errors).\nPlease do no use Overview as a name for the new example, the title Overview is reserved.\nUse the following template for equations, note that $$ and both \\begin and \\end commands are on the same line (check other examples if you are not sure). This is important, because otherwise formulas may not render correctly. Inline equations may use $...$ template.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"$$\\begin{aligned}\n <latex equations here>\n\\end{aligned}$$","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"When using equations, make sure not to follow the left-hand $$ or $ with a space, but instead directly start the equation, e.g. not $$ a + b $$, but $$a + b$$. For equations that are supposed to be on a separate line, make sure $$...$$ is preceded and followed by an empty line.\nNotebooks and plain Julia have different scoping rules for global variables. It may happen that the generation of your example fails due to an UndefVarError or other scoping issues. In these cases we recommend using let ... end blocks to enforce local scoping or use the global keyword to disambiguate the scoping rules, e.g.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"variable = 0\nfor i in 1:10\n global variable = variable + i\nend","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"All examples must use and activate the local environment specified by Project.toml in the second cell (see 1.). Please have a look at the existing notebooks for an example on how to activate this local environment. If you need additional packages, you can add then to the (examples) project.\nAll plots should be displayed automatically. In special cases, if needed, save figures in the ../pics/figure-name.ext format. Might be useful for saving gifs. Use ![](../pics/figure-name.ext) to display a static image.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nPlease avoid adding PyPlot in the (examples) project. Installing and building PyPlot dependencies takes several minutes on every CI run. Use Plots instead.","category":"page"},{"location":"contributing/new-example/","page":"Contributing to the examples","title":"Contributing to the examples","text":"note: Note\nUse make examples to run all examples or make examples specific=MyNewCoolNotebook to run any notebook that includes MyNewCoolNotebook in its file name.","category":"page"},{"location":"library/model-specification/#lib-model-specification","page":"Model specification","title":"Model specification in RxInfer","text":"","category":"section"},{"location":"library/model-specification/","page":"Model specification","title":"Model specification","text":"RxInfer.@model\nRxInfer.ModelGenerator\nRxInfer.create_model\nRxInfer.ModelInferenceOptions","category":"page"},{"location":"library/model-specification/#RxInfer.@model","page":"Model specification","title":"RxInfer.@model","text":"@model function model_name(model_arguments...; model_keyword_arguments...)\n # model description\nend\n\n@model macro generates a function that returns an equivalent graph-representation of the given probabilistic model description.\n\nSupported alias in the model specification\n\na || b: alias for OR(a, b) node (operator precedence between ||, &&, -> and ! is the same as in Julia).\na && b: alias for AND(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\na -> b: alias for IMPLY(a, b) node (operator precedence ||, &&, -> and ! is the same as in Julia).\n¬a and !a: alias for NOT(a) node (Unicode \\neg, operator precedence ||, &&, -> and ! is the same as in Julia).\na + b + c: alias for (a + b) + c\na * b * c: alias for (a * b) * c\nNormal(μ|m|mean = ..., σ²|τ⁻¹|v|var|variance = ...) alias for NormalMeanVariance(..., ...) node. Gaussian could be used instead Normal too.\nNormal(μ|m|mean = ..., τ|γ|σ⁻²|w|p|prec|precision = ...) alias for NormalMeanPrecision(..., ...) node. Gaussian could be used instead Normal too.\nMvNormal(μ|m|mean = ..., Σ|V|Λ⁻¹|cov|covariance = ...) alias for MvNormalMeanCovariance(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., Λ|W|Σ⁻¹|prec|precision = ...) alias for MvNormalMeanPrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nMvNormal(μ|m|mean = ..., τ|γ|σ⁻²|scale_diag_prec|scale_diag_precision = ...) alias for MvNormalMeanScalePrecision(..., ...) node. MvGaussian could be used instead MvNormal too.\nGamma(α|a|shape = ..., θ|β⁻¹|scale = ...) alias for GammaShapeScale(..., ...) node.\nGamma(α|a|shape = ..., β|θ⁻¹|rate = ...) alias for GammaShapeRate(..., ...) node.\n\n\n\n\n\n","category":"macro"},{"location":"library/model-specification/#RxInfer.ModelGenerator","page":"Model specification","title":"RxInfer.ModelGenerator","text":"ModelGenerator\n\nModelGenerator is a special object that is used in the infer function to lazily create model later on given constraints, meta and options.\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"library/model-specification/#RxInfer.create_model","page":"Model specification","title":"RxInfer.create_model","text":"create_model(::ModelGenerator, constraints = nothing, meta = nothing, options = nothing)\n\nCreates an instance of FactorGraphModel from the given model specification as well as optional constraints, meta and options.\n\nReturns a tuple of 2 values:\n\nan instance of FactorGraphModel\nreturn value from the @model macro function definition\n\n\n\n\n\n","category":"function"},{"location":"library/model-specification/#RxInfer.ModelInferenceOptions","page":"Model specification","title":"RxInfer.ModelInferenceOptions","text":"ModelInferenceOptions(; kwargs...)\n\nCreates model inference options object. The list of available options is present below.\n\nOptions\n\nlimit_stack_depth: limits the stack depth for computing messages, helps with StackOverflowError for some huge models, but reduces the performance of inference backend. Accepts integer as an argument that specifies the maximum number of recursive depth. Lower is better for stack overflow error, but worse for performance.\nwarn: (optional) flag to suppress warnings. Warnings are not displayed if set to false. Defaults to true.\n\nAdvanced options\n\npipeline: changes the default pipeline for each factor node in the graph\nglobal_reactive_scheduler: changes the scheduler of reactive streams, see Rocket.jl for more info, defaults to no scheduler\n\nSee also: infer\n\n\n\n\n\n","category":"type"},{"location":"manuals/getting-started/#user-guide-getting-started","page":"Getting started","title":"Getting started","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl is a Julia package for Bayesian Inference on Factor Graphs by Message Passing. It supports both exact and variational inference algorithms.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"RxInfer.jl package forms an ecosystem around three main packages: ReactiveMP.jl exports a reactive message passing based Bayesian inference engine, Rocket.jl is the core library that enables reactivity and GraphPPL.jl library simplifies model and constraints specification. ReactiveMP.jl engine is a successor of the ForneyLab package. It follows the same ideas and concepts for message-passing based inference, but uses new reactive and efficient message passing implementation under the hood. The API between two packages is different due to a better flexibility, performance and new reactive approach for solving inference problems.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"This page provides the necessary information you need to get started with Rxinfer. We will show the general approach to solving inference problems with RxInfer by means of a running example: inferring the bias of a coin.","category":"page"},{"location":"manuals/getting-started/#Installation","page":"Getting started","title":"Installation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Install RxInfer through the Julia package manager:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"] add RxInfer","category":"page"},{"location":"manuals/getting-started/#Importing-RxInfer","page":"Getting started","title":"Importing RxInfer","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"To add RxInfer package (and all associated packages) into a running Julia session simply run:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more about about using in the Using methods from RxInfer section of the documentation.","category":"page"},{"location":"manuals/getting-started/#Example:-Inferring-the-bias-of-a-coin","page":"Getting started","title":"Example: Inferring the bias of a coin","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The RxInfer approach to solving inference problems consists of three phases:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Model specification: RxInfer uses GraphPPL package for model specification part. It offers a domain-specific language to specify your probabilistic model.\nInference specification: RxInfer inference API uses ReactiveMP inference engine under the hood and has been designed to be as flexible as possible. It is compatible both with asynchronous infinite data streams and with static datasets. For most of the use cases it consists of the same simple building blocks. In this example we will show one of the many possible ways to infer your quantities of interest.\nInference execution: Given model specification and inference procedure it is pretty straightforward to use reactive API from Rocket to pass data to the inference backend and to run actual inference.","category":"page"},{"location":"manuals/getting-started/#Coin-flip-simulation","page":"Getting started","title":"Coin flip simulation","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Let's start by creating some dataset. One approach could be flipping a coin N times and recording each outcome. 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).","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"First let's setup our environment by importing all needed packages:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using RxInfer, Distributions, Random","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Next, let's define our dataset:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"rng = MersenneTwister(42)\nn = 10\np = 0.75\ndistribution = Bernoulli(p)\n\ndataset = float.(rand(rng, Bernoulli(p), n))","category":"page"},{"location":"manuals/getting-started/#getting-started-model-specification","page":"Getting started","title":"Model specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In 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.","category":"page"},{"location":"manuals/getting-started/#Likelihood","page":"Getting started","title":"Likelihood","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will assume that the outcome of each coin flip is governed by the Bernoulli distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"y_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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 01.","category":"page"},{"location":"manuals/getting-started/#Prior","page":"Getting started","title":"Prior","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"We will choose the conjugate prior of the Bernoulli likelihood function defined above, namely the beta distribution, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"theta sim Beta(a b)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"where 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. ","category":"page"},{"location":"manuals/getting-started/#Joint-probability","page":"Getting started","title":"Joint probability","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"The joint probability is given by the multiplication of the likelihood and the prior, i.e.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"P(y_1N θ) = P(θ) prod_i=1^N P(y_i θ)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Now let's see how to specify this model using GraphPPL's package syntax.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"\n# GraphPPL.jl export `@model` macro for model specification\n# It accepts a regular Julia function and builds an FFG under the hood\n@model function coin_model(n)\n\n # `datavar` creates data 'inputs' in our model\n # We will pass data later on to these inputs\n # In this example we create a sequence of inputs that accepts Float64\n y = datavar(Float64, n)\n \n # We endow θ parameter of our model with some prior\n θ ~ Beta(2.0, 7.0)\n # or, in this particular case, the `Uniform(0.0, 1.0)` prior also works:\n # θ ~ Uniform(0.0, 1.0)\n \n # We assume that outcome of each coin flip is governed by the Bernoulli distribution\n for i in 1:n\n y[i] ~ Bernoulli(θ)\n end\n \n # We return references to our data inputs and θ parameter\n # We will use these references later on during inference step\n return y, θ\nend\n","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"As you can see, RxInfer offers a model specification syntax that resembles closely to the mathematical equations defined above. We use datavar function to create \"clamped\" variables that take specific values at a later date. θ ~ Beta(2.0, 7.0) expression creates random variable θ and assigns it as an output of Beta node in the corresponding FFG. ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"note: Note\nTo quickly check the list of all available factor nodes that can be used in the model specification language call ?make_node or Base.doc(make_node).","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-specification","page":"Getting started","title":"Inference specification","text":"","category":"section"},{"location":"manuals/getting-started/#Automatic-inference-specification","page":"Getting started","title":"Automatic inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Once 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 inference function that supports static datasets.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"result = infer(\n model = coin_model(length(dataset)),\n data = (y = dataset, )\n)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = result.posteriors[:θ]","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Read more information about the inference function in the Static Inference documentation section.","category":"page"},{"location":"manuals/getting-started/#Manual-inference-specification","page":"Getting started","title":"Manual inference specification","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There is a way to manually specify an inference procedure for advanced use-cases. RxInfer API is flexible in terms of inference specification and is compatible both with real-time inference processing and with static datasets. In most of the cases for static datasets, as in our example, it consists of same basic building blocks:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Return variables of interests from model specification\nSubscribe on variables of interests posterior marginal updates\nPass data to the model\nUnsubscribe ","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here is an example of inference procedure:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"function custom_inference(data)\n n = length(data)\n\n # `coin_model` function from `@model` macro returns a reference to the model generator object\n # we need to use the `create_model` function to get actual model object\n model, (y, θ) = create_model(coin_model(n))\n \n # Reference for future posterior marginal \n mθ = nothing\n\n # `getmarginal` function returns an observable of future posterior marginal updates\n # We use `Rocket.jl` API to subscribe on this observable\n # As soon as posterior marginal update is available we just save it in `mθ`\n subscription = subscribe!(getmarginal(θ), (m) -> mθ = m)\n \n # `update!` function passes data to our data inputs\n update!(y, data)\n \n # It is always a good practice to unsubscribe and to \n # free computer resources held by the subscription\n unsubscribe!(subscription)\n \n # Here we return our resulting posterior marginal\n return mθ\nend","category":"page"},{"location":"manuals/getting-started/#getting-started-inference-execution","page":"Getting started","title":"Inference execution","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"Here after everything is ready we just call our inference function to get a posterior marginal distribution over θ parameter in the model.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated = custom_inference(dataset)","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated))\nprintln(\"std: \", std(θestimated))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"using Plots\n\nrθ = range(0, 1, length = 1000)\n\np1 = plot(rθ, (x) -> pdf(Beta(2.0, 7.0), x), title=\"Prior\", fillalpha=0.3, fillrange = 0, label=\"P(θ)\", c=1,)\np2 = plot(rθ, (x) -> pdf(θestimated, x), title=\"Posterior\", fillalpha=0.3, fillrange = 0, label=\"P(θ|y)\", c=3)\n\nplot(p1, p2, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"In our dataset we used 10 coin flips to estimate the bias of a coin. It resulted in a vague posterior distribution, however RxInfer scales very well for large models and factor graphs. We may use more coin flips in our dataset for better posterior distribution estimates:","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"dataset_100 = float.(rand(rng, Bernoulli(p), 100))\ndataset_1000 = float.(rand(rng, Bernoulli(p), 1000))\ndataset_10000 = float.(rand(rng, Bernoulli(p), 10000))\nnothing # hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"θestimated_100 = custom_inference(dataset_100)\nθestimated_1000 = custom_inference(dataset_1000)\nθestimated_10000 = custom_inference(dataset_10000)\nnothing #hide","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"p3 = plot(title = \"Posterior\", legend = :topleft)\n\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_100, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_100)\", c = 4)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_1000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_1000)\", c = 5)\np3 = plot!(p3, rθ, (x) -> pdf(θestimated_10000, x), fillalpha = 0.3, fillrange = 0, label = \"P(θ|y_10000)\", c = 6)\n\nplot(p1, p3, layout = @layout([ a; b ]))","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"With larger dataset our posterior marginal estimate becomes more and more accurate and represents real value of the bias of a coin.","category":"page"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"println(\"mean: \", mean(θestimated_10000))\nprintln(\"std: \", std(θestimated_10000))\nnothing #hide","category":"page"},{"location":"manuals/getting-started/#Where-to-go-next?","page":"Getting started","title":"Where to go next?","text":"","category":"section"},{"location":"manuals/getting-started/","page":"Getting started","title":"Getting started","text":"There are a set of examples available in RxInfer repository that demonstrate the more advanced features of the package and also Examples section in the documentation. Alternatively, you can head to the Model specification which provides more detailed information of how to use RxInfer to specify probabilistic models. Inference execution section provides a documentation about RxInfer API for running reactive Bayesian inference.","category":"page"},{"location":"manuals/debugging/#user-guide-debugging","page":"Debugging","title":"Debugging","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Debugging RxInfer can be quite challenging, mostly due to custom typing, the use of observables and Julia's stack tracing in general. Below we discuss ways to help you find problems in your model that prevents you from getting the results you want. ","category":"page"},{"location":"manuals/debugging/#Requesting-a-trace-of-messages","page":"Debugging","title":"Requesting a trace of messages","text":"","category":"section"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We have developed a way that allows us to save the history of the computations leading up to the computed messages and marginals in an inference procedure. This history is added on top of messages and marginals and is referred to as a \"Memory Addon\". Below is an example explaining how you can extract this history and use it to fix a bug.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Consider the coin toss example from earlier in the documentation. We model the binary outcome x (heads or tails) using a Bernoulli distribution, with a parameter 𝜃 that represents the probability of landing on heads. We have a Beta prior distribution for the theta parameter, with a known shape 𝑎 and rate 𝑏 parameter.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"x_i sim mathrmBernoulli(theta)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"theta sim mathrmBeta(a b)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"where x_i in 0 1 are the binary observations (heads = 1, tails = 0). This is the corresponding RxInfer model:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"using RxInfer, Random, Plots\n\nn = 4\nθ_real = 0.3\ndataset = convert.(Int64, rand(Bernoulli(θ_real), n))\n\n@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, huge)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);\n","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The model will run without errors. But when we plot the posterior distribution for theta, something's wrong. The posterior seems to be a flat distribution:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"\nrθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"We can figure out what's wrong by looking at the Memory Addon. To obtain the trace, we have to add addons = (AddonMemory(),) as an argument to the inference function.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"result = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n addons = (AddonMemory(),)\n)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now we have access to the messages that led to the marginal posterior:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Addons_messages)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"The messages in the factor graph are marked in color. If you're interested in the mathematics behind these results, consider verifying them manually using the general equation for sum-product messages:","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"underbraceoverrightarrowmu_θ(θ)_substack textoutgoing textmessage = sum_x_1ldotsx_n underbraceoverrightarrowmu_X_1(x_1)cdots overrightarrowmu_X_n(x_n)_substacktextincoming textmessages cdot underbracef(θx_1ldotsx_n)_substacktextnode textfunction","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"(Image: Graph)","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Note that the posterior (yellow) has a rate parameter on the order of 1e12. Our plot failed because a Beta distribution with such a rate parameter cannot be accurately depicted using the range of theta we used in the code block above. So why does the posterior have this rate parameter?","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"All the observations (purple, green, pink, blue) have much smaller rate parameters. It seems the prior distribution (red) has an unusual rate parameter, namely 1e12. If we look back at the model, the parameter was set to huge (which is a reserved keyword meaning 1e12). Reducing the prior rate parameter will ensure the posterior has a reasonable rate parameter as well.","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"@model function coin_model(n)\n \n # Observations\n x = datavar(Int64, n)\n \n # Prior distribution\n θ ~ Beta(4, 100)\n\n # Likelihood for each input\n for i in 1:n\n x[i] ~ Bernoulli(θ)\n end\n\nend\n\nresult = infer(\n model = coin_model(length(dataset)), \n data = (x = dataset, ),\n);","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"rθ = range(0, 1, length = 1000)\n\nplot(rθ, (rvar) -> pdf(result.posteriors[:θ], rvar), label=\"Infered posterior\")\nvline!([θ_real], label=\"Real θ\", title = \"Inference results\")","category":"page"},{"location":"manuals/debugging/","page":"Debugging","title":"Debugging","text":"Now the posterior is visible in the plot.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"This example has been auto-generated from the examples/ folder at GitHub repository.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#examples-active-inference-mountain-car","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import Pkg; Pkg.activate(\"..\"); Pkg.instantiate();","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"using RxInfer, Plots","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"A group of friends is going to a camping site that is located on the biggest mountain in the Netherlands. They use an electric car for the trip. When they are almost there, the car's battery is almost empty and is therefore limiting the engine force. Unfortunately, they are in the middle of a valley and don't have enough power to reach the camping site. Night is falling and they still need to reach the top of the mountain. As rescuers, let us develop an Active Inference (AI) agent that can get them up the hill with the limited engine power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#The-environmental-process-of-the-mountain","page":"Active Inference Mountain car","title":"The environmental process of the mountain","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Firstly, we specify the environmental process according to Ueltzhoeffer (2017) \"Deep active inference\". This process shows how the environment evolves after interacting with the agent.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Particularly, let's denote z_t = (phi_t dotphi_t) as the environmental state depending on the position phi_t and velocity dotphi_t of the car; a_t as the action of the environment on the car. Then the evolution of the state is described as follows ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndotphi_t = dotphi_t-1 + F_g(phi_t-1) + F_f(dotphi_t-1) + F_a(a_t)\nphi_t = phi_t-1 + dotphi_t \nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where F_g(phi_t-1) is the gravitational force of the hill landscape that depends on the car's position","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_g(phi) = begincases\n -005(2phi + 1) mathrmif phi 0 \n -005 left(1 + 5phi^2)^-frac12 + phi^2 (1 + 5phi^2)^-frac32 + frac116phi^4 right mathrmotherwise\nendcases","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"F_f(dotphi)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"is the friction on the car defined through the car's velocity F_f(dotphi) = -01 dotphi and F_a(a) is the engine force F_a(a) = 004 tanh(a) Since the car is on low battery, we use the tanh(cdot) function to limit the engine force to the interval [-0.04, 0.04].","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the create_physics function defines forces F_g F_f F_a; and the create_world function defines the environmental process of the mountain.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"import HypergeometricFunctions: _₂F₁\n\nfunction create_physics(; engine_force_limit = 0.04, friction_coefficient = 0.1)\n # Engine force as function of action\n Fa = (a::Real) -> engine_force_limit * tanh(a) \n\n # Friction force as function of velocity\n Ff = (y_dot::Real) -> -friction_coefficient * y_dot \n \n # Gravitational force (horizontal component) as function of position\n Fg = (y::Real) -> begin\n if y < 0\n 0.05*(-2*y - 1)\n else\n 0.05*(-(1 + 5*y^2)^(-0.5) - (y^2)*(1 + 5*y^2)^(-3/2) - (y^4)/16)\n end\n end\n \n # The height of the landscape as a function of the horizontal coordinate\n height = (x::Float64) -> begin\n if x < 0\n h = x^2 + x\n else\n h = x * _₂F₁(0.5,0.5,1.5, -5*x^2) + x^3 * _₂F₁(1.5, 1.5, 2.5, -5*x^2) / 3 + x^5 / 80\n end\n return 0.05*h\n end\n\n return (Fa, Ff, Fg,height)\nend;\n\nfunction create_world(; Fg, Ff, Fa, initial_position = -0.5, initial_velocity = 0.0)\n\n y_t_min = initial_position\n y_dot_t_min = initial_velocity\n \n y_t = y_t_min\n y_dot_t = y_dot_t_min\n \n execute = (a_t::Float64) -> begin\n # Compute next state\n y_dot_t = y_dot_t_min + Fg(y_t_min) + Ff(y_dot_t_min) + Fa(a_t)\n y_t = y_t_min + y_dot_t\n \n # Reset state for next step\n y_t_min = y_t\n y_dot_t_min = y_dot_t\n end\n \n observe = () -> begin \n return [y_t, y_dot_t]\n end\n \n return (execute, observe)\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_world (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Let's visualize the mountain landscape and the situation of the car. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"engine_force_limit = 0.04\nfriction_coefficient = 0.1\n\nFa, Ff, Fg, height = create_physics(\n engine_force_limit = engine_force_limit,\n friction_coefficient = friction_coefficient\n);\ninitial_position = -0.5\ninitial_velocity = 0.0\n\nx_target = [0.5, 0.0] \n\nvalley_x = range(-2, 2, length=400)\nvalley_y = [ height(xs) for xs in valley_x ]\nplot(valley_x, valley_y, title = \"Mountain valley\", label = \"Landscape\", color = \"black\")\nscatter!([ initial_position ], [ height(initial_position) ], label=\"initial car position\") \nscatter!([x_target[1]], [height(x_target[1])], label=\"camping site\")","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Naive-approach","page":"Active Inference Mountain car","title":"Naive approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Well, let's see how our friends were struggling with the low-battery car when they tried to get it to the camping site before we come to help. They basically used the brute-force method, i.e. just pushing the gas pedal for full power.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"N_naive = 100 # Total simulation time\npi_naive = 100.0 * ones(N_naive) # Naive policy for right full-power only\n\n# Let there be a world\n(execute_naive, observe_naive) = create_world(; \n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n);\n\ny_naive = Vector{Vector{Float64}}(undef, N_naive)\nfor t = 1:N_naive\n execute_naive(pi_naive[t]) # Execute environmental process\n y_naive[t] = observe_naive() # Observe external states\nend\n\nanimation_naive = @animate for i in 1:N_naive\n plot(valley_x, valley_y, title = \"Naive policy\", label = \"Landscape\", color = \"black\", size = (800, 400))\n scatter!([y_naive[i][1]], [height(y_naive[i][1])], label=\"car\")\n scatter!([x_target[1]], [height(x_target[1])], label=\"goal\") \nend\n\n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_naive, \"../pics/ai-mountain-car-naive.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"They failed as expected since the car doesn't have enough power. This helps to understand that the brute-force approach is not the most efficient one in this case and hopefully a bit of swinging is necessary to achieve the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Active-inference-approach","page":"Active Inference Mountain car","title":"Active inference approach","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now let's help them solve the problem with an active inference approach. Particularly, we create an agent that predicts the future car position as well as the best possible actions in a probabilistic manner.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We start by specifying a probabilistic model for the agent that describes the agent's internal beliefs over the external dynamics of the environment. The generative model is defined as follows","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned\np_t(xsu) propto p(s_t-1) prod_k=t^t+T p(x_k mid s_k) p(s_k mid s_k-1u_k) p(u_k) p(x_k) nonumber\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where the factors are defined as","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k) = mathcalN(x_k mid x_goalV_goal) quad (mathrmtarget)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_k mid s_k-1u_k) = mathcalN(s_k mid tildeg(s_k-1)+h(u_k)gamma^-1) quad (mathrmstate transition)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(x_k mid s_k) = mathcalN(x_k mid s_ktheta) quad (mathrmobservation)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(u_k) = mathcalN(u_k mid m_uV_u) quad (mathrmcontrol)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"p(s_t-1) = mathcalN(s_t-1 mid m_t-1V_t-1) quad (mathrmprevious state)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"where ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"x\ndenotes observations of the agent after interacting with the environment; \ns_t = (s_tdots_t)\nis the state of the car embodying its position and velocity; \nu_t\ndenotes the control state of the agent; \nh(cdot)\nis the tanh(cdot) function modeling engine control; \ntildeg(cdot)\nexecutes a linear approximation of equations (1) and (2): ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"beginaligned \ndots_t = dots_t-1 + F_g(s_t-1) + F_f(dots_t-1)\ns_t = s_t-1 + dots_t\nendaligned","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, the @model macro and the meta blocks are used to define the probabilistic model and the approximation methods for the nonlinear state-transition functions, respectively. In addition, the beliefs over the future states (up to T steps ahead) of the agent is included.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"@model function mountain_car(; T, Fg, Fa, Ff, engine_force_limit)\n \n # Transition function modeling transition due to gravity and friction\n g = (s_t_min::AbstractVector) -> begin \n s_t = similar(s_t_min) # Next state\n s_t[2] = s_t_min[2] + Fg(s_t_min[1]) + Ff(s_t_min[2]) # Update velocity\n s_t[1] = s_t_min[1] + s_t[2] # Update position\n return s_t\n end\n \n # Function for modeling engine control\n h = (u::AbstractVector) -> [0.0, Fa(u[1])] \n \n # Inverse engine force, from change in state to corresponding engine force\n h_inv = (delta_s_dot::AbstractVector) -> [atanh(clamp(delta_s_dot[2], -engine_force_limit+1e-3, engine_force_limit-1e-3)/engine_force_limit)] \n \n # Internal model perameters\n Gamma = 1e4*diageye(2) # Transition precision\n Theta = 1e-4*diageye(2) # Observation variance\n \n m_s_t_min = datavar(Vector{Float64})\n V_s_t_min = datavar(Matrix{Float64})\n\n s_t_min ~ MvNormal(mean = m_s_t_min, cov = V_s_t_min)\n s_k_min = s_t_min\n \n m_u = datavar(Vector{Float64}, T)\n V_u = datavar(Matrix{Float64}, T)\n \n m_x = datavar(Vector{Float64}, T)\n V_x = datavar(Matrix{Float64}, T)\n \n u = randomvar(T)\n s = randomvar(T)\n x = randomvar(T)\n \n u_h_k = randomvar(T)\n s_g_k = randomvar(T)\n u_s_sum = randomvar(T)\n \n for k in 1:T\n u[k] ~ MvNormal(mean = m_u[k], cov = V_u[k])\n u_h_k[k] ~ h(u[k]) where { meta = DeltaMeta(method = Linearization(), inverse = h_inv) }\n s_g_k[k] ~ g(s_k_min) where { meta = DeltaMeta(method = Linearization()) }\n u_s_sum[k] ~ s_g_k[k] + u_h_k[k]\n s[k] ~ MvNormal(mean = u_s_sum[k], precision = Gamma)\n x[k] ~ MvNormal(mean = s[k], cov = Theta)\n x[k] ~ MvNormal(mean = m_x[k], cov = V_x[k]) # goal\n s_k_min = s[k]\n end\n \n return (s, )\nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"After specifying the generative model, let's create an Active Inference(AI) agent for the car. Technically, the agent goes through three phases: Act-Execute-Observe, Infer and Slide.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Act-Execute-Observe: In this phase, the agent performs an action onto the environment at time t and gets T observations in exchange. These observations are basically the prediction of the agent on how the environment evolves over the next T time step. \nInfer: After receiving observations, the agent starts updating its internal probabilistic model by doing inference. Particularly, it finds the posterior distributions over the state s_t and control u_t, i.e. p(s_tmid x_t) and p(u_tmid x_t).\nSlide: After updating its internal belief, the agent moves to the next time step and uses the inferred action u_t in the previous time step to interact with the environment. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"In the cell below, we create the agent through the create_agent function, which includes compute, act, slide and future functions:","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The act function selects the next action based on the inferred policy. On the other hand, the future function predicts the next T positions based on the current action. These two function implement the Act-Execute-Observe phase.\nThe compute function infers the policy (which is a set of actions for the next T time steps) and the agent's state using the agent internal model. This function implements the Infer phase. We call it compute to avoid the clash with the infer function of RxInfer.jl.\nThe slide function implements the Slide phase, which moves the agent internal model to the next time step.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"# We are going to use some private functionality from ReactiveMP, \n# in the future we should expose a proper API for this\nimport RxInfer.ReactiveMP: getrecent, messageout\n\nfunction create_agent(; T = 20, Fg, Fa, Ff, engine_force_limit, x_target, initial_position, initial_velocity)\n Epsilon = fill(huge, 1, 1) # Control prior variance\n m_u = Vector{Float64}[ [ 0.0] for k=1:T ] # Set control priors\n V_u = Matrix{Float64}[ Epsilon for k=1:T ]\n\n Sigma = 1e-4*diageye(2) # Goal prior variance\n m_x = [zeros(2) for k=1:T]\n V_x = [huge*diageye(2) for k=1:T]\n V_x[end] = Sigma # Set prior to reach goal at t=T\n\n # Set initial brain state prior\n m_s_t_min = [initial_position, initial_velocity] \n V_s_t_min = tiny * diageye(2)\n \n # Set current inference results\n result = nothing\n\n # The `infer` function is the heart of the agent\n # It calls the `RxInfer.inference` function to perform Bayesian inference by message passing\n compute = (upsilon_t::Float64, y_hat_t::Vector{Float64}) -> begin\n m_u[1] = [ upsilon_t ] # Register action with the generative model\n V_u[1] = fill(tiny, 1, 1) # Clamp control prior to performed action\n\n m_x[1] = y_hat_t # Register observation with the generative model\n V_x[1] = tiny*diageye(2) # Clamp goal prior to observation\n\n data = Dict(:m_u => m_u, \n :V_u => V_u, \n :m_x => m_x, \n :V_x => V_x,\n :m_s_t_min => m_s_t_min,\n :V_s_t_min => V_s_t_min)\n \n model = mountain_car(; T = T, Fg = Fg, Fa = Fa, Ff = Ff, engine_force_limit = engine_force_limit) \n result = infer(model = model, data = data)\n end\n \n # The `act` function returns the inferred best possible action\n act = () -> begin\n if result !== nothing\n return mode(result.posteriors[:u][2])[1]\n else\n return 0.0 # Without inference result we return some 'random' action\n end\n end\n \n # The `future` function returns the inferred future states\n future = () -> begin \n if result !== nothing \n return getindex.(mode.(result.posteriors[:s]), 1)\n else\n return zeros(T)\n end\n end\n\n # The `slide` function modifies the `(m_s_t_min, V_s_t_min)` for the next step\n # and shifts (or slides) the array of future goals `(m_x, V_x)` and inferred actions `(m_u, V_u)`\n slide = () -> begin\n (s, ) = result.returnval\n \n slide_msg_idx = 3 # This index is model dependend\n (m_s_t_min, V_s_t_min) = mean_cov(getrecent(messageout(s[2], slide_msg_idx)))\n\n m_u = circshift(m_u, -1)\n m_u[end] = [0.0]\n V_u = circshift(V_u, -1)\n V_u[end] = Epsilon\n\n m_x = circshift(m_x, -1)\n m_x[end] = x_target\n V_x = circshift(V_x, -1)\n V_x[end] = Sigma\n end\n\n return (compute, act, slide, future) \nend","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"create_agent (generic function with 1 method)","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now it's time to see if we can help our friends arrive at the camping site by midnight?","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(execute_ai, observe_ai) = create_world(\n Fg = Fg, Ff = Ff, Fa = Fa, \n initial_position = initial_position, \n initial_velocity = initial_velocity\n) # Let there be a world\n\nT_ai = 50\n\n(compute_ai, act_ai, slide_ai, future_ai) = create_agent(; # Let there be an agent\n T = T_ai, \n Fa = Fa,\n Fg = Fg, \n Ff = Ff, \n engine_force_limit = engine_force_limit,\n x_target = x_target,\n initial_position = initial_position,\n initial_velocity = initial_velocity\n) \n\nN_ai = 100\n\n# Step through experimental protocol\nagent_a = Vector{Float64}(undef, N_ai) # Actions\nagent_f = Vector{Vector{Float64}}(undef, N_ai) # Predicted future\nagent_x = Vector{Vector{Float64}}(undef, N_ai) # Observations\n\nfor t=1:N_ai\n agent_a[t] = act_ai() # Invoke an action from the agent\n agent_f[t] = future_ai() # Fetch the predicted future states\n execute_ai(agent_a[t]) # The action influences hidden external states\n agent_x[t] = observe_ai() # Observe the current environmental outcome (update p)\n compute_ai(agent_a[t], agent_x[t]) # Infer beliefs from current model state (update q)\n slide_ai() # Prepare for next iteration\nend\n\nanimation_ai = @animate for i in 1:N_ai\n # pls - plot landscape\n pls = plot(valley_x, valley_y, title = \"Active inference results\", label = \"Landscape\", color = \"black\")\n pls = scatter!(pls, [agent_x[i][1]], [height(agent_x[i][1])], label=\"car\")\n pls = scatter!(pls, [x_target[1]], [height(x_target[1])], label=\"goal\") \n pls = scatter!(pls, agent_f[i], height.(agent_f[i]), label = \"Predicted future\", alpha = map(i -> 0.5 / i, 1:T_ai))\n \n # pef - plot engine force\n pef = plot(Fa.(agent_a[1:i]), title = \"Engine force (agents actions)\", xlim = (0, N_ai), ylim = (-0.05, 0.05))\n \n plot(pls, pef, size = (800, 400))\nend\n \n# The animation is saved and displayed as markdown picture for the automatic HTML generation\ngif(animation_ai, \"../pics/ai-mountain-car-ai.gif\", fps = 24, show_msg = false);","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"(Image: )","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Voila! The car now is able to reach the camping site with a smart strategy.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"The left figure shows the agent reached its goal by swinging and the right one shows the corresponding engine force. As we can see, at the beginning the agent tried to reach the goal directly (with full engine force) but after some trials it realized that's not possible. Since the agent looks ahead for 50 time steps, it has enough time to explore other policies, helping it learn to move back to get more momentum to reach the goal.","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"Now our friends can enjoy their trip at the camping site!. ","category":"page"},{"location":"examples/advanced_examples/Active Inference Mountain car/#Reference","page":"Active Inference Mountain car","title":"Reference","text":"","category":"section"},{"location":"examples/advanced_examples/Active Inference Mountain car/","page":"Active Inference Mountain car","title":"Active Inference Mountain car","text":"We refer reader to the Thijs van de Laar (2019) \"Simulating active inference processes by message passing\" original paper with more in-depth overview and explanation of the active inference agent implementation by message passing. The original environment/task description is from Ueltzhoeffer (2017) \"Deep active inference\".","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-free-energy","page":"Bethe Free Energy","title":"Bethe Free Energy implementation in RxInfer","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The following text introduces the Bethe Free Energy. We start be defining a factorized model and move from the Variational Free Energy to a definition of the Bethe Free Energy.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-factorized-model","page":"Bethe Free Energy","title":"Factorized model","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Before we can define a model, we must identify all variables that are relevant to the problem at hand. We distinguish between variables that can be directly observed, y = (y_1 dots y_j dots y_m) and variables that can not be observed directly, also known as latent variables, x = (x_1 dots x_i dots x_n) We then define a model that factorizes over consituent smaller factors (functions), as f(yx) = prod_a f_a(y_ax_a)","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Individual factors may represent stochastic functions, such as conditional or prior distributions, but also potential functions or deterministic relationships. A factor may depend on multiple observed and/or latent variables (or none).","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-vfe","page":"Bethe Free Energy","title":"Variational Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Variational Free Energy (VFE) then defines a functional objective that includes the model and a variational distribution over the latent variables, Fq(haty) = mathbbE_q(x)leftlog fracq(x)f(y=haty x) right A functional defines a function of a function that returns a scalar. Here, the VFE is a function of the variational distribution (as indicated by square brackets) and returns a number.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The VFE is also a function of the observed data, as indicated by round brackets, where the data are substituted in the factorized model.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-variational-inference","page":"Bethe Free Energy","title":"Variational inference","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The goal of variational inference is to find a variational distibution that minimizes the VFE, q^*(x) = argmin_qinmathcalQ Fq(haty) This objective can be optimized (under specific constraints) with the use of variational calculus. Constraints are implied by the domain over which the variational distribution is optimized, and can be enforced by Lagrange multipliers.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For the VFE, constraints enforce e.g. the normalization of the variational distribution. The variational distribution that minimizes the VFE then approximates the true (but often unobtainable) posterior distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-approximation","page":"Bethe Free Energy","title":"Bethe approximation","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Optimization of the VFE is still a daunting task, because the variational distribution is a joint distribution over possibly many latent variables. Instead of optimizing the joint variational distribution directly, a factorized variational distribution is often chosen. The factorized variational distribution is then optimized for its constituent factors.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"A popular choice of factorization is the Bethe approximation, which is constructed from the factorization of the model itself, q(x) triangleq fracprod_a q_a(x_a)prod_i q_i(x_i)^d_i - 1 The numerator iterates over the factors in the model, and carves the joint variational distribution in smaller variational distributions that are more manageable to optimize.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The denominator of the Bethe approximation iterates over all individual latent variables and discounts them. The discounting factor is chosen as the degree of the variable minus one, where the degree counts the number of factors in which the variable appears.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe approximation thus constrains the variational distribution to a factorized form. However, the true posterior distribution might not factorize in this way, e.g. if the grapical representation of the model contains cycles. In these cases the Bethe approximation trades the exact solution for computational tractability.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-bfe","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"The Bethe Free Energy (BFE) substitutes the Bethe approximation in the VFE, which then fragments over factors and variables, as F_Bq(haty) = sum_a U_aq_a(haty_a) - sum_a Hq_a + sum_i (d_i - 1) Hq_i The first term of the BFE specifies an average energy, U_aq_a(haty_a) = -mathbbE_q_a(x_a)leftlog f_a(y_a=haty_a x_a)right which internalizes the factors of the model. The last two terms specify entropies.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Crucially, the BFE can be iteratively optimized for each individual variational distribution in turn. Optimization of the BFE is thus more manageable than direct optimization of the VFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For iterative optimization of the BFE, the variational distributions must first be initialized. The initmarginals keyword argument to the infer function initializes the variational distributions of the BFE.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"For disambiguation, note that the initialization of the variational distribution is a different design consideration than the choice of priors. A prior specifies a factor in the model definition, while initialization concerns factors in the variational distribution.","category":"page"},{"location":"library/bethe-free-energy/#lib-bethe-further-reading","page":"Bethe Free Energy","title":"Further reading","text":"","category":"section"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"Pearl (1986) on the original foundations of Bayesian networks and belief propagation;\nYedidia et al. (2005) on the connections between belief propagation and regional approximations to the VFE;\nDauwels (2007) on variational message passing on Forney-style factor graphs (FFGs);\nSenoz et al. (2021) on constraint manipulation and message passing on FFGs.","category":"page"},{"location":"library/bethe-free-energy/","page":"Bethe Free Energy","title":"Bethe Free Energy","text":"RxInfer.AbstractScoreObjective\nRxInfer.BetheFreeEnergy\nRxInfer.apply_diagnostic_check\nRxInfer.BetheFreeEnergyCheckNaNs\nRxInfer.BetheFreeEnergyCheckInfs","category":"page"},{"location":"library/bethe-free-energy/#RxInfer.AbstractScoreObjective","page":"Bethe Free Energy","title":"RxInfer.AbstractScoreObjective","text":"AbstractScoreObjective\n\nAbstract type for functional objectives that can be used in the score function. \n\nnote: Note\n\n\nscore is defined in the ReactiveMP package.\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergy","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergy","text":"BetheFreeEnergy(marginal_skip_strategy, scheduler, diagnostic_checks)\n\nCreates Bethe Free Energy values stream when passed to the score function. \n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.apply_diagnostic_check","page":"Bethe Free Energy","title":"RxInfer.apply_diagnostic_check","text":"apply_diagnostic_check(check, context, stream)\n\nThis function applies a check to the stream. Accepts optional context object for custom error messages.\n\n\n\n\n\n","category":"function"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckNaNs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckNaNs","text":"BetheFreeEnergyCheckNaNs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return NaNs. Throws an error if finds NaN. \n\nSee also: BetheFreeEnergyCheckInfs\n\n\n\n\n\n","category":"type"},{"location":"library/bethe-free-energy/#RxInfer.BetheFreeEnergyCheckInfs","page":"Bethe Free Energy","title":"RxInfer.BetheFreeEnergyCheckInfs","text":"BetheFreeEnergyCheckInfs\n\nIf enabled checks that both variable and factor bound score functions in Bethe Free Energy computation do not return Infs. Throws an error if finds Inf. \n\nSee also: BetheFreeEnergyCheckNaNs\n\n\n\n\n\n","category":"type"},{"location":"manuals/background/#intro-background-variational-inference","page":"Background: variational inference","title":"Background: variational inference","text":"","category":"section"}] +} diff --git a/v2.16.2/siteinfo.js b/v2.16.2/siteinfo.js new file mode 100644 index 000000000..d88daad44 --- /dev/null +++ b/v2.16.2/siteinfo.js @@ -0,0 +1 @@ +var DOCUMENTER_CURRENT_VERSION = "v2.16.2"; diff --git a/versions.js b/versions.js new file mode 100644 index 000000000..2683ee219 --- /dev/null +++ b/versions.js @@ -0,0 +1,8 @@ +var DOC_VERSIONS = [ + "stable", + "v2.16", + "v2.15", + "dev", +]; +var DOCUMENTER_NEWEST = "v2.16.2"; +var DOCUMENTER_STABLE = "stable";